pional 0.1.0__tar.gz

pional-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+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

pional-0.1.0/README.md

@@ -0,0 +1,98 @@
+# 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

pional-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "pional"
+version = "0.1.0"
+description = "Add Functional Programing to Python"
+authors = [
+    { name = "NovaH00", email = "trantay2006super@gmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = []
+
+
+[project.urls]
+Repository = "https://github.com/NovaH00/python-FP"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"

pional-0.1.0/src/pional/__init__.py

@@ -0,0 +1,9 @@
+"""pional — Functional programming primitives for Python."""
+from . import iterators, collections, adts, fn
+
+__all__ = [
+    "iterators",
+    "collections",
+    "adts",
+    "fn"
+]

pional-0.1.0/src/pional/adts/__init__.py

@@ -0,0 +1,8 @@
+"""Algebraic data types — Option and Result."""
+from .option import Option, Some, Nothing
+from .result import Result, Ok, Err
+
+__all__ = [
+    "Option", "Some", "Nothing",
+    "Result", "Ok", "Err"
+]

pional-0.1.0/src/pional/adts/option.py

@@ -0,0 +1,173 @@
+"""Option type — represents an optional value.
+
+Provides ``Some[T]`` for present values and ``Nothing`` for absent values,
+with monadic operations like ``map`` and ``and_then``.
+"""
+from __future__ import annotations
+
+from typing import final, Callable, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .result import Result
+
+type Option[T] = Some[T] | Nothing
+
+
+@final
+class Some[T]:
+    """Represents a present value."""
+
+    __match_args__ = ('value',)
+
+    def __init__(self, value: T) -> None:
+        self.value = value
+
+    def unwrap(self) -> T:
+        """Return the inner value."""
+        return self.value
+
+    def unwrap_or(self, default: T) -> T:
+        """Return the inner value, ignoring *default*."""
+        return self.value
+
+    def map[U](self, f: Callable[[T], U]) -> Some[U]:
+        """Transform the inner value using *f*.
+
+        Args:
+            f: The function to apply to the wrapped value.
+
+        Returns:
+            A new ``Some`` containing the transformed value.
+        """
+        return Some(f(self.value))
+
+    def and_then[U](self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Apply *f* to the inner value and return the result.
+
+        Args:
+            f: A function that returns an ``Option``.
+
+        Returns:
+            The ``Option`` returned by *f*.
+        """
+        return f(self.value)
+
+    def ok_or[E](self, err: E) -> Result[T, E]:
+        """Convert to ``Ok``, ignoring *err*.
+
+        Args:
+            err: The error value (discarded).
+
+        Returns:
+            ``Ok(self.value)``.
+        """
+        from .result import Ok as ResultOk
+        return ResultOk(self.value)
+
+    def ok_or_else[E](self, err_fn: Callable[[], E]) -> Result[T, E]:
+        """Convert to ``Ok``, ignoring *err_fn*.
+
+        Args:
+            err_fn: A function producing an error (not called).
+
+        Returns:
+            ``Ok(self.value)``.
+        """
+        from .result import Ok as ResultOk
+        return ResultOk(self.value)
+
+    def is_some(self) -> bool:
+        """True if this is a ``Some`` value."""
+        return True
+
+    def is_none(self) -> bool:
+        """False — this is a ``Some``."""
+        return False
+
+    def __repr__(self) -> str:
+        return f'Some({self.value!r})'
+
+
+@final
+class Nothing:
+    """Represents an absent value (singleton)."""
+
+    __match_args__ = ()
+    _instance: Nothing | None = None
+
+    def __new__(cls) -> Nothing:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def unwrap(self) -> None:
+        """Raise — cannot unwrap ``Nothing``."""
+        raise ValueError('Called unwrap on Nothing')
+
+    def unwrap_or[T](self, default: T) -> T:
+        """Return *default*.
+
+        Args:
+            default: The fallback value.
+
+        Returns:
+            *default* unchanged.
+        """
+        return default
+
+    def ok_or[T, E](self, err: E) -> Result[T, E]:
+        """Convert to ``Err`` using *err*.
+
+        Args:
+            err: The error value.
+
+        Returns:
+            ``Err(err)``.
+        """
+        from .result import Err as ResultErr
+        return ResultErr(err)
+
+    def ok_or_else[T, E](self, err_fn: Callable[[], E]) -> Result[T, E]:
+        """Convert to ``Err`` by calling *err_fn*.
+
+        Args:
+            err_fn: A function producing the error value.
+
+        Returns:
+            ``Err(err_fn())``.
+        """
+        from .result import Err as ResultErr
+        return ResultErr(err_fn())
+
+    def map[U](self, f: Callable[[Any], U]) -> Nothing:
+        """No-op — returns ``Nothing`` unchanged.
+
+        Args:
+            f: The function (not called).
+
+        Returns:
+            ``self`` (``Nothing``).
+        """
+        return self
+
+    def and_then[U](self, f: Callable[[Any], Option[U]]) -> Nothing:
+        """No-op — returns ``Nothing`` unchanged.
+
+        Args:
+            f: The function (not called).
+
+        Returns:
+            ``self`` (``Nothing``).
+        """
+        return self
+
+    def is_some(self) -> bool:
+        """False — this is ``Nothing``."""
+        return False
+
+    def is_none(self) -> bool:
+        """True if this is ``Nothing``."""
+        return True
+
+    def __repr__(self) -> str:
+        return 'Nothing'

pional-0.1.0/src/pional/adts/result.py

@@ -0,0 +1,251 @@
+"""Result type — represents success (``Ok``) or failure (``Err``).
+
+Provides monadic operations and combinators for working with fallible
+computations in a type-safe way.
+"""
+from __future__ import annotations
+
+from typing import final, Callable, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .option import Option, Nothing
+
+type Result[T, E] = Ok[T] | Err[E]
+
+
+@final
+class Ok[T]:
+    """Represents a successful result containing a value."""
+
+    __match_args__ = ('value',)
+
+    def __init__(self, value: T) -> None:
+        self.value = value
+
+    def unwrap(self) -> T:
+        """Return the inner value."""
+        return self.value
+
+    def unwrap_or(self, default: T) -> T:
+        """Return the inner value, ignoring *default*."""
+        return self.value
+
+    def map[U](self, f: Callable[[T], U]) -> Ok[U]:
+        """Transform the inner value using *f*.
+
+        Args:
+            f: The function to apply.
+
+        Returns:
+            ``Ok(f(self.value))``.
+        """
+        return Ok(f(self.value))
+
+    def map_err(self, f: Callable[[Any], Any]) -> Ok[T]:
+        """No-op — returns ``self`` unchanged."""
+        return self
+
+    def and_then[U, F](self, f: Callable[[T], Result[U, F]]) -> Result[U, F]:
+        """Apply *f* to the inner value and return the result.
+
+        Args:
+            f: A function returning a ``Result``.
+
+        Returns:
+            The ``Result`` returned by *f*.
+        """
+        return f(self.value)
+
+    def ok(self) -> Option[T]:
+        """Convert to ``Some(self.value)``."""
+        from .option import Some as OptionSome
+        return OptionSome(self.value)
+
+    def err(self) -> Nothing:
+        """Always returns ``Nothing`` — this is an ``Ok``."""
+        from .option import Nothing as OptionNothing
+        return OptionNothing()
+
+    def map_or[U](self, default: U, f: Callable[[T], U]) -> U:
+        """Apply *f* to the inner value, ignoring *default*.
+
+        Args:
+            default: The fallback (ignored).
+            f: The function to apply.
+
+        Returns:
+            ``f(self.value)``.
+        """
+        return f(self.value)
+
+    def map_or_else[U](self, default: Callable[[Any], U], f: Callable[[T], U]) -> U:
+        """Apply *f* to the inner value, ignoring *default*.
+
+        Args:
+            default: The fallback function (not called).
+            f: The function to apply.
+
+        Returns:
+            ``f(self.value)``.
+        """
+        return f(self.value)
+
+    def combine[U, E](self, other: Result[U, E]) -> Result[tuple[T, U], E]:
+        """Pair this ``Ok`` with *other*.
+
+        Args:
+            other: Another ``Result``.
+
+        Returns:
+            ``Ok((self.value, v))`` if *other* is ``Ok(v)``,
+            otherwise propagates the ``Err``.
+        """
+        match other:
+            case Ok(v):
+                return Ok((self.value, v))
+            case Err(e):
+                return Err(e)
+
+    def combine_with[U, V, E](self, other: Result[U, E], f: Callable[[T, U], V]) -> Result[V, E]:
+        """Combine this ``Ok`` with *other* using *f*.
+
+        Args:
+            other: Another ``Result``.
+            f: The merge function.
+
+        Returns:
+            ``Ok(f(self.value, v))`` if *other* is ``Ok(v)``,
+            otherwise propagates the ``Err``.
+        """
+        match other:
+            case Ok(v):
+                return Ok(f(self.value, v))
+            case Err(e):
+                return Err(e)
+
+    def is_ok(self) -> bool:
+        """True if this is an ``Ok`` value."""
+        return True
+
+    def is_err(self) -> bool:
+        """False — this is an ``Ok``."""
+        return False
+
+    def __repr__(self) -> str:
+        return f'Ok({self.value!r})'
+
+
+@final
+class Err[E]:
+    """Represents a failure result containing an error value."""
+
+    __match_args__ = ('value',)
+
+    def __init__(self, value: E) -> None:
+        self.value = value
+
+    def unwrap(self) -> None:
+        """Raise — cannot unwrap an ``Err``."""
+        raise ValueError(f'Called unwrap on Err: {self.value}')
+
+    def unwrap_or[T](self, default: T) -> T:
+        """Return *default*.
+
+        Args:
+            default: The fallback value.
+
+        Returns:
+            *default* unchanged.
+        """
+        return default
+
+    def unwrap_err(self) -> E:
+        """Return the inner error value."""
+        return self.value
+
+    def map[U](self, f: Callable[[Any], U]) -> Err[E]:
+        """No-op — returns ``self`` unchanged."""
+        return self
+
+    def map_err[F](self, f: Callable[[E], F]) -> Err[F]:
+        """Transform the error value using *f*.
+
+        Args:
+            f: The function to apply.
+
+        Returns:
+            ``Err(f(self.value))``.
+        """
+        return Err(f(self.value))
+
+    def and_then[U](self, f: Callable[[Any], Result[U, Any]]) -> Err[E]:
+        """No-op — returns ``self`` unchanged."""
+        return self
+
+    def ok(self) -> Nothing:
+        """Always returns ``Nothing`` — this is an ``Err``."""
+        from .option import Nothing as OptionNothing
+        return OptionNothing()
+
+    def err(self) -> Option[E]:
+        """Convert to ``Some(self.value)``."""
+        from .option import Some as OptionSome
+        return OptionSome(self.value)
+
+    def map_or[T, U](self, default: U, f: Callable[[T], U]) -> U:
+        """Return *default*, ignoring *f*.
+
+        Args:
+            default: The fallback value.
+            f: The function (not called).
+
+        Returns:
+            *default* unchanged.
+        """
+        return default
+
+    def map_or_else[U](self, default: Callable[[E], U], f: Callable[[Any], U]) -> U:
+        """Call *default* with the error value.
+
+        Args:
+            default: The fallback function.
+            f: The function (not called).
+
+        Returns:
+            ``default(self.value)``.
+        """
+        return default(self.value)
+
+    def combine[T, U](self, other: Result[U, E]) -> Result[tuple[T, U], E]:
+        """Propagate this ``Err`` — ignores *other*.
+
+        Args:
+            other: Another ``Result`` (ignored).
+
+        Returns:
+            ``self`` (the error).
+        """
+        return self  # type: ignore
+
+    def combine_with[T, U, V](self, other: Result[U, E], f: Callable[[T, U], V]) -> Result[V, E]:
+        """Propagate this ``Err`` — ignores *other* and *f*.
+
+        Args:
+            other: Another ``Result`` (ignored).
+            f: The merge function (not called).
+
+        Returns:
+            ``self`` (the error).
+        """
+        return self  # type: ignore
+
+    def is_ok(self) -> bool:
+        """False — this is an ``Err``."""
+        return False
+
+    def is_err(self) -> bool:
+        """True if this is an ``Err`` value."""
+        return True
+
+    def __repr__(self) -> str:
+        return f'Err({self.value!r})'

pional-0.1.0/src/pional/collections/__init__.py

@@ -0,0 +1,10 @@
+"""Collection types — Vec, HashMap, HashSet."""
+from .vec import Vec
+from .hashmap import HashMap
+from .hashset import HashSet
+
+__all__ = [
+    "Vec",
+    "HashMap",
+    "HashSet",
+]

pional-0.1.0/src/pional/collections/base.py

@@ -0,0 +1,20 @@
+"""Base abstraction for collection types."""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Self
+
+if TYPE_CHECKING:
+    from pional.iterators import IteratorExt, Iter
+
+
+class CollectionExt[T](ABC):
+    """Abstract base for collections that can be constructed from iterators."""
+
+    @abstractmethod
+    def into_iter(self) -> Iter[T]:
+        """Consume and convert into an ``Iter``."""
+
+    @classmethod
+    @abstractmethod
+    def from_iter(cls, iterator: IteratorExt[T]) -> Self:
+        """Construct an instance from an ``IteratorExt``."""