Metadata-Version: 2.5
Name: calckit-kabanda
Version: 0.2.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
Requires-Dist: flask>=3.0
Description-Content-Type: text/markdown

# calckit-kabanda

Arithmetic and statistics helpers for Python, plus a `calckit-kabanda` command line tool.

## Calculator interface

`calc-kabanda` starts a local web server and opens a clickable calculator in
your browser, with a full button pad, keyboard support, and a statistics panel.

```powershell
calc-kabanda
```

It prints a `http://127.0.0.1:5000` address and opens it automatically. Press
Ctrl+C to stop. Nothing leaves your machine.

If the command is not found, run `python -m calc_toolkit.webapp` instead.

The display accepts expressions using `+ - * / // % **`, parentheses, and
functions: `sqrt`, `root`, `abs`, `factorial`, `log`, `ln`, `floor`, `ceil`,
`round`, `exp`, `sin`, `cos`, `tan`, `min`, `max`, `pow`.

Expressions are parsed by a hand-written recursive-descent parser, not
`eval()`, so nothing outside that list can execute. Handing the server
`__import__('os').system('...')` returns an error instead of running it.

## 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
```

### Expressions

`evaluate` parses a string safely, with no use of `eval`:

```python
from calc_toolkit import evaluate

evaluate("2 + 3 * sqrt(16)")   # 14.0
evaluate("(10 + 5) / 3")        # 5.0
evaluate("2 ** 3 ** 2")         # 512.0  (right associative)
evaluate("factorial(5) + 1")    # 121.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
```