Merge pull request 'MIL-003: Add console interface' (#32) from mil-003-console-interface into main

Reviewed-on: #32

.gitignore

@@ -173,3 +173,6 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+
+# Doxygen output
+docs/doxygen/

Doxyfile

@@ -0,0 +1,16 @@
+# Doxygen configuration for the console calculator.
+# Generate the API documentation with:  doxygen Doxyfile
+PROJECT_NAME           = "Calculator"
+PROJECT_BRIEF          = "Console calculator (Udemy 100 Days of Code, day 10)"
+OUTPUT_DIRECTORY       = docs/doxygen
+INPUT                  = src
+FILE_PATTERNS          = *.py
+RECURSIVE              = YES
+OPTIMIZE_OUTPUT_JAVA   = YES
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+QUIET                  = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_NO_PARAMDOC       = YES

pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "calc"
+version = "0.1.0"
+description = "A console calculator (Udemy 100 Days of Code, day 10)."
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "AGPL-3.0-or-later" }
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+calc = "calc.calculator:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

src/calc/__init__.py

@@ -0,0 +1,4 @@
+"""!
+@file __init__.py
+@brief Console calculator package (Udemy 100 Days of Code, day 10).
+"""

src/calc/__main__.py

@@ -0,0 +1,9 @@
+"""!
+@file __main__.py
+@brief Allows running the calculator with `python -m calc`.
+"""
+
+from calc.calculator import main
+
+if __name__ == "__main__":
+    main()

src/calc/calculator.py

@@ -0,0 +1,112 @@
+"""!
+@file calculator.py
+@brief The interactive console calculator.
+"""
+
+from calc.constants import (
+    ANSWER_CONTINUE,
+    ANSWER_NEW,
+    ANSWER_QUIT,
+    ASCII_TITLE,
+    MESSAGE_DIVIDE_BY_ZERO,
+    MESSAGE_GOODBYE,
+    MESSAGE_INVALID_ANSWER,
+    MESSAGE_INVALID_NUMBER,
+    MESSAGE_INVALID_OPERATION,
+    PROMPT_AGAIN,
+    PROMPT_FIRST_NUMBER,
+    PROMPT_NEXT_NUMBER,
+    PROMPT_OPERATION,
+)
+from calc.operations import OPERATIONS
+
+
+def format_number(value: float) -> str:
+    """!
+    @brief Format a number without a trailing ".0" for whole values.
+    @param value The number to format.
+    @return The text to show the user.
+    """
+    return str(int(value)) if value.is_integer() else str(value)
+
+
+def read_number(prompt: str) -> float:
+    """!
+    @brief Ask for a number until the user types a valid one.
+    @param prompt The text shown to the user.
+    @return The number typed by the user.
+    """
+    while True:
+        try:
+            return float(input(prompt))
+        except ValueError:
+            print(MESSAGE_INVALID_NUMBER)
+
+
+def read_operation() -> str:
+    """!
+    @brief Show the available operations and ask for one until it is valid.
+    @return The symbol of the chosen operation, a key of OPERATIONS.
+    """
+    for symbol in OPERATIONS:
+        print(symbol)
+    while True:
+        symbol = input(PROMPT_OPERATION).strip()
+        if symbol in OPERATIONS:
+            return symbol
+        print(MESSAGE_INVALID_OPERATION)
+
+
+def read_answer(result: float) -> str:
+    """!
+    @brief Ask whether to continue with the result, start anew or quit.
+    @param result The result of the last calculation.
+    @return One of ANSWER_CONTINUE, ANSWER_NEW or ANSWER_QUIT.
+    """
+    while True:
+        answer = input(PROMPT_AGAIN.format(result=format_number(result)))
+        answer = answer.strip().lower()
+        if answer in (ANSWER_CONTINUE, ANSWER_NEW, ANSWER_QUIT):
+            return answer
+        print(MESSAGE_INVALID_ANSWER)
+
+
+def calculator() -> None:
+    """!
+    @brief Run one calculation session.
+
+    The user may continue with the previous result. Starting a new
+    calculation calls this function again (recursion), which gives a clean
+    restart. A division by zero also restarts the calculator.
+    """
+    num1 = read_number(PROMPT_FIRST_NUMBER)
+    while True:
+        symbol = read_operation()
+        num2 = read_number(PROMPT_NEXT_NUMBER)
+        try:
+            result = OPERATIONS[symbol](num1, num2)
+        except ZeroDivisionError:
+            print(MESSAGE_DIVIDE_BY_ZERO)
+            calculator()
+            return
+        print(
+            f"{format_number(num1)} {symbol} {format_number(num2)} "
+            f"= {format_number(result)}"
+        )
+        answer = read_answer(result)
+        if answer == ANSWER_CONTINUE:
+            num1 = result
+        elif answer == ANSWER_NEW:
+            calculator()
+            return
+        else:
+            print(MESSAGE_GOODBYE)
+            return
+
+
+def main() -> None:
+    """!
+    @brief Program entry point: show the ASCII title and start the calculator.
+    """
+    print(ASCII_TITLE)
+    calculator()

src/calc/constants.py

@@ -0,0 +1,48 @@
+"""!
+@file constants.py
+@brief Constants used by the console calculator.
+"""
+
+## Operation symbols, in the order they are offered to the user.
+SYMBOL_ADD: str = "+"
+SYMBOL_SUBTRACT: str = "-"
+SYMBOL_MULTIPLY: str = "*"
+SYMBOL_DIVIDE: str = "/"
+
+## Answers accepted after a calculation.
+ANSWER_CONTINUE: str = "y"
+ANSWER_NEW: str = "n"
+ANSWER_QUIT: str = "q"
+
+## Prompts and messages shown to the user.
+PROMPT_FIRST_NUMBER: str = "What's the first number?: "
+PROMPT_NEXT_NUMBER: str = "What's the next number?: "
+PROMPT_OPERATION: str = "Pick an operation: "
+PROMPT_AGAIN: str = (
+    f"Type '{ANSWER_CONTINUE}' to continue calculating with {{result}}, "
+    f"'{ANSWER_NEW}' to start a new calculation, "
+    f"or '{ANSWER_QUIT}' to quit: "
+)
+MESSAGE_INVALID_NUMBER: str = "That is not a number, please try again."
+MESSAGE_INVALID_OPERATION: str = "That is not a valid operation, please try again."
+MESSAGE_INVALID_ANSWER: str = "Please answer with one of the listed letters."
+MESSAGE_DIVIDE_BY_ZERO: str = "You cannot divide by zero."
+MESSAGE_GOODBYE: str = "Goodbye!"
+
+## ASCII title shown at start: a calculator with the lettering to its right.
+ASCII_TITLE: str = r"""
+ _____________________
+|  _________________  |
+| |               0 | |
+| |_________________| |
+|  ___ ___ ___   ___  |     ____        _            _       _
+| | 7 | 8 | 9 | | + | |    / ___|__ _  | | ___ _   _| | __ _| |_ ___  _ __
+| |___|___|___| |___| |   | |   / _` | | |/ __| | | | |/ _` | __/ _ \| '__|
+| | 4 | 5 | 6 | | - | |   | |__| (_| | | | (__| |_| | | (_| | || (_) | |
+| |___|___|___| |___| |    \____\__,_| |_|\___|\__,_|_|\__,_|\__\___/|_|
+| | 1 | 2 | 3 | | x | |
+| |___|___|___| |___| |
+| | . | 0 | = | | / | |
+| |___|___|___| |___| |
+|_____________________|
+"""

src/calc/operations.py

@@ -0,0 +1,63 @@
+"""!
+@file operations.py
+@brief Arithmetic operations and the dictionary that maps symbols to them.
+"""
+
+from collections.abc import Callable
+
+from calc.constants import (
+    SYMBOL_ADD,
+    SYMBOL_DIVIDE,
+    SYMBOL_MULTIPLY,
+    SYMBOL_SUBTRACT,
+)
+
+
+def add(n1: float, n2: float) -> float:
+    """!
+    @brief Add two numbers.
+    @param n1 The first number.
+    @param n2 The second number.
+    @return The sum of @p n1 and @p n2.
+    """
+    return n1 + n2
+
+
+def subtract(n1: float, n2: float) -> float:
+    """!
+    @brief Subtract the second number from the first.
+    @param n1 The first number.
+    @param n2 The second number.
+    @return The difference @p n1 minus @p n2.
+    """
+    return n1 - n2
+
+
+def multiply(n1: float, n2: float) -> float:
+    """!
+    @brief Multiply two numbers.
+    @param n1 The first number.
+    @param n2 The second number.
+    @return The product of @p n1 and @p n2.
+    """
+    return n1 * n2
+
+
+def divide(n1: float, n2: float) -> float:
+    """!
+    @brief Divide the first number by the second.
+    @param n1 The dividend.
+    @param n2 The divisor.
+    @return The quotient @p n1 divided by @p n2.
+    @throws ZeroDivisionError When @p n2 is zero.
+    """
+    return n1 / n2
+
+
+## Maps an operation symbol to its function. The functions are stored, not called.
+OPERATIONS: dict[str, Callable[[float, float], float]] = {
+    SYMBOL_ADD: add,
+    SYMBOL_SUBTRACT: subtract,
+    SYMBOL_MULTIPLY: multiply,
+    SYMBOL_DIVIDE: divide,
+}

tests/test_calculator.py

@@ -0,0 +1,79 @@
+"""!
+@file test_calculator.py
+@brief Tests for the interactive calculator loop.
+"""
+
+import pytest
+
+from calc.calculator import calculator, format_number, main
+
+
+def feed(monkeypatch: pytest.MonkeyPatch, answers: list[str]) -> None:
+    """!
+    @brief Make input() return the given answers in order.
+    @param monkeypatch The pytest monkeypatch fixture.
+    @param answers The lines the "user" types.
+    """
+    lines = iter(answers)
+    monkeypatch.setattr("builtins.input", lambda _prompt="": next(lines))
+
+
+def test_format_number_drops_trailing_zero() -> None:
+    assert format_number(5.0) == "5"
+    assert format_number(2.5) == "2.5"
+
+
+def test_calculator_adds_then_quits(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    feed(monkeypatch, ["2", "+", "3", "q"])
+    calculator()
+    assert "2 + 3 = 5" in capsys.readouterr().out
+
+
+def test_calculator_continues_with_previous_result(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    feed(monkeypatch, ["2", "+", "3", "y", "*", "4", "q"])
+    calculator()
+    assert "5 * 4 = 20" in capsys.readouterr().out
+
+
+def test_calculator_starts_new_calculation(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    feed(monkeypatch, ["2", "+", "3", "n", "10", "/", "4", "q"])
+    calculator()
+    assert "10 / 4 = 2.5" in capsys.readouterr().out
+
+
+def test_calculator_reprompts_on_invalid_input(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    feed(monkeypatch, ["abc", "1", "^", "+", "x", "1", "?", "q"])
+    calculator()
+    out = capsys.readouterr().out
+    assert "not a number" in out
+    assert "not a valid operation" in out
+    assert "Please answer" in out
+    assert "1 + 1 = 2" in out
+
+
+def test_calculator_restarts_after_division_by_zero(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    feed(monkeypatch, ["1", "/", "0", "6", "-", "1", "q"])
+    calculator()
+    out = capsys.readouterr().out
+    assert "cannot divide by zero" in out
+    assert "6 - 1 = 5" in out
+
+
+def test_main_shows_ascii_art(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    feed(monkeypatch, ["1", "+", "1", "q"])
+    main()
+    out = capsys.readouterr().out
+    assert "|_____________________|" in out
+    assert "Goodbye!" in out

tests/test_operations.py

@@ -0,0 +1,33 @@
+"""!
+@file test_operations.py
+@brief Tests for the arithmetic operations.
+"""
+
+import pytest
+
+from calc.operations import OPERATIONS, add, divide, multiply, subtract
+
+
+def test_add_returns_sum() -> None:
+    assert add(2, 3) == 5
+
+
+def test_subtract_returns_difference() -> None:
+    assert subtract(2, 3) == -1
+
+
+def test_multiply_returns_product() -> None:
+    assert multiply(4, 2.5) == 10
+
+
+def test_divide_returns_quotient() -> None:
+    assert divide(9, 3) == 3
+
+
+def test_divide_when_divisor_is_zero() -> None:
+    with pytest.raises(ZeroDivisionError):
+        divide(1, 0)
+
+
+def test_operations_maps_symbols_to_functions() -> None:
+    assert OPERATIONS == {"+": add, "-": subtract, "*": multiply, "/": divide}