calckit-kabanda 0.1.0__tar.gz

calckit_kabanda-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Verify metadata
+        run: python -m pip install twine && python -m twine check dist/*
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

calckit_kabanda-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+      - name: Run tests
+        run: pytest -q
+      - name: Build check
+        run: |
+          pip install build twine
+          python -m build
+          python -m twine check dist/*

calckit_kabanda-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/

calckit_kabanda-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+### Added
+
+- Arithmetic: `add`, `subtract`, `multiply`, `divide`, `integer_divide`,
+  `power`, `modulus`, `absolute`, `root`, `square_root`, `logarithm`,
+  `factorial`
+- Statistics: `total`, `mean`, `average`, `median`, `mode`, `minimum`,
+  `maximum`, `value_range`, `variance`, `standard_deviation`,
+  `geometric_mean`, `harmonic_mean`
+- Errors: `CalcError`, `DivisionByZeroError`, `EmptySequenceError`
+- `calckit-kabanda` command line interface, also runnable as
+  `python -m calc_toolkit`

calckit_kabanda-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kabanda-jordan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calckit_kabanda-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: calckit-kabanda
+Version: 0.1.0
+Summary: Arithmetic and statistics helpers: add, subtract, multiply, divide, mean, median, mode and more.
+Project-URL: Homepage, https://github.com/kabanda-jordan/calckit-kabanda
+Project-URL: Repository, https://github.com/kabanda-jordan/calckit-kabanda
+Project-URL: Issues, https://github.com/kabanda-jordan/calckit-kabanda/issues
+Project-URL: Changelog, https://github.com/kabanda-jordan/calckit-kabanda/blob/main/CHANGELOG.md
+Author: kabanda-jordan
+License: MIT
+License-File: LICENSE
+Keywords: arithmetic,average,calculator,math,mean,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# calckit-kabanda
+
+Arithmetic and statistics helpers for Python, plus a `calckit-kabanda` command line tool.
+
+## Install
+
+From GitHub (no PyPI account needed, works immediately):
+
+```powershell
+pip install git+https://github.com/kabanda-jordan/calckit-kabanda.git
+```
+
+From PyPI, once published:
+
+```powershell
+pip install calckit-kabanda
+```
+
+Or from a checkout:
+
+```powershell
+pip install -e .
+```
+
+The distribution is named `calckit-kabanda` on PyPI, but the import name stays
+`calc_toolkit`, so code reads:
+
+```python
+from calc_toolkit import add, subtract, multiply, divide, mean, median
+```
+
+## Library use
+
+```python
+add(1, 2, 3)            # 6
+subtract(10, 3, 2)      # 5
+multiply(2, 3, 4)       # 24
+divide(10, 4)           # 2.5
+
+mean(2, 4, 6)           # 4.0  (same as average)
+median(1, 3, 2)         # 2.0
+mode(1, 2, 2, 3)        # 2.0
+```
+
+### Arithmetic
+
+| Function | Example | Result |
+| --- | --- | --- |
+| `add(*values)` | `add(1, 2, 3)` | `6` |
+| `subtract(a, *rest)` | `subtract(10, 3)` | `7` |
+| `multiply(*values)` | `multiply(2, 3, 4)` | `24` |
+| `divide(a, b)` | `divide(10, 4)` | `2.5` |
+| `integer_divide(a, b)` | `integer_divide(10, 3)` | `3` |
+| `power(base, exp)` | `power(2, 10)` | `1024` |
+| `modulus(a, b)` | `modulus(10, 3)` | `1` |
+| `absolute(x)` | `absolute(-5)` | `5` |
+| `root(x, degree=2)` | `root(27, 3)` | `3.0` |
+| `square_root(x)` | `square_root(9)` | `3.0` |
+| `logarithm(x, base=e)` | `logarithm(8, 2)` | `3.0` |
+| `factorial(n)` | `factorial(5)` | `120` |
+
+### Statistics
+
+All statistics accept a variable number of values, so both
+`mean([2, 4, 6])` and `mean(2, 4, 6)` work.
+
+| Function | Example | Result |
+| --- | --- | --- |
+| `total(*values)` | `total(1, 2, 3)` | `6.0` |
+| `mean(*values)` / `average` | `mean(2, 4, 6)` | `4.0` |
+| `median(*values)` | `median(4, 1, 3, 2)` | `2.5` |
+| `mode(*values)` | `mode(1, 2, 2)` | `2.0` |
+| `minimum(*values)` | `min(3, 1, 2)` | `1.0` |
+| `maximum(*values)` | `max(3, 1, 2)` | `3.0` |
+| `value_range(*values)` | `range(3, 1, 2)` | `2.0` |
+| `variance(*values, sample=False)` | `variance(2, 4, 6)` | `2.666…` |
+| `standard_deviation(*values)` | `stdev(2, 4, 6)` | `1.632…` |
+| `geometric_mean(*values)` | `geometric_mean(1, 4)` | `2.0` |
+| `harmonic_mean(*values)` | `harmonic_mean(1, 4)` | `1.6` |
+
+### Errors
+
+Everything raises `CalcError` (a plain `Exception` subclass):
+
+- `DivisionByZeroError` for `divide(1, 0)`, `modulus(1, 0)`, `integer_divide(1, 0)`
+- `EmptySequenceError` for `mean()` with no values
+- `CalcError` for bad types (strings, booleans, negatives under a root, and so on)
+
+Booleans are rejected on purpose, so `add(True, 1)` fails instead of silently
+treating `True` as `1`.
+
+## Command line
+
+```powershell
+calckit-kabanda add 1 2 3
+calckit-kabanda divide 10 4
+calckit-kabanda mean 2 4 6
+calckit-kabanda median 4 1 3 2
+calckit-kabanda sqrt 9
+calckit-kabanda factorial 5
+calckit-kabanda --help
+```
+
+Without installing the script, use the module form:
+
+```powershell
+python -m calc_toolkit add 1 2 3
+```
+
+Exit codes: `0` success, `1` calculation error, `2` bad arguments.
+
+## Tests
+
+```powershell
+pytest
+```

calckit_kabanda-0.1.0/README.md

@@ -0,0 +1,116 @@
+# calckit-kabanda
+
+Arithmetic and statistics helpers for Python, plus a `calckit-kabanda` command line tool.
+
+## Install
+
+From GitHub (no PyPI account needed, works immediately):
+
+```powershell
+pip install git+https://github.com/kabanda-jordan/calckit-kabanda.git
+```
+
+From PyPI, once published:
+
+```powershell
+pip install calckit-kabanda
+```
+
+Or from a checkout:
+
+```powershell
+pip install -e .
+```
+
+The distribution is named `calckit-kabanda` on PyPI, but the import name stays
+`calc_toolkit`, so code reads:
+
+```python
+from calc_toolkit import add, subtract, multiply, divide, mean, median
+```
+
+## Library use
+
+```python
+add(1, 2, 3)            # 6
+subtract(10, 3, 2)      # 5
+multiply(2, 3, 4)       # 24
+divide(10, 4)           # 2.5
+
+mean(2, 4, 6)           # 4.0  (same as average)
+median(1, 3, 2)         # 2.0
+mode(1, 2, 2, 3)        # 2.0
+```
+
+### Arithmetic
+
+| Function | Example | Result |
+| --- | --- | --- |
+| `add(*values)` | `add(1, 2, 3)` | `6` |
+| `subtract(a, *rest)` | `subtract(10, 3)` | `7` |
+| `multiply(*values)` | `multiply(2, 3, 4)` | `24` |
+| `divide(a, b)` | `divide(10, 4)` | `2.5` |
+| `integer_divide(a, b)` | `integer_divide(10, 3)` | `3` |
+| `power(base, exp)` | `power(2, 10)` | `1024` |
+| `modulus(a, b)` | `modulus(10, 3)` | `1` |
+| `absolute(x)` | `absolute(-5)` | `5` |
+| `root(x, degree=2)` | `root(27, 3)` | `3.0` |
+| `square_root(x)` | `square_root(9)` | `3.0` |
+| `logarithm(x, base=e)` | `logarithm(8, 2)` | `3.0` |
+| `factorial(n)` | `factorial(5)` | `120` |
+
+### Statistics
+
+All statistics accept a variable number of values, so both
+`mean([2, 4, 6])` and `mean(2, 4, 6)` work.
+
+| Function | Example | Result |
+| --- | --- | --- |
+| `total(*values)` | `total(1, 2, 3)` | `6.0` |
+| `mean(*values)` / `average` | `mean(2, 4, 6)` | `4.0` |
+| `median(*values)` | `median(4, 1, 3, 2)` | `2.5` |
+| `mode(*values)` | `mode(1, 2, 2)` | `2.0` |
+| `minimum(*values)` | `min(3, 1, 2)` | `1.0` |
+| `maximum(*values)` | `max(3, 1, 2)` | `3.0` |
+| `value_range(*values)` | `range(3, 1, 2)` | `2.0` |
+| `variance(*values, sample=False)` | `variance(2, 4, 6)` | `2.666…` |
+| `standard_deviation(*values)` | `stdev(2, 4, 6)` | `1.632…` |
+| `geometric_mean(*values)` | `geometric_mean(1, 4)` | `2.0` |
+| `harmonic_mean(*values)` | `harmonic_mean(1, 4)` | `1.6` |
+
+### Errors
+
+Everything raises `CalcError` (a plain `Exception` subclass):
+
+- `DivisionByZeroError` for `divide(1, 0)`, `modulus(1, 0)`, `integer_divide(1, 0)`
+- `EmptySequenceError` for `mean()` with no values
+- `CalcError` for bad types (strings, booleans, negatives under a root, and so on)
+
+Booleans are rejected on purpose, so `add(True, 1)` fails instead of silently
+treating `True` as `1`.
+
+## Command line
+
+```powershell
+calckit-kabanda add 1 2 3
+calckit-kabanda divide 10 4
+calckit-kabanda mean 2 4 6
+calckit-kabanda median 4 1 3 2
+calckit-kabanda sqrt 9
+calckit-kabanda factorial 5
+calckit-kabanda --help
+```
+
+Without installing the script, use the module form:
+
+```powershell
+python -m calc_toolkit add 1 2 3
+```
+
+Exit codes: `0` success, `1` calculation error, `2` bad arguments.
+
+## Tests
+
+```powershell
+pytest
+```

calckit_kabanda-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "calckit-kabanda"
+version = "0.1.0"
+description = "Arithmetic and statistics helpers: add, subtract, multiply, divide, mean, median, mode and more."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+authors = [{ name = "kabanda-jordan" }]
+keywords = ["math", "arithmetic", "statistics", "calculator", "average", "mean"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/kabanda-jordan/calckit-kabanda"
+Repository = "https://github.com/kabanda-jordan/calckit-kabanda"
+Issues = "https://github.com/kabanda-jordan/calckit-kabanda/issues"
+Changelog = "https://github.com/kabanda-jordan/calckit-kabanda/blob/main/CHANGELOG.md"
+
+[project.scripts]
+calckit-kabanda = "calc_toolkit.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/calc_toolkit"]
+
+[dependency-groups]
+dev = ["pytest>=7.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

calckit_kabanda-0.1.0/src/calc_toolkit/__init__.py

@@ -0,0 +1,77 @@
+"""calc_toolkit - arithmetic and statistics helpers.
+
+Examples:
+    >>> from calc_toolkit import add, divide, mean
+    >>> add(1, 2, 3)
+    6
+    >>> divide(10, 4)
+    2.5
+    >>> mean(2, 4, 6)
+    4.0
+"""
+
+from .arithmetic import (
+    absolute,
+    add,
+    divide,
+    factorial,
+    integer_divide,
+    logarithm,
+    modulus,
+    multiply,
+    power,
+    root,
+    square_root,
+    subtract,
+)
+from .errors import CalcError, DivisionByZeroError, EmptySequenceError
+from .statistics import (
+    average,
+    geometric_mean,
+    harmonic_mean,
+    maximum,
+    mean,
+    median,
+    minimum,
+    mode,
+    standard_deviation,
+    total,
+    value_range,
+    variance,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # arithmetic
+    "add",
+    "subtract",
+    "multiply",
+    "divide",
+    "integer_divide",
+    "power",
+    "modulus",
+    "absolute",
+    "root",
+    "square_root",
+    "logarithm",
+    "factorial",
+    # statistics
+    "total",
+    "mean",
+    "average",
+    "median",
+    "mode",
+    "minimum",
+    "maximum",
+    "value_range",
+    "variance",
+    "standard_deviation",
+    "geometric_mean",
+    "harmonic_mean",
+    # errors
+    "CalcError",
+    "DivisionByZeroError",
+    "EmptySequenceError",
+    "__version__",
+]

calckit_kabanda-0.1.0/src/calc_toolkit/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m calc_toolkit``."""
+
+from .cli import main
+
+raise SystemExit(main())

calckit_kabanda-0.1.0/src/calc_toolkit/arithmetic.py

@@ -0,0 +1,129 @@
+"""Basic arithmetic operations.
+
+Every function accepts any number of values and returns a numeric result.
+Numbers can be ints or floats; ``True``/``False`` are rejected on purpose so
+that booleans never sneak in as 0/1.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Iterable, Union
+
+from .errors import CalcError, DivisionByZeroError
+
+Number = Union[int, float]
+
+
+def _validate(values: Iterable[Number], op: str) -> list:
+    """Return ``values`` as a list of numbers, or raise ``CalcError``."""
+    out = []
+    for value in values:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise CalcError(
+                f"{op}() only accepts int or float, got {type(value).__name__}: {value!r}"
+            )
+        out.append(value)
+    if not out:
+        raise CalcError(f"{op}() needs at least one value")
+    return out
+
+
+def _check_nonzero(divisor: Number, op: str) -> None:
+    if divisor == 0:
+        raise DivisionByZeroError(f"{op}() cannot divide by zero")
+
+
+def add(*values: Number) -> Number:
+    """Return the sum of all ``values``."""
+    return sum(_validate(values, "add"))
+
+
+def subtract(minuend: Number, *subtrahends: Number) -> Number:
+    """Subtract every following value from ``minuend``.
+
+    ``subtract(10, 3, 2)`` -> ``5``
+    """
+    _validate((minuend, *subtrahends), "subtract")
+    result = minuend
+    for value in subtrahends:
+        result -= value
+    return result
+
+
+def multiply(*values: Number) -> Number:
+    """Return the product of all ``values``."""
+    result = 1
+    for value in _validate(values, "multiply"):
+        result *= value
+    return result
+
+
+def divide(dividend: Number, divisor: Number) -> Number:
+    """Return ``dividend / divisor``.
+
+    Raises:
+        DivisionByZeroError: if ``divisor`` is zero.
+    """
+    _validate((dividend, divisor), "divide")
+    _check_nonzero(divisor, "divide")
+    return dividend / divisor
+
+
+def integer_divide(dividend: Number, divisor: Number) -> int:
+    """Return floor division (``//``) as an int."""
+    _validate((dividend, divisor), "integer_divide")
+    _check_nonzero(divisor, "integer_divide")
+    return int(dividend // divisor)
+
+
+def power(base: Number, exponent: Number) -> Number:
+    """Return ``base ** exponent``."""
+    _validate((base, exponent), "power")
+    return base**exponent
+
+
+def modulus(dividend: Number, divisor: Number) -> Number:
+    """Return the remainder (``%``)."""
+    _validate((dividend, divisor), "modulus")
+    _check_nonzero(divisor, "modulus")
+    return dividend % divisor
+
+
+def absolute(value: Number) -> Number:
+    """Return the absolute value of ``value``."""
+    _validate((value,), "absolute")
+    return abs(value)
+
+
+def root(value: Number, degree: Number = 2) -> float:
+    """Return the ``degree``-th root of a non-negative ``value``."""
+    _validate((value, degree), "root")
+    if value < 0:
+        raise CalcError(f"root() needs a non-negative value, got {value}")
+    if degree == 0:
+        raise CalcError("root() degree cannot be zero")
+    return float(value ** (1 / degree))
+
+
+def square_root(value: Number) -> float:
+    """Return the square root of ``value``."""
+    return root(value, 2)
+
+
+def logarithm(value: Number, base: Number = math.e) -> float:
+    """Return the logarithm of ``value`` in the given ``base``."""
+    _validate((value, base), "logarithm")
+    if value <= 0:
+        raise CalcError(f"logarithm() needs a value above zero, got {value}")
+    _check_nonzero(base, "logarithm")
+    return math.log(value, base)
+
+
+def factorial(value: int) -> int:
+    """Return ``value!`` for non-negative integers."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise CalcError(f"factorial() needs an int, got {type(value).__name__}")
+    if value < 0:
+        raise CalcError(f"factorial() needs a non-negative value, got {value}")
+    return math.factorial(value)

calckit_kabanda-0.1.0/src/calc_toolkit/cli.py

@@ -0,0 +1,133 @@
+"""Command line interface: ``calc <operation> <numbers...>``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .arithmetic import (
+    absolute,
+    add,
+    divide,
+    factorial,
+    integer_divide,
+    logarithm,
+    modulus,
+    multiply,
+    power,
+    root,
+    square_root,
+    subtract,
+)
+from .errors import CalcError
+from .statistics import (
+    average,
+    geometric_mean,
+    harmonic_mean,
+    maximum,
+    mean,
+    median,
+    minimum,
+    mode,
+    standard_deviation,
+    total,
+    value_range,
+    variance,
+)
+
+OPERATIONS = {
+    "add": add,
+    "subtract": subtract,
+    "multiply": multiply,
+    "divide": divide,
+    "div": divide,
+    "idiv": integer_divide,
+    "power": power,
+    "pow": power,
+    "modulus": modulus,
+    "mod": modulus,
+    "abs": absolute,
+    "root": root,
+    "sqrt": square_root,
+    "log": logarithm,
+    "factorial": factorial,
+    "total": total,
+    "mean": mean,
+    "average": average,
+    "median": median,
+    "mode": mode,
+    "min": minimum,
+    "max": maximum,
+    "range": value_range,
+    "variance": variance,
+    "stdev": standard_deviation,
+    "geomean": geometric_mean,
+    "harmmean": harmonic_mean,
+}
+
+NEEDS_ONE = {"abs", "sqrt", "factorial"}
+NEEDS_TWO = {"divide", "div", "idiv", "power", "pow", "modulus", "mod"}
+ONE_OR_TWO = {"root", "log"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="calckit-kabanda",
+        description="Arithmetic and statistics calculator.",
+        epilog="Operations: " + ", ".join(sorted(OPERATIONS)),
+    )
+    parser.add_argument("operation", help="e.g. add, divide, mean")
+    parser.add_argument("numbers", nargs="*", help="numbers to work on")
+    parser.add_argument("-V", "--version", action="version", version=f"calckit-kabanda {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    op_name = args.operation.lower()
+    if op_name not in OPERATIONS:
+        print(
+            f"Unknown operation: {args.operation}\nOperations: " + ", ".join(sorted(OPERATIONS)),
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        numbers = [float(n) for n in args.numbers]
+    except ValueError:
+        print("All arguments must be numbers", file=sys.stderr)
+        return 2
+
+    if op_name in NEEDS_ONE and len(numbers) != 1:
+        print(f"{op_name}() takes exactly 1 number", file=sys.stderr)
+        return 2
+    if op_name in NEEDS_TWO and len(numbers) != 2:
+        print(f"{op_name}() takes exactly 2 numbers", file=sys.stderr)
+        return 2
+    if op_name in ONE_OR_TWO and len(numbers) > 2:
+        print(f"{op_name}() takes 1 or 2 numbers", file=sys.stderr)
+        return 2
+    if not numbers and op_name not in NEEDS_ONE:
+        print(f"{op_name}() needs at least one number", file=sys.stderr)
+        return 2
+
+    if op_name == "factorial":
+        numbers = [numbers[0].is_integer() and int(numbers[0])]
+
+    try:
+        result = OPERATIONS[op_name](*numbers)
+    except CalcError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    if isinstance(result, float) and result.is_integer():
+        print(int(result))
+    else:
+        print(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

calckit_kabanda-0.1.0/src/calc_toolkit/errors.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for calc_toolkit."""
+
+
+class CalcError(Exception):
+    """Base class for every error raised by calc_toolkit."""
+
+
+class DivisionByZeroError(CalcError):
+    """Raised when a division would divide by zero."""
+
+
+class EmptySequenceError(CalcError):
+    """Raised when a statistic is requested on an empty sequence."""

calckit_kabanda-0.1.0/src/calc_toolkit/statistics.py

@@ -0,0 +1,112 @@
+"""Statistics over a sequence of numbers."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from typing import Iterable, Union
+
+from .errors import CalcError, EmptySequenceError
+
+Number = Union[int, float]
+
+
+def _clean(values: Iterable[Number], op: str) -> list[float]:
+    """Return ``values`` as a non-empty list of floats."""
+    out = []
+    for value in values:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise CalcError(
+                f"{op}() only accepts int or float, got {type(value).__name__}: {value!r}"
+            )
+        out.append(float(value))
+    if not out:
+        raise EmptySequenceError(f"{op}() needs at least one value")
+    return out
+
+
+def total(*values: Number) -> float:
+    """Return the sum of all ``values``."""
+    return float(sum(_clean(values, "total")))
+
+
+def mean(*values: Number) -> float:
+    """Return the arithmetic mean (average) of ``values``.
+
+    Also available as ``average``.
+    """
+    nums = _clean(values, "mean")
+    return sum(nums) / len(nums)
+
+
+average = mean
+
+
+def median(*values: Number) -> float:
+    """Return the middle value (or mean of the two middles)."""
+    nums = sorted(_clean(values, "median"))
+    mid = len(nums) // 2
+    if len(nums) % 2:
+        return nums[mid]
+    return (nums[mid - 1] + nums[mid]) / 2
+
+
+def mode(*values: Number) -> float:
+    """Return the most common value.
+
+    With several tied values the smallest one is returned.
+    """
+    counts = Counter(_clean(values, "mode"))
+    top = max(counts.values())
+    return min(value for value, count in counts.items() if count == top)
+
+
+def minimum(*values: Number) -> float:
+    """Return the smallest value."""
+    return min(_clean(values, "minimum"))
+
+
+def maximum(*values: Number) -> float:
+    """Return the largest value."""
+    return max(_clean(values, "maximum"))
+
+
+def value_range(*values: Number) -> float:
+    """Return ``max - min``."""
+    nums = _clean(values, "value_range")
+    return max(nums) - min(nums)
+
+
+def variance(*values: Number, sample: bool = False) -> float:
+    """Return the variance.
+
+    Args:
+        sample: use n-1 (Bessel's correction) instead of n.
+    """
+    nums = _clean(values, "variance")
+    if sample and len(nums) < 2:
+        raise CalcError("variance() with sample=True needs at least two values")
+    avg = sum(nums) / len(nums)
+    divisor = len(nums) - 1 if sample else len(nums)
+    return sum((n - avg) ** 2 for n in nums) / divisor
+
+
+def standard_deviation(*values: Number, sample: bool = False) -> float:
+    """Return the standard deviation (square root of the variance)."""
+    return math.sqrt(variance(*values, sample=sample))
+
+
+def geometric_mean(*values: Number) -> float:
+    """Return the geometric mean. All values must be positive."""
+    nums = _clean(values, "geometric_mean")
+    if any(n <= 0 for n in nums):
+        raise CalcError("geometric_mean() only accepts values above zero")
+    return math.exp(sum(math.log(n) for n in nums) / len(nums))
+
+
+def harmonic_mean(*values: Number) -> float:
+    """Return the harmonic mean. All values must be non-zero."""
+    nums = _clean(values, "harmonic_mean")
+    if any(n == 0 for n in nums):
+        raise CalcError("harmonic_mean() cannot accept zero")
+    return len(nums) / sum(1 / n for n in nums)

calckit_kabanda-0.1.0/tests/test_arithmetic.py

@@ -0,0 +1,82 @@
+import pytest
+
+from calc_toolkit import (
+    CalcError,
+    DivisionByZeroError,
+    absolute,
+    add,
+    divide,
+    factorial,
+    integer_divide,
+    modulus,
+    multiply,
+    power,
+    square_root,
+    subtract,
+)
+
+
+def test_add():
+    assert add(1, 2, 3) == 6
+    assert add(1.5, 2) == 3.5
+
+
+def test_add_rejects_nothing_given():
+    with pytest.raises(CalcError):
+        add()
+
+
+def test_subtract():
+    assert subtract(10, 3) == 7
+    assert subtract(10, 3, 2) == 5
+
+
+def test_multiply():
+    assert multiply(2, 3, 4) == 24
+    assert multiply(5) == 5
+
+
+def test_divide():
+    assert divide(10, 4) == 2.5
+    assert divide(9, 3) == 3.0
+
+
+def test_divide_by_zero():
+    with pytest.raises(DivisionByZeroError):
+        divide(1, 0)
+
+
+def test_integer_divide():
+    assert integer_divide(10, 3) == 3
+    assert integer_divide(-10, 3) == -4
+
+
+def test_power_and_modulus():
+    assert power(2, 10) == 1024
+    assert modulus(10, 3) == 1
+    with pytest.raises(DivisionByZeroError):
+        modulus(10, 0)
+
+
+def test_root_and_log():
+    assert square_root(9) == 3.0
+    with pytest.raises(CalcError):
+        square_root(-1)
+
+
+def test_absolute_and_factorial():
+    assert absolute(-5) == 5
+    assert factorial(5) == 120
+    assert factorial(0) == 1
+    with pytest.raises(CalcError):
+        factorial(-1)
+
+
+def test_booleans_rejected():
+    with pytest.raises(CalcError):
+        add(True, 1)
+
+
+def test_strings_rejected():
+    with pytest.raises(CalcError):
+        multiply("2", 3)

calckit_kabanda-0.1.0/tests/test_cli.py

@@ -0,0 +1,44 @@
+import pytest
+
+from calc_toolkit.cli import main
+
+
+def test_add(capsys):
+    assert main(["add", "1", "2", "3"]) == 0
+    assert capsys.readouterr().out.strip() == "6"
+
+
+def test_divide_renders_without_decimal_point(capsys):
+    assert main(["divide", "9", "3"]) == 0
+    assert capsys.readouterr().out.strip() == "3"
+
+
+def test_mean(capsys):
+    assert main(["mean", "2", "4", "6"]) == 0
+    assert capsys.readouterr().out.strip() == "4"
+
+
+def test_divide_by_zero_returns_error(capsys):
+    assert main(["divide", "1", "0"]) == 1
+    assert "divide by zero" in capsys.readouterr().err
+
+
+def test_unknown_operation(capsys):
+    assert main(["frobnicate", "1"]) == 2
+
+
+def test_non_numeric_argument(capsys):
+    assert main(["add", "abc"]) == 2
+
+
+def test_wrong_argument_count(capsys):
+    assert main(["divide", "1", "2", "3"]) == 2
+
+
+def test_missing_numbers(capsys):
+    assert main(["add"]) == 2
+
+
+def test_factorial(capsys):
+    assert main(["factorial", "5"]) == 0
+    assert capsys.readouterr().out.strip() == "120"

calckit_kabanda-0.1.0/tests/test_statistics.py

@@ -0,0 +1,77 @@
+import math
+
+import pytest
+
+from calc_toolkit import (
+    CalcError,
+    EmptySequenceError,
+    average,
+    geometric_mean,
+    harmonic_mean,
+    maximum,
+    mean,
+    median,
+    minimum,
+    mode,
+    standard_deviation,
+    total,
+    value_range,
+    variance,
+)
+
+
+def test_total():
+    assert total(1, 2, 3, 4) == 10.0
+
+
+def test_mean_and_average():
+    assert mean(2, 4, 6) == 4.0
+    assert average(2, 4, 6) == 4.0
+    assert mean(5) == 5.0
+
+
+def test_median():
+    assert median(1, 3, 2) == 2.0
+    assert median(4, 1, 3, 2) == 2.5
+
+
+def test_mode_picks_smallest_on_tie():
+    assert mode(1, 2, 2, 3) == 2.0
+    assert mode(1, 1, 2, 2) == 1.0
+
+
+def test_min_max_range():
+    assert minimum(3, 1, 2) == 1.0
+    assert maximum(3, 1, 2) == 3.0
+    assert value_range(3, 1, 2) == 2.0
+
+
+def test_variance_and_stdev():
+    assert variance(2, 4, 4, 4, 5, 5, 7, 9) == pytest.approx(4.0)
+    assert variance(2, 4, 4, 4, 5, 5, 7, 9, sample=True) == pytest.approx(32 / 7)
+    assert standard_deviation(2, 4, 4, 4, 5, 5, 7, 9) == pytest.approx(2.0)
+
+
+def test_population_variance_single_value():
+    assert variance(7) == 0.0
+    with pytest.raises(CalcError):
+        variance(7, sample=True)
+
+
+def test_means():
+    assert geometric_mean(1, 4) == pytest.approx(2.0)
+    assert harmonic_mean(1, 4) == pytest.approx(1.6)
+    with pytest.raises(CalcError):
+        geometric_mean(0)
+    with pytest.raises(CalcError):
+        harmonic_mean(0)
+
+
+def test_empty_sequence():
+    with pytest.raises(EmptySequenceError):
+        mean()
+
+
+def test_non_numeric():
+    with pytest.raises(CalcError):
+        median(1, "two")