fnkit 0.5.0__py3-none-any.whl

fnkit/option.py

@@ -0,0 +1,54 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class Option[T](Protocol):
+    def map[U](self, fn: Callable[[T], U]) -> Option[U]: ...
+    def bind[U](self, fn: Callable[[T], Option[U]]) -> Option[U]: ...
+    def just_or(self, fn: Callable[[], T]) -> T: ...
+
+
+def pure[T](v: T) -> Option[T]:
+    return Just(v)
+
+
+def lift[A, B, C](fn: Callable[[A, B], C]) -> Callable[[Option[A], Option[B]], Option[C]]:
+    def _inner(a: Option[A], b: Option[B]) -> Option[C]:
+        return a.bind(lambda w: b.map(lambda v: fn(w, v)))
+
+    return _inner
+
+
+@dataclass(frozen=True, slots=True)
+class Just[T](Option[T]):
+    v: T
+
+    def map[U](self, fn: Callable[[T], U]) -> Just[U]:
+        return Just(fn(self.v))
+
+    def bind[U](self, fn: Callable[[T], Option[U]]) -> Option[U]:
+        return fn(self.v)
+
+    def just_or(self, fn: Callable[[], T]) -> T:
+        return self.v
+
+
+class Nothing[T](Option[T]):
+    def map[U](self, fn: Callable[[T], U]) -> Option[U]:
+        return self  # type: ignore
+
+    def bind[U](self, fn: Callable[[T], Option[U]]) -> Option[U]:
+        return self  # type: ignore
+
+    def just_or(self, fn: Callable[[], T]) -> T:
+        return fn()
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, Nothing)
+
+    def __hash__(self) -> int:
+        return hash(Nothing)
+
+    def __repr__(self) -> str:
+        return "Nothing()"

fnkit/result.py

@@ -0,0 +1,57 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class Result[T, E](Protocol):
+    def map[U](self, fn: Callable[[T], U]) -> Result[U, E]: ...
+    def map_err[F](self, fn: Callable[[E], F]) -> Result[T, F]: ...
+    def bind[U](self, fn: Callable[[T], Result[U, E]]) -> Result[U, E]: ...
+    def ok_or(self, fn: Callable[[E], T]) -> T: ...
+
+
+def pure[T, E = Exception](v: T) -> Result[T, E]:
+    return Ok(v)
+
+
+def lift[A, B, C, E](
+    fn: Callable[[A, B], C],
+) -> Callable[[Result[A, E], Result[B, E]], Result[C, E]]:
+    def _inner(a: Result[A, E], b: Result[B, E]) -> Result[C, E]:
+        return a.bind(lambda w: b.map(lambda v: fn(w, v)))
+
+    return _inner
+
+
+@dataclass(frozen=True, slots=True)
+class Ok[T, E](Result[T, E]):
+    v: T
+
+    def map[U](self, fn: Callable[[T], U]) -> Result[U, E]:
+        return Ok(fn(self.v))
+
+    def map_err[F](self, fn: Callable[[E], F]) -> Result[T, F]:
+        return self  # type: ignore
+
+    def bind[U](self, fn: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        return fn(self.v)
+
+    def ok_or(self, fn: Callable[[E], T]) -> T:
+        return self.v
+
+
+@dataclass(frozen=True, slots=True)
+class Err[T, E](Result[T, E]):
+    v: E
+
+    def map[U](self, fn: Callable[[T], U]) -> Result[U, E]:
+        return self  # type: ignore
+
+    def bind[U](self, fn: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        return self  # type: ignore
+
+    def ok_or(self, fn: Callable[[E], T]) -> T:
+        return fn(self.v)
+
+    def map_err[F](self, fn: Callable[[E], F]) -> Result[T, F]:
+        return Err(fn(self.v))

fnkit/state.py

@@ -0,0 +1,46 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from types import NoneType
+
+
+@dataclass(frozen=True)
+class State[S, A]:
+    run_state: Callable[[S], tuple[A, S]]
+
+    def map[B](self, fn: Callable[[A], B]) -> State[S, B]:
+        def _composed(s: S) -> tuple[B, S]:
+            v = self.run_state(s)
+            return fn(v[0]), v[1]
+
+        return State(_composed)
+
+    def map_state[Y](self, sy: Callable[[S], Y], ys: Callable[[Y], S]) -> State[Y, A]:
+        def _inner(y: Y) -> tuple[A, Y]:
+            s = ys(y)
+            a, s1 = self.run_state(s)
+            return a, sy(s1)
+
+        return State(_inner)
+
+    def bind[B](self, fn: Callable[[A], State[S, B]]) -> State[S, B]:
+        def _inner(s: S) -> tuple[B, S]:
+            a, s1 = self.run_state(s)
+            return fn(a).run_state(s1)
+
+        return State(_inner)
+
+
+def pure[A, S = NoneType](v: A) -> State[S, A]:
+    return State(lambda s: (v, s))
+
+
+def lift[A, B, C, S](fn: Callable[[A, B], C]) -> Callable[[State[S, A], State[S, B]], State[S, C]]:
+    def _inner(a: State[S, A], b: State[S, B]) -> State[S, C]:
+        def _run_state(s: S) -> tuple[C, S]:
+            v1, s1 = a.run_state(s)
+            v2, s2 = b.run_state(s1)
+            return fn(v1, v2), s2
+
+        return State(_run_state)
+
+    return _inner

fnkit/transformers.py

@@ -0,0 +1,47 @@
+from collections.abc import Callable
+
+from fnkit.option import Just, Option
+from fnkit.result import Ok, Result
+from fnkit.state import State
+
+
+def r_bindt[S, A, B, E](
+    state: State[S, Result[A, E]],
+    fn: Callable[[A], State[S, Result[B, E]]],
+) -> State[S, Result[B, E]]:
+    """
+    r_bindt :: State s (Result a e) ->
+               (a -> State s (Result b e)) ->
+               State s (Result b e)
+    """
+
+    def _inner(s: S) -> tuple[Result[B, E], S]:
+        result, s1 = state.run_state(s)
+        match result:
+            case Ok(value):
+                return fn(value).run_state(s1)
+            case _:
+                return result, s1  # type: ignore
+
+    return State(_inner)
+
+
+def o_bindt[S, A, B](
+    state: State[S, Option[A]],
+    fn: Callable[[A], State[S, Option[B]]],
+) -> State[S, Option[B]]:
+    """
+    o_bindt :: State s (Option a) ->
+               (a -> State s (Option b)) ->
+               State s (Option b)
+    """
+
+    def _inner(s: S) -> tuple[Option[B], S]:
+        result, s1 = state.run_state(s)
+        match result:
+            case Just(value):
+                return fn(value).run_state(s1)
+            case _:
+                return result, s1  # type: ignore
+
+    return State(_inner)

fnkit-0.5.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: fnkit
+Version: 0.5.0
+Summary: Slightly alternative way to write the code
+Keywords: functional,monad,option,result,state,types
+Author: Vitaliy Muminov
+Author-email: Vitaliy Muminov <vitaliy.muminov+github@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/vmuminov/fnkit
+Project-URL: Repository, https://github.com/vmuminov/fnkit
+Project-URL: Issues, https://github.com/vmuminov/fnkit/issues
+Description-Content-Type: text/markdown
+
+# fnkit
+
+[![PyPI version](https://img.shields.io/pypi/v/fnkit)](https://pypi.org/project/fnkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fnkit)](https://pypi.org/project/fnkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/github/actions/workflow/status/vmuminov/fnkit/tests.yml?label=tests)](https://github.com/vmuminov/fnkit/actions)
+
+Typed functional programming primitives for Python 3.14, built on native PEP 695 generics.
+
+`Option`, `Result`, and `State` give you composable, type-checked alternatives to `None`
+checks, exception-driven error handling, and hand-rolled state threading, without a
+class hierarchy to inherit from and without losing type information along the way.
+
+## Why this exists
+
+Most Python functional-programming libraries predate PEP 695 and still lean on
+`TypeVar` and `Generic[T]`. This library is built from the ground up on Python 3.14's
+native generic syntax (`class Foo[T]`, `def bar[T, E = Default]`), structural
+`Protocol`s instead of inheritance, and `match` statements for unwrapping values.
+
+## Features
+
+- **`Option[T]`**: a `Just` / `Nothing` pair for values that may or may not exist,
+  replacing `None`-based optionality with a type-checked container.
+- **`Result[T, E]`**: an `Ok` / `Err` pair for computations that may fail, replacing
+  exception-driven control flow with explicit, inspectable failure values.
+- **`State[S, A]`**: a composable wrapper around `S -> (A, S)` functions, for
+  threading state through a pipeline without mutation or global variables.
+- **Monad transformers** (`o_bindt`, `r_bindt`): compose `State` with `Option` or
+  `Result` directly, so a stateful computation can short-circuit on `Nothing` or
+  `Err` without manual unwrapping at every step.
+- **`map` / `bind` / `lift`** across all three types, for a consistent functional
+  interface regardless of which container you are working with.
+- Fully immutable: every type is a frozen, slotted dataclass. No shared mutable
+  state, no reference cycles.
+- Structural typing throughout: `Option`, `Result`, and `State` are `Protocol`s, so
+  you can write your own conforming implementations without subclassing.
+
+## Requirements
+
+Python 3.14 or later.
+
+## Installation
+
+```bash
+pip install fnkit
+```
+
+## Quick examples
+
+### Option
+
+```python
+from fnkit.option import Just, Nothing, Option, pure
+
+def find_user(name: str) -> Option[str]:
+    return Just(name) if name == "ada" else Nothing()
+
+result = (
+    find_user("ada")
+    .map(str.upper)
+    .bind(lambda name: Just(f"hello, {name}"))
+    .just_or(lambda: "user not found")
+)
+print(result)  # hello, ADA
+```
+
+### Result
+
+```python
+from fnkit.result import Err, Ok, Result
+
+def parse_positive(raw: str) -> Result[int, str]:
+    value = int(raw)
+    return Ok(value) if value > 0 else Err(f"{value} is not positive")
+
+result = (
+    parse_positive("42")
+    .map(lambda n: n * 2)
+    .map_err(lambda e: f"parse failed: {e}")
+    .ok_or(lambda e: -1)
+)
+print(result)  # 84
+```
+
+### State
+
+```python
+from fnkit.state import State, pure
+
+def push[T](item: T) -> State[list[T], None]:
+    def run(stack: list[T]) -> tuple[None, list[T]]:
+        return None, [*stack, item]
+    return State(run)
+
+def pop[T]() -> State[list[T], T]:
+    def run(stack: list[T]) -> tuple[T, list[T]]:
+        return stack[-1], stack[:-1]
+    return State(run)
+
+program = push(1).bind(lambda _: push(2)).bind(lambda _: pop())
+value, final_state = program.run_state([])
+print(value, final_state)  # 2 [1]
+```
+
+### Combining State with Result or Option
+
+```python
+from fnkit.result import Err, Ok, Result
+from fnkit.state import State
+from fnkit.transformers import r_bindt
+
+def read_and_validate(state: State[int, Result[int, str]]) -> State[int, Result[int, str]]:
+    def validate(value: int) -> State[int, Result[int, str]]:
+        if value < 0:
+            return State(lambda s: (Err("negative value"), s))
+        return State(lambda s: (Ok(value * 2), s))
+
+    return r_bindt(state, validate)
+```
+
+## Design notes
+
+- `Nothing`, `Ok`, and `Err` compare and hash by value, not by identity, since all
+  three are plain frozen dataclasses.
+- `State` compares and hashes by function identity, since two closures cannot be
+  compared for behavioral equality in general. Do not rely on `State() == State()`
+  for anything other than the same object.
+- `lift` for `Option` and `Result` evaluates its first argument before its second,
+  so when both sides are `Nothing`/`Err`, the first argument's failure is the one
+  that propagates. This matches left-to-right short-circuiting.
+
+## License
+
+MIT. See `LICENSE` for the full text.

fnkit-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fnkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fnkit/option.py,sha256=MnUl3vikjfCy1xlocvuc7f5SzlDcCZP63Pda9UB9aG0,1426
+fnkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fnkit/result.py,sha256=Oz5wfICCjIKGiY_fnL0zcJ9RAnlTLoOzlpSmhwnu4R8,1610
+fnkit/state.py,sha256=5ABdWNCJZPMEUPNHcS8H2BziFfbPTIMLRdktBsurzbM,1312
+fnkit/transformers.py,sha256=ssQ4LowNLNo7AqI-Pcis7g-mOhByw0wq47SanjTss6k,1237
+fnkit-0.5.0.dist-info/WHEEL,sha256=YR4QUxGCbsyoOnWBVTv-p1I4yc3seKGPev46mvmc8Cg,81
+fnkit-0.5.0.dist-info/METADATA,sha256=TECsT2QHgl5Rl0-OutNiWvoUAF2r3re9IoL--Zkwz0c,5434
+fnkit-0.5.0.dist-info/RECORD,,

fnkit-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.29
+Root-Is-Purelib: true
+Tag: py3-none-any