Metadata-Version: 2.4
Name: nithilan
Version: 0.3.0
Summary: Small Python utilities for everyday programs
Author: Nithilan Vivek
Project-URL: Homepage, https://nithi.land
Keywords: utilities,factorial,terminal,combinations,calendar
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# nithilan

Small Python utilities for everyday programs. Requires Python 3.10 or newer.

## Version 0.3.0

New in 0.3.0:

- `combination(x, y)` and its aliases `comb`, `C`, and `combn`.
- `days` and `months`: lists of English weekday and month names.
- An expanded interactive `help()` tutorial covering the new features.
- Line-input fallback for `ask()` on Windows when input is not a terminal.

Install or upgrade from PyPI:

```sh
python3 -m pip install --upgrade nithilan
```

## Usage

```python
import nithilan

print(nithilan.factorial(5))  # 120
print(nithilan.factorial(1.5))  # approximately 1.329340388179137
print(nithilan.combination(5, 3))  # 10
print(nithilan.comb(5, 3))  # 10; C and combn are aliases too
print(nithilan.days[1])  # Tuesday
print(nithilan.months[1])  # February

my_days = nithilan.days.copy()  # independent list you can modify

if nithilan.ask("Continue?"):
    print("Continuing")

nithilan.help()
```

### `factorial(x)`

Returns an integer factorial for non-negative whole numbers (including zero
and whole-valued floats such as `5.0`). For non-negative fractional values,
returns the floating-point extension `math.gamma(x + 1)`. Negative values raise
`ValueError`; sufficiently large fractional results may raise `OverflowError`.

### `ask(prompt)`

Returns `True` for `y`, `False` for `n`, and `None` for any other answer.
Answers are case-insensitive. Reads one key without Enter in an interactive
Windows, macOS, or Linux terminal; otherwise uses line input (press Enter when
typing). End-of-input raises `EOFError` in the line-input fallback.

### `combination(x, y)` / `comb(x, y)` / `C(x, y)` / `combn(x, y)`

Returns the exact integer number of ways to choose `y` items from `x` without
repetition and without considering order. Uses Python's
[`math.comb`](https://docs.python.org/3/library/math.html#math.comb).
Both arguments must be non-negative integers. Negative integers raise
`ValueError`; non-integers, including `5.0`, raise `TypeError`.
Returns `0` if `y > x`, and `1` if `y == 0` (including `combination(0, 0)`).
Use qualified names after `import nithilan`, or explicitly import an alias with
`from nithilan import comb` before calling `comb(5, 3)`.

### `days` and `months`

These are lists, not functions: use `nithilan.days` and `nithilan.months`
without parentheses. Days start with Monday; months start with January.
Indexing starts at zero, so index `1` means Tuesday or February.

The lists are shared and mutable within a Python process. Assigning
`my_days = nithilan.days` refers to the same list; use `.copy()` to obtain
an independent list before modifying it. The same applies to `months`.

### `help()`

Starts the interactive tutorial. Answer `y` to continue, or `n` (or an invalid
answer) to stop at any prompt. Returns `None`.

## Development and building

```sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e . build twine
python -m unittest discover -s tests -v
python -m build
python -m twine check --strict dist/nithilan-0.3.0-py3-none-any.whl dist/nithilan-0.3.0.tar.gz
```

Building and checking these files does not publish them to PyPI.
