pional 0.1.0__py3-none-any.whl

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/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/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/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/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/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``."""

pional/collections/hashmap.py

@@ -0,0 +1,90 @@
+"""HashMap — a hash map wrapping ``dict``."""
+from __future__ import annotations
+from collections.abc import (
+    Iterable,
+    MutableMapping,
+    Mapping,
+)
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from pional.iterators import Iter, IteratorExt
+from pional.adts import Option, Some, Nothing
+
+from .base import CollectionExt
+
+
+class HashMap[K, V](MutableMapping[K, V], CollectionExt[tuple[K, V]]):
+    """A mutable hash map backed by ``dict``."""
+
+    def __init__(
+        self,
+        items: Mapping[K, V] | Iterable[tuple[K, V]] = (),
+    ):
+        self._data: dict[K, V] = dict(items)
+
+    def __str__(self) -> str:
+        return f"HashMap({self._data})"
+
+    def __repr__(self) -> str:
+        return f"HashMap({self._data!r})"
+
+    def __getitem__(self, key: K) -> V:
+        return self._data[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        self._data[key] = value
+
+    def __delitem__(self, key: K) -> None:
+        del self._data[key]
+
+    def __iter__(self) -> Iter[tuple[K, V]]:
+        return self.into_iter()
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def keys(self) -> Iter[K]:
+        """Return an iterator over keys."""
+        return Iter(self._data.keys())
+
+    def values(self) -> Iter[V]:
+        """Return an iterator over values."""
+        return Iter(self._data.values())
+
+    def into_iter(self) -> Iter[tuple[K, V]]:
+        """Consume and convert into an ``Iter`` of ``(key, value)`` pairs."""
+        from pional.iterators import Iter
+        return Iter(self._data.items())
+
+    def insert(self, key: K, value: V) -> None:
+        """Insert a key-value pair.
+
+        Args:
+            key: The key.
+            value: The associated value.
+        """
+        self._data[key] = value
+
+    def remove(self, key: K) -> Option[V]:
+        """Remove the value associated with *key*.
+
+        Args:
+            key: The key to remove.
+
+        Returns:
+            ``Some(V)`` if the key existed, ``Nothing`` otherwise.
+        """
+        try:
+            return Some(self._data.pop(key))
+        except KeyError:
+            return Nothing()
+
+    def contains(self, key: K) -> bool:
+        """True if *key* exists in the map."""
+        return key in self._data
+
+    @classmethod
+    def from_iter(cls, iterator: IteratorExt[tuple[K, V]]) -> HashMap[K, V]:
+        """Construct a ``HashMap`` from an ``IteratorExt`` of pairs."""
+        return HashMap(iterator)

pional/collections/hashset.py

@@ -0,0 +1,61 @@
+"""HashSet — a hash set wrapping ``set``."""
+from __future__ import annotations
+from collections.abc import (
+    Iterable,
+    MutableSet,
+)
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pional.iterators import Iter, IteratorExt
+
+from .base import CollectionExt
+
+
+class HashSet[T](MutableSet[T], CollectionExt[T]):
+    """A mutable hash set backed by ``set``."""
+
+    def __init__(self, items: Iterable[T] = ()):
+        self._set: set[T] = set(items)
+
+    def __str__(self) -> str:
+        return f"HashSet({self._set})"
+
+    def __repr__(self) -> str:
+        return f"HashMap({self._set!r})"
+
+    def __contains__(self, item: T) -> bool:
+        return item in self._set
+
+    def __iter__(self) -> Iter[T]:
+        return self.into_iter()
+
+    def __len__(self) -> int:
+        return len(self._set)
+
+    def add(self, value: T) -> None:
+        """Add *value* to the set."""
+        self._set.add(value)
+
+    def insert(self, value: T) -> None:
+        """Alias for ``add``."""
+        self._set.add(value)
+
+    def contains(self, value: T) -> bool:
+        """True if *value* is in the set."""
+        return value in self._set
+
+    def discard(self, value: T) -> None:
+        """Remove *value* if present, otherwise no-op."""
+        self._set.discard(value)
+
+    def into_iter(self) -> Iter[T]:
+        """Consume and convert into an ``Iter``."""
+        from pional.iterators import Iter
+        return Iter(self._set)
+
+    @classmethod
+    def from_iter(cls, iterator: IteratorExt[T]) -> HashSet[T]:
+        """Construct a ``HashSet`` from an ``IteratorExt``."""
+        return HashSet(iterator)