Metadata-Version: 2.3
Name: pional
Version: 0.1.0
Summary: Add Functional Programing to Python
Author: NovaH00
Author-email: NovaH00 <trantay2006super@gmail.com>
Requires-Python: >=3.14
Project-URL: Repository, https://github.com/NovaH00/python-FP
Description-Content-Type: text/markdown

# pional

Functional programming primitives for Python, with full type safety.

## Installation

```bash
uv add pional  # or pip install pional
```

## Quick Example

```python
from pional.adts import Result, Ok, Err
from pional.collections import Vec
from pional.iterators import Range

def divide(a: int, b: int) -> Result[float, str]:
    if b == 0:
        return Err("cannot divide by zero")
    return Ok(a / b)

first = Range(1, 100)
second = Range(1, 100)

result: Vec[float] = (
    first
    .rev()
    .zip(second)
    .filter_map(lambda ab: divide(*ab).ok())
    .collect(Vec)
)
```

## Modules

### `pional.adts` — Algebraic Data Types

- **`Result[T, E] = Ok[T] | Err[E]`** — success/failure
  - `unwrap()`, `unwrap_or(default)`, `unwrap_err()` (Err only)
  - `map(f)`, `map_err(f)`, `and_then(f)`
  - `map_or(default, f)`, `map_or_else(default_fn, f)`
  - `combine(other)`, `combine_with(other, f)`
  - `ok()` → `Option[T]`, `err()` → `Option[E]`
  - `is_ok()`, `is_err()`

- **`Option[T] = Some[T] | Nothing`** — optional value
  - `unwrap()`, `unwrap_or(default)`
  - `map(f)`, `and_then(f)`
  - `ok_or(err)`, `ok_or_else(err_fn)` → `Result[T, E]`
  - `is_some()`, `is_none()`

### `pional.collections` — Collections

- **`Vec[T]`** — immutable-style vector (wraps `list`)
  - `into_iter()` → `Iter[T]`
  - `append(item)`, `extend(items)`, `insert(index, item)`
  - `pop()` → `Option[T]`, `get(index)` → `Option[T]`
  - `sort()`, `sort_by(key)`

- **`HashMap[K, V]`** — hash map (wraps `dict`, extends `MutableMapping`)
  - `insert(k, v)`, `remove(k)` → `Option[V]`, `contains(k)`
  - `keys()` → `Iter[K]`, `values()` → `Iter[V]`
  - `into_iter()` → `Iter[tuple[K, V]]`

- **`HashSet[T]`** — hash set (wraps `set`, extends `MutableSet`)
  - `insert(x)`, `remove(x)`, `contains(x)`
  - `add(x)`, `discard(x)`
  - `into_iter()` → `Iter[T]`

### `pional.iterators` — Iterator Combinators

- **`Iter[T]`**, **`Range`** — constructors

- **Lazy combinators**:
  `map`, `filter`, `filter_map`, `flat_map`, `flatten`, `enumerate`,
  `take`, `skip`, `chain`, `zip`, `inspect`, `peekable`, `rev`,
  `dedup`, `unique`, `cycle`, `chunks(n)`, `windows(n)`

- **Terminal methods**:
  `collect(Vec|HashSet|HashMap)`, `count`, `first`, `last`, `nth`,
  `for_each`, `sum`, `product`, `min`, `max`, `fold`, `reduce`,
  `all`, `any`, `find`, `join`,
  `sorted()`, `sorted_by(key)`, `partition(pred)`, `group_by(key_fn)`

### `pional.fn` — Function Utilities

- **`Pipe`** — `Pipe(x).pipe(fn1).pipe(fn2)`
- **`Compose`** — `Compose(fn1).compose(fn2)(x)` (right-to-left)
- **`identity(x)`** — returns `x`
- **`constant(x)`** — returns a function that always returns `x`

## Design

- Fully type-annotated with Python 3.14+ generics (PEP 695)
- ADTs use `match`-compatible `__match_args__` for pattern matching
- Iterators are lazy where possible
- No external dependencies
