Python License Status

Calculator (Python CLI Project)

Created and maintained by Fbarquez

An educational project built in Python that demonstrates how to create a real console-based calculator using clear, structured, and testable code.

Terminal Output Preview

screenshot 1
screenshot 2

Supported Operations

Operation Function Name Example Input
Addition add(a, b) 2 + 3
Subtraction subtract(a, b) 7 - 2
Multiplication multiply(a, b) 4 * 5
Division divide(a, b) 9 / 3
Square Root square_root(a) sqrt(16)
Modulo modulo(a, b) 10 % 3
Power power(a, b) 2 ** 4
Percentage percentage(a, b) 30% of 200
Factorial factorial(a) factorial(5)
Full Expressions evaluate(expr) 2 + 3*(5 - 1)

What is a Python CLI Project?

A Python CLI project is a program that runs in the terminal (also called the console or command line). It does not have buttons or graphical elements—users interact with it by typing commands and reading text responses.

Example: git, pip install, or typing python3 script.py in the terminal.

This calculator works entirely this way.

What can this calculator do?

This project simulates a real calculator but in a text-only format. It allows you to:

Project Structure

Just like in real-world programming, this project is split into multiple Python files to keep everything clean and organized:

calculator/
├── main.py               ← Main program: shows the menu and handles user input
├── operations.py         ← Math functions: add, divide, etc.
├── utils.py              ← Utility helpers: show menu, clear screen, validate input
├── test_operations.py    ← Automated tests to verify that functions work
├── history.json          ← File to store calculation history
└── README.md             ← This document

Tools and Libraries Used

Built-in Python Libraries

math

Allows mathematical operations like square root (sqrt) and factorial.

json

Used to store and read data in a human-readable file (history.json).

External Library

colorama

Adds colors to text in the terminal (e.g., green for results, red for errors).

Install it with:

pip install colorama

File-by-File Explanation

1. main.py — The Main Program

This is where the program starts. It shows the user a menu, asks what they want to do, and calls the right function.

Key imports:

from utils import show_menu, get_number, save_history, load_history, clear_screen
from operations import *
from colorama import Fore, Style, init
import math

Core Logic:

2. operations.py — Math Functions

Contains one function for each type of math calculation:

def add(a, b): return a + b
def divide(a, b): return "Error: Division by zero" if b == 0 else a / b

3. utils.py — Helper Functions

These don't calculate math but improve usability:

def show_menu()
def get_number(prompt)
def save_history(entry)
def load_history()
def clear_screen()

4. test_operations.py — Automatic Testing

This file uses Python’s unittest module to test whether math functions return correct results:

import unittest
from operations import *

class TestCalculator(unittest.TestCase):
    def test_add(self): ...
    def test_divide_zero(self): ...

Run the tests like this:

python3 test_operations.py

If everything works, you’ll see confirmation. If not, it will tell you which test failed.

How Does It All Work Together?

  1. Start the program:

    python3 main.py

  2. The menu appears:

    === CALCULATOR ===
1. Basic Operations
2. Advanced Operations
3. Evaluate Expression
4. View History
5. Exit

  3. You choose an option (e.g., 2 for advanced operations)

  4. The program walks you through: it asks for numbers, calculates, shows the result, and logs it

  5. Option 5 exits the program cleanly

Run Tests

To check that the functions behave correctly, run:

python3 test_operations.py

Example result:

.....
----------------------------------------------------------------------
Ran 5 tests in 0.001s

OK

Feature Roadmap

Educational Value

This project is ideal for learning:

Requirements

License

This project is licensed under the MIT License © 2025 Fbarquez.
You are free to use, modify, and distribute this code, but attribution is required.
Any copy or derivative work must keep the original author's credit visible.

Want to contribute or report issues? Contact Fbarquez or open a Github issue