uogtad 0.2.0__tar.gz

uogtad-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 uogtad contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uogtad-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: uogtad
+Version: 0.2.0
+Summary: Typed functional control containers for Python
+Author: uogtad contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/blakehawkins/uogtad
+Project-URL: Issues, https://github.com/blakehawkins/uogtad/issues
+Project-URL: Repository, https://github.com/blakehawkins/uogtad.git
+Keywords: either,functional-programming,maybe,result,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.15
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: hypothesis>=6; extra == "test"
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.19; extra == "typecheck"
+Requires-Dist: pyright>=1.1.408; extra == "typecheck"
+Dynamic: license-file
+
+# uoɥʇʎd
+
+[![CI](https://github.com/blakehawkins/uogtad/actions/workflows/ci.yml/badge.svg)](https://github.com/blakehawkins/uogtad/actions/workflows/ci.yml)
+[![Python 3.15](https://img.shields.io/badge/python-3.15-blue.svg)](https://docs.python.org/3.15/)
+[![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
+[![Pyright](https://img.shields.io/badge/pyright-checked-blue.svg)](https://github.com/microsoft/pyright)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/license/mit)
+
+A functional control library for python in the same vein as io.vavr.control for java.
+
+Provides three immutable, typed control containers:
+
+```python
+Either.new(value)       # Left(value)
+Either.right(error)     # Right(error)
+Maybe.new(value)        # Some(value), even when value is None
+Maybe.empty()           # Empty()
+Maybe.of_optional(value) # Empty() for None, otherwise Some(value)
+Fallible(computation)   # captures Exception, but not KeyboardInterrupt/SystemExit
+Fallible(computation, ValueError)  # captures only ValueError (and subclasses)
+```
+
+Example usage:
+
+```python
+from typing import Literal
+
+from uogtad import Either, Fallible
+
+def raises() -> str:
+    raise RuntimeError("tada")
+
+tada = Fallible(raises).as_result().swap().map(lambda exc: str(exc.args[0])).narrow().narrow()
+assert tada == "tada"
+
+# Unexpected exceptions remain bugs instead of becoming values. A tuple works
+# just like an ``except`` clause when several exception types are expected.
+parsed = Fallible(lambda: int("not a number"), (ValueError, RuntimeError))
+if failure := parsed.maybe_exception():
+    # ``failure.value`` is statically narrowed to ValueError | RuntimeError.
+    assert isinstance(failure.value, ValueError)
+
+def categorise(num: int) -> Either[Literal['A'], Literal['B']]:
+    if num == 0:
+        return Either.new('A')  # Either is left-biased, like Result[T, E].
+    return Either.right('B')
+
+results = list(map(categorise, [0, 1, 0, 2, 0, 3]))
+assert [result.is_left() for result in results] == [True, False, True, False, True, False]
+
+result = categorise(0)
+if left := result.maybe_left():
+    # Static checkers narrow `left` to Left[Literal['A']].
+    assert left.value == "A"
+
+```
+
+
+# Ops
+
+Install the latest release from PyPI (Python 3.15 or newer):
+
+```shell
+python -m pip install uogtad
+```
+
+Install the current `master` branch directly from GitHub (Python 3.15 or newer)
+with pip:
+
+```shell
+python -m pip install "uogtad @ git+https://github.com/blakehawkins/uogtad.git@master"
+```
+
+Or add the same PyPI-compatible Git dependency to a Pixi project:
+
+```shell
+pixi add --pypi "uogtad @ git+https://github.com/blakehawkins/uogtad.git@master"
+```
+
+Run the test suite:
+
+```shell
+pixi run python -m pytest
+```
+
+Build and validate the PyPI distributions:
+
+```shell
+pixi run package
+```
+
+### Releases
+
+Releases use [Release Please](https://github.com/googleapis/release-please#readme)
+and [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so no
+GitHub repository secrets are required.
+
+## Comparison with other libraries
+
+[`returns`](https://returns.readthedocs.io/) is a broad collection of typed
+functional abstractions, including IO-aware and asynchronous containers. Its
+decorators, point-free helpers, and `flow` utilities encourage building
+annotated function pipelines. Choose it when an application benefits from that
+larger functional-programming ecosystem and composition style.
+
+[`Expression`](https://expression.readthedocs.io/) is inspired by F# and
+provides discriminated unions, computation expressions, immutable collections,
+and functional utilities in addition to `Option` and `Result`. Its decorators,
+free functions, and `pipe` helpers support an F#-style pipeline-oriented
+application design. Choose it when those abstractions should shape more of the
+application.
+
+`uogtad` deliberately has a smaller scope: `Either`, `Maybe`, and `Fallible`,
+with operations exposed directly as methods. It intentionally avoids
+decorator-driven control flow, free-function combinators, and a pipeline DSL.
+Choose it when ordinary method chaining, Python pattern matching, and a compact
+API are preferable.

uogtad-0.2.0/README.md

@@ -0,0 +1,117 @@
+# uoɥʇʎd
+
+[![CI](https://github.com/blakehawkins/uogtad/actions/workflows/ci.yml/badge.svg)](https://github.com/blakehawkins/uogtad/actions/workflows/ci.yml)
+[![Python 3.15](https://img.shields.io/badge/python-3.15-blue.svg)](https://docs.python.org/3.15/)
+[![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
+[![Pyright](https://img.shields.io/badge/pyright-checked-blue.svg)](https://github.com/microsoft/pyright)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/license/mit)
+
+A functional control library for python in the same vein as io.vavr.control for java.
+
+Provides three immutable, typed control containers:
+
+```python
+Either.new(value)       # Left(value)
+Either.right(error)     # Right(error)
+Maybe.new(value)        # Some(value), even when value is None
+Maybe.empty()           # Empty()
+Maybe.of_optional(value) # Empty() for None, otherwise Some(value)
+Fallible(computation)   # captures Exception, but not KeyboardInterrupt/SystemExit
+Fallible(computation, ValueError)  # captures only ValueError (and subclasses)
+```
+
+Example usage:
+
+```python
+from typing import Literal
+
+from uogtad import Either, Fallible
+
+def raises() -> str:
+    raise RuntimeError("tada")
+
+tada = Fallible(raises).as_result().swap().map(lambda exc: str(exc.args[0])).narrow().narrow()
+assert tada == "tada"
+
+# Unexpected exceptions remain bugs instead of becoming values. A tuple works
+# just like an ``except`` clause when several exception types are expected.
+parsed = Fallible(lambda: int("not a number"), (ValueError, RuntimeError))
+if failure := parsed.maybe_exception():
+    # ``failure.value`` is statically narrowed to ValueError | RuntimeError.
+    assert isinstance(failure.value, ValueError)
+
+def categorise(num: int) -> Either[Literal['A'], Literal['B']]:
+    if num == 0:
+        return Either.new('A')  # Either is left-biased, like Result[T, E].
+    return Either.right('B')
+
+results = list(map(categorise, [0, 1, 0, 2, 0, 3]))
+assert [result.is_left() for result in results] == [True, False, True, False, True, False]
+
+result = categorise(0)
+if left := result.maybe_left():
+    # Static checkers narrow `left` to Left[Literal['A']].
+    assert left.value == "A"
+
+```
+
+
+# Ops
+
+Install the latest release from PyPI (Python 3.15 or newer):
+
+```shell
+python -m pip install uogtad
+```
+
+Install the current `master` branch directly from GitHub (Python 3.15 or newer)
+with pip:
+
+```shell
+python -m pip install "uogtad @ git+https://github.com/blakehawkins/uogtad.git@master"
+```
+
+Or add the same PyPI-compatible Git dependency to a Pixi project:
+
+```shell
+pixi add --pypi "uogtad @ git+https://github.com/blakehawkins/uogtad.git@master"
+```
+
+Run the test suite:
+
+```shell
+pixi run python -m pytest
+```
+
+Build and validate the PyPI distributions:
+
+```shell
+pixi run package
+```
+
+### Releases
+
+Releases use [Release Please](https://github.com/googleapis/release-please#readme)
+and [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so no
+GitHub repository secrets are required.
+
+## Comparison with other libraries
+
+[`returns`](https://returns.readthedocs.io/) is a broad collection of typed
+functional abstractions, including IO-aware and asynchronous containers. Its
+decorators, point-free helpers, and `flow` utilities encourage building
+annotated function pipelines. Choose it when an application benefits from that
+larger functional-programming ecosystem and composition style.
+
+[`Expression`](https://expression.readthedocs.io/) is inspired by F# and
+provides discriminated unions, computation expressions, immutable collections,
+and functional utilities in addition to `Option` and `Result`. Its decorators,
+free functions, and `pipe` helpers support an F#-style pipeline-oriented
+application design. Choose it when those abstractions should shape more of the
+application.
+
+`uogtad` deliberately has a smaller scope: `Either`, `Maybe`, and `Fallible`,
+with operations exposed directly as methods. It intentionally avoids
+decorator-driven control flow, free-function combinators, and a pipeline DSL.
+Choose it when ordinary method chaining, Python pattern matching, and a compact
+API are preferable.

uogtad-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uogtad"
+version = "0.2.0"
+description = "Typed functional control containers for Python"
+readme = "README.md"
+requires-python = ">=3.15"
+license = "MIT"
+authors = [{name = "uogtad contributors"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+keywords = ["either", "functional-programming", "maybe", "result", "typing"]
+
+[project.urls]
+Homepage = "https://github.com/blakehawkins/uogtad"
+Issues = "https://github.com/blakehawkins/uogtad/issues"
+Repository = "https://github.com/blakehawkins/uogtad.git"
+
+[project.optional-dependencies]
+test = ["hypothesis>=6", "pytest>=7"]
+typecheck = ["mypy>=1.19", "pyright>=1.1.408"]
+
+[tool.setuptools.package-data]
+uogtad = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["uogtad"]
+
+[tool.mypy]
+strict = true
+files = ["uogtad"]
+
+[tool.pyright]
+pythonVersion = "3.15"
+
+[tool.pixi.workspace]
+channels = ["conda-forge/label/python_rc", "conda-forge"]
+platforms = ["linux-64"]
+
+[tool.pixi.dependencies]
+python = "3.15.*"
+pip = ">=25"
+
+[tool.pixi.pypi-dependencies]
+build = ">=1"
+twine = ">=6"
+
+[tool.pixi.tasks]
+package = "rm -rf build dist *.egg-info && python -m build && python -m twine check --strict dist/*"

uogtad-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uogtad-0.2.0/uogtad/__init__.py

@@ -0,0 +1,7 @@
+"""Small, typed containers for functional-style control flow."""
+
+from uogtad.either import Either, Left, Right
+from uogtad.fallible import Fallible
+from uogtad.maybe import Empty, Maybe, Some
+
+__all__ = ["Either", "Left", "Right", "Maybe", "Some", "Empty", "Fallible"]

uogtad-0.2.0/uogtad/either.py

@@ -0,0 +1,139 @@
+"""The two-case :class:`Either` container."""
+
+from dataclasses import dataclass
+from typing import Callable, Never
+
+lazy import uogtad.maybe as maybe_module
+
+
+class Either[T, U]:
+    """A value in exactly one of two cases: :class:`Left` or :class:`Right`."""
+
+    @classmethod
+    def new(cls, value: T) -> Either[T, U]:
+        """Create a left value (``Either`` is left-biased)."""
+        return Left[T, U](value)
+
+    @classmethod
+    def right(cls, value: U) -> Either[T, U]:
+        """Create a right value."""
+        return Right[U, T](value)
+
+    def is_left(self) -> bool:
+        match self:
+            case Left():
+                return True
+            case Right():
+                return False
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def is_right(self) -> bool:
+        return not self.is_left()
+
+    def maybe_left(self) -> Left[T, U] | None:
+        """Return the concrete left variant, or ``None`` when this is right."""
+        match self:
+            case Left() as left:
+                return left
+            case Right():
+                return None
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def maybe_right(self) -> Right[U, T] | None:
+        """Return the concrete right variant, or ``None`` when this is left."""
+        match self:
+            case Left():
+                return None
+            case Right() as right:
+                return right
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def context(self, context: str) -> Either[T, RuntimeError]:
+        match self:
+            case Left(value):
+                return Left(value)
+            case Right(value):
+                return Right(RuntimeError(context, value))
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def swap(self) -> Either[U, T]:
+        match self:
+            case Left(value):
+                return Right(value)
+            case Right(value):
+                return Left(value)
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def or_else[V](self, otherwise: Callable[[U], V]) -> T | V:
+        if (left := self.maybe_left()) is not None:
+            return left.value
+        if (right := self.maybe_right()) is not None:
+            return otherwise(right.value)
+        raise TypeError("unknown Either variant")
+
+    def map[V](self, function: Callable[[T], V]) -> Either[V, U]:
+        match self:
+            case Left(value):
+                return Left(function(value))
+            case Right(value):
+                return Right(value)
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def flat_map[V](self, function: Callable[[T], Either[V, U]]) -> Either[V, U]:
+        match self:
+            case Left(value):
+                return function(value)
+            case Right(value):
+                return Right(value)
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def map_right[V](self, function: Callable[[U], V]) -> Either[T, V]:
+        match self:
+            case Left(value):
+                return Left(value)
+            case Right(value):
+                return Right(function(value))
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def flat_map_right[V](self, function: Callable[[U], Either[T, V]]) -> Either[T, V]:
+        match self:
+            case Left(value):
+                return Left(value)
+            case Right(value):
+                return function(value)
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def narrow(self) -> maybe_module.Maybe[T]:
+        match self:
+            case Left(value):
+                return maybe_module.Some(value)
+            case Right():
+                return maybe_module.Empty[T]()
+            case _:
+                raise TypeError("unknown Either variant")
+
+
+@dataclass(frozen=True)
+class Left[L, R = Never](Either[L, R]):
+    """The left case of :class:`Either`."""
+
+    value: L
+
+
+@dataclass(frozen=True)
+class Right[R, L = Never](Either[L, R]):
+    """The right case of :class:`Either`."""
+
+    value: R
+
+
+__all__ = ["Either", "Left", "Right"]

uogtad-0.2.0/uogtad/fallible.py

@@ -0,0 +1,95 @@
+"""The exception-capturing :class:`Fallible` container."""
+
+from typing import Callable, cast, overload
+
+from uogtad.either import Either, Left, Right
+from uogtad.maybe import Maybe
+
+
+class Fallible[F, E: Exception = Exception]:
+    """The return value or a selected exception from a computation.
+
+    By default, all ordinary exceptions are captured.  Pass an exception class
+    or tuple of exception classes to let unrelated exceptions propagate.
+    """
+
+    @overload
+    def __init__(self, computation: Callable[[], F]) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        computation: Callable[[], F],
+        exceptions: type[E] | tuple[type[E], ...],
+    ) -> None: ...
+
+    def __init__(
+        self,
+        computation: Callable[[], F],
+        exceptions: type[E] | tuple[type[E], ...] = cast(type[E], Exception),
+    ) -> None:
+        self._exceptions = exceptions
+        try:
+            self._result: Either[F, E] = Either[F, E].new(computation())
+        except exceptions as error:
+            self._result = Either[F, E].right(error)
+
+    @classmethod
+    def _from_result(
+        cls,
+        result: Either[F, E],
+        exceptions: type[E] | tuple[type[E], ...],
+    ) -> Fallible[F, E]:
+        instance = cls.__new__(cls)
+        instance._result = result
+        instance._exceptions = exceptions
+        return instance
+
+    def as_result(self) -> Either[F, E]:
+        return self._result
+
+    def is_success(self) -> bool:
+        return self._result.is_left()
+
+    def is_exception(self) -> bool:
+        return self._result.is_right()
+
+    def maybe_success(self) -> Left[F, E] | None:
+        """Return the concrete successful result, or ``None`` on failure."""
+        return self._result.maybe_left()
+
+    def maybe_exception(self) -> Right[E, F] | None:
+        """Return the concrete failed result, or ``None`` on success."""
+        return self._result.maybe_right()
+
+    def map[V](self, function: Callable[[F], V]) -> Fallible[V, E]:
+        match self._result:
+            case Left(value):
+                return Fallible[V, E](lambda: function(value), self._exceptions)
+            case Right(error):
+                return Fallible[V, E]._from_result(Right(error), self._exceptions)
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def flat_map[V](
+        self, function: Callable[[F], Fallible[V, E]]
+    ) -> Fallible[V, E]:
+        match self._result:
+            case Left(value):
+                try:
+                    return function(value)
+                except self._exceptions as error:
+                    return Fallible[V, E]._from_result(Right(error), self._exceptions)
+            case Right(error):
+                return Fallible[V, E]._from_result(Right(error), self._exceptions)
+            case _:
+                raise TypeError("unknown Either variant")
+
+    def narrow(self) -> Maybe[F]:
+        return self._result.narrow()
+
+    def or_else[V](self, recovery: Callable[[E], V]) -> F | V:
+        return self._result.or_else(recovery)
+
+
+__all__ = ["Fallible"]

uogtad-0.2.0/uogtad/maybe.py

@@ -0,0 +1,126 @@
+"""The optional-value :class:`Maybe` container."""
+
+from dataclasses import dataclass
+from typing import Callable, Never
+
+from uogtad.either import Either, Left, Right
+
+
+class Maybe[T]:
+    """A value represented by either :class:`Some` or :class:`Empty`.
+
+    ``Maybe(value)`` creates ``Some(value)``. Unlike the previous implementation,
+    ``None`` is a valid present value.
+    """
+
+    def __new__(cls, value: T) -> Maybe[T]:
+        return Some(value)
+
+    @classmethod
+    def new(cls, value: T) -> Maybe[T]:
+        """Create a present value, including when ``value`` is falsy."""
+        return Some(value)
+
+    @classmethod
+    def empty(cls) -> Maybe[T]:
+        return Empty[T]()
+
+    @classmethod
+    def of_optional(cls, value: T | None) -> Maybe[T]:
+        """Create ``Empty`` from ``None`` and ``Some`` from any other value."""
+        match value:
+            case None:
+                return Empty[T]()
+            case _:
+                return Some(value)
+
+    def is_present(self) -> bool:
+        match self:
+            case Some():
+                return True
+            case Empty():
+                return False
+            case _:
+                raise TypeError("unknown Maybe variant")
+
+    def maybe_some(self) -> Some[T] | None:
+        """Return the concrete present variant, or ``None`` when empty."""
+        match self:
+            case Some() as some:
+                return some
+            case Empty():
+                return None
+            case _:
+                raise TypeError("unknown Maybe variant")
+
+    def context(self, context: str) -> Either[T, RuntimeError]:
+        match self:
+            case Some(value):
+                return Either[T, RuntimeError].new(value)
+            case Empty():
+                return Either[T, RuntimeError].right(RuntimeError(context))
+            case _:
+                raise TypeError("unknown Maybe variant")
+
+    def or_else[V](self, instead: V) -> T | V:
+        if (some := self.maybe_some()) is not None:
+            return some.value
+        return instead
+
+    def or_else_get[V](self, instead_provider: Callable[[], V]) -> T | V:
+        if (some := self.maybe_some()) is not None:
+            return some.value
+        return instead_provider()
+
+    def filter(self, clause: Callable[[T], bool]) -> Maybe[T]:
+        match self:
+            case Some(value) if clause(value):
+                return Some(value)
+            case Some() | Empty():
+                return Empty[T]()
+            case _:
+                raise TypeError("unknown Maybe variant")
+
+    def map[V](self, function: Callable[[T], V]) -> Maybe[V]:
+        match self:
+            case Some(value):
+                return Some(function(value))
+            case Empty():
+                return Empty[V]()
+            case _:
+                raise TypeError("unknown Maybe variant")
+
+    def narrow(self) -> T | None:
+        if (some := self.maybe_some()) is not None:
+            return some.value
+        return None
+
+    def flat_map[V](self, function: Callable[[T], Maybe[V]]) -> Maybe[V]:
+        match self:
+            case Some(value):
+                return function(value)
+            case Empty():
+                return Empty[V]()
+            case _:
+                raise TypeError("unknown Maybe variant")
+
+
+@dataclass(frozen=True)
+class Some[L](Maybe[L]):
+    """The present case of :class:`Maybe`."""
+
+    value: L
+
+    def __new__(cls, value: L) -> Some[L]:
+        return object.__new__(cls)
+
+
+@dataclass(frozen=True)
+class Empty[T = Never](Maybe[T]):
+    """The absent case of :class:`Maybe`."""
+
+    def __new__(cls) -> Empty[T]:
+        return object.__new__(cls)
+
+
+__all__ = ["Maybe", "Some", "Empty"]

uogtad-0.2.0/uogtad/py.typed

@@ -0,0 +1 @@
+

uogtad-0.2.0/uogtad/test_properties.py

@@ -0,0 +1,164 @@
+"""Property-based tests for the public container laws and invariants."""
+
+from collections.abc import Callable
+
+from hypothesis import given
+from hypothesis import strategies as st
+
+from uogtad import Either, Empty, Fallible, Left, Maybe, Right, Some
+
+
+values = st.one_of(
+    st.none(),
+    st.booleans(),
+    st.integers(),
+    st.text(),
+    st.lists(st.integers()),
+)
+
+
+@given(values)
+def test_either_left_has_exactly_one_variant(value: object) -> None:
+    result: Either[object, object] = Either.new(value)
+
+    assert result.is_left()
+    assert not result.is_right()
+    assert result.maybe_left() == Left(value)
+    assert result.maybe_right() is None
+    assert result.narrow() == Some(value)
+
+
+@given(values)
+def test_either_right_has_exactly_one_variant(value: object) -> None:
+    result: Either[object, object] = Either.right(value)
+
+    assert not result.is_left()
+    assert result.is_right()
+    assert result.maybe_left() is None
+    assert result.maybe_right() == Right(value)
+    assert result.narrow() == Empty()
+
+
+@given(values, st.booleans())
+def test_either_swap_is_an_involution(value: object, is_left: bool) -> None:
+    result: Either[object, object]
+    if is_left:
+        result = Either.new(value)
+    else:
+        result = Either.right(value)
+
+    assert result.swap().swap() == result
+
+
+@given(st.integers(), st.integers(), st.integers())
+def test_either_map_obeys_identity_and_composition(value: int, addend: int, factor: int) -> None:
+    result: Either[int, str] = Either.new(value)
+
+    def add(item: int) -> int:
+        return item + addend
+
+    def multiply(item: int) -> int:
+        return item * factor
+
+    assert result.map(lambda item: item) == result
+    assert result.map(add).map(multiply) == result.map(lambda item: multiply(add(item)))
+
+
+@given(st.text(), st.text())
+def test_either_right_short_circuits_left_operations(value: str, fallback: str) -> None:
+    result: Either[int, str] = Either.right(value)
+    called = False
+
+    def left_callback(_: int) -> int:
+        nonlocal called
+        called = True
+        return 0
+
+    assert result.map(left_callback) == Right(value)
+    assert result.flat_map(lambda item: Either.new(left_callback(item))) == Right(value)
+    assert result.or_else(lambda _: fallback) == fallback
+    assert not called
+
+
+@given(values)
+def test_maybe_new_always_creates_some(value: object) -> None:
+    result = Maybe.new(value)
+
+    assert result == Some(value)
+    assert result.is_present()
+    assert result.maybe_some() == Some(value)
+    assert result.narrow() == value
+
+
+@given(values)
+def test_maybe_of_optional_matches_none_semantics(value: object) -> None:
+    result = Maybe.of_optional(value)
+
+    if value is None:
+        assert result == Empty()
+    else:
+        assert result == Some(value)
+
+
+@given(st.integers(), st.integers(), st.integers())
+def test_maybe_map_obeys_identity_and_composition(value: int, addend: int, factor: int) -> None:
+    result = Maybe.new(value)
+
+    def add(item: int) -> int:
+        return item + addend
+
+    def multiply(item: int) -> int:
+        return item * factor
+
+    assert result.map(lambda item: item) == result
+    assert result.map(add).map(multiply) == result.map(lambda item: multiply(add(item)))
+
+
+@given(st.integers(), st.integers())
+def test_maybe_filter_matches_predicate(value: int, divisor: int) -> None:
+    predicate: Callable[[int], bool] = lambda item: item >= divisor
+    expected: Maybe[int] = Some(value) if predicate(value) else Empty()
+
+    assert Maybe.new(value).filter(predicate) == expected
+
+
+@given(values, values)
+def test_maybe_fallbacks_are_lazy_for_present_values(value: object, fallback: object) -> None:
+    called = False
+
+    def fallback_provider() -> object:
+        nonlocal called
+        called = True
+        return fallback
+
+    assert Maybe.new(value).or_else(fallback) == value
+    assert Maybe.new(value).or_else_get(fallback_provider) == value
+    assert not called
+
+
+@given(st.integers())
+def test_fallible_success_round_trips_and_maps(value: int) -> None:
+    result = Fallible(lambda: value)
+
+    assert result.is_success()
+    assert not result.is_exception()
+    assert result.as_result() == Left(value)
+    assert result.narrow() == Some(value)
+    assert result.map(lambda item: item + 1).as_result() == Left(value + 1)
+
+
+@given(st.text(), st.text())
+def test_fallible_failure_preserves_exception_and_recovers(message: str, recovery: str) -> None:
+    error = ValueError(message)
+
+    def fail() -> int:
+        raise error
+
+    result = Fallible(fail)
+
+    assert not result.is_success()
+    assert result.is_exception()
+    assert result.maybe_success() is None
+    assert result.maybe_exception() == Right(error)
+    assert result.map(lambda item: item + 1).as_result() == Right(error)
+    assert result.or_else(lambda caught: (caught, recovery)) == (error, recovery)

uogtad-0.2.0/uogtad/test_uogtad.py

@@ -0,0 +1,145 @@
+from typing import Literal, Never, assert_type
+
+import pytest
+
+from uogtad import Either, Empty, Fallible, Left, Maybe, Right, Some
+
+
+@pytest.mark.parametrize("value", [0, "", [], False, None])
+def test_either_preserves_falsy_left_values(value: object) -> None:
+    result: Either[object, Never] = Either.new(value)
+    assert result.map(lambda item: (item, "mapped")) == Left((value, "mapped"))
+    assert result.narrow() == Some(value)
+
+
+def test_either_cases_support_equality_repr_and_matching() -> None:
+    assert Either.new(1) == Either.new(1)
+    assert repr(Either.right("error")) == "Right(value='error')"
+    match Either.new(None):
+        case Left(value):
+            assert value is None
+        case Right():  # pragma: no cover - protects exhaustiveness at runtime
+            pytest.fail("unexpected right")
+
+
+def test_either_operations() -> None:
+    result: Either[int, str] = Either.new(1)
+    assert result.map(lambda value: value + 1) == Left(2)
+    assert result.flat_map(lambda value: Either.new(value + 2)) == Left(3)
+    assert Either.right("bad").map_right(str.upper) == Right("BAD")
+    assert Either.right("bad").swap() == Left("bad")
+    assert Either.right("bad").context("failed").is_right()
+
+
+def test_either_variant_guards_narrow_to_concrete_cases() -> None:
+    result: Either[int, str] = Either.new(1)
+    if left := result.maybe_left():
+        assert left.value + 1 == 2
+    else:  # pragma: no cover - protects type narrowing at runtime
+        pytest.fail("expected left")
+
+    assert result.maybe_right() is None
+
+
+@pytest.mark.parametrize("value", [0, "", [], False, None])
+def test_maybe_preserves_present_falsy_values(value: object) -> None:
+    maybe = Maybe(value)
+    assert maybe.is_present()
+    assert maybe.or_else("fallback") == value
+    assert maybe.or_else_get(lambda: "fallback") == value
+    assert maybe.filter(lambda _: True) == Some(value)
+    assert maybe.map(lambda item: (item, "mapped")) == Some((value, "mapped"))
+
+
+def test_empty_maybe() -> None:
+    empty: Maybe[int] = Maybe.empty()
+    assert empty == Empty()
+    assert empty.or_else(99) == 99
+    assert empty.flat_map(lambda value: Some(value + 1)) == Empty()
+    assert empty.maybe_some() is None
+
+
+@pytest.mark.parametrize("value", [0, "", [], False])
+def test_maybe_of_optional_preserves_non_none_values(value: object) -> None:
+    assert Maybe.of_optional(value) == Some(value)
+
+
+def test_maybe_of_optional_converts_none_to_empty() -> None:
+    assert Maybe.of_optional(None) == Empty()
+
+
+def test_maybe_guard_narrows_to_some() -> None:
+    if some := Maybe(0).maybe_some():
+        assert some.value == 0
+    else:  # pragma: no cover - protects type narrowing at runtime
+        pytest.fail("expected some")
+
+
+@pytest.mark.parametrize("value", [0, "", [], False, None])
+def test_fallible_preserves_falsy_successes(value: object) -> None:
+    result = Fallible(lambda: value)
+    assert result.is_success()
+    assert result.as_result() == Left(value)
+    assert result.or_else(lambda _: "fallback") == value
+
+
+def test_fallible_defaults_to_capturing_exception() -> None:
+    result = Fallible(lambda: 1)
+    assert_type(result, Fallible[int, Exception])
+    assert_type(result.maybe_exception(), Right[Exception, int] | None)
+
+
+def test_fallible_map_and_flat_map_capture_callback_errors() -> None:
+    mapped = Fallible(lambda: 1).map(lambda _: 1 / 0)
+    assert mapped.is_exception()
+    mapped_result = mapped.as_result()
+    assert isinstance(mapped_result, Right)
+    assert isinstance(mapped_result.value, ZeroDivisionError)
+
+    def fail(_: int) -> Fallible[str]:
+        raise ValueError("bad callback")
+
+    flat_mapped_result = Fallible(lambda: 1).flat_map(fail).as_result()
+    assert isinstance(flat_mapped_result, Right)
+    assert isinstance(flat_mapped_result.value, ValueError)
+
+    assert mapped.maybe_success() is None
+    assert isinstance(mapped.maybe_exception(), Right)
+
+
+def test_fallible_does_not_swallow_base_exceptions() -> None:
+    def interrupt() -> Never:
+        raise KeyboardInterrupt
+
+    with pytest.raises(KeyboardInterrupt):
+        Fallible(interrupt)
+
+
+def test_fallible_only_captures_selected_exceptions() -> None:
+    captured = Fallible(lambda: int("not a number"), ValueError)
+    failed = captured.maybe_exception()
+    assert isinstance(failed, Right)
+    assert isinstance(failed.value, ValueError)
+
+    with pytest.raises(TypeError):
+        Fallible(lambda: len(None), ValueError)  # type: ignore[arg-type]
+
+
+def test_fallible_accepts_and_preserves_a_tuple_of_exception_types() -> None:
+    selected = (ValueError, RuntimeError)
+    result = Fallible(lambda: 1, selected).map(
+        lambda _: (_ for _ in ()).throw(RuntimeError("mapped failure"))
+    )
+
+    failed = result.maybe_exception()
+    assert isinstance(failed, Right)
+    assert isinstance(failed.value, RuntimeError)
+
+
+def test_typed_readme_flow() -> None:
+    def categorise(number: int) -> Either[Literal["A"], Literal["B"]]:
+        if number == 0:
+            return Either.new("A")
+        return Either.right("B")
+
+    assert [item.is_left() for item in map(categorise, [0, 1, 0])] == [True, False, True]

uogtad-0.2.0/uogtad.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: uogtad
+Version: 0.2.0
+Summary: Typed functional control containers for Python
+Author: uogtad contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/blakehawkins/uogtad
+Project-URL: Issues, https://github.com/blakehawkins/uogtad/issues
+Project-URL: Repository, https://github.com/blakehawkins/uogtad.git
+Keywords: either,functional-programming,maybe,result,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.15
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: hypothesis>=6; extra == "test"
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.19; extra == "typecheck"
+Requires-Dist: pyright>=1.1.408; extra == "typecheck"
+Dynamic: license-file
+
+# uoɥʇʎd
+
+[![CI](https://github.com/blakehawkins/uogtad/actions/workflows/ci.yml/badge.svg)](https://github.com/blakehawkins/uogtad/actions/workflows/ci.yml)
+[![Python 3.15](https://img.shields.io/badge/python-3.15-blue.svg)](https://docs.python.org/3.15/)
+[![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
+[![Pyright](https://img.shields.io/badge/pyright-checked-blue.svg)](https://github.com/microsoft/pyright)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/license/mit)
+
+A functional control library for python in the same vein as io.vavr.control for java.
+
+Provides three immutable, typed control containers:
+
+```python
+Either.new(value)       # Left(value)
+Either.right(error)     # Right(error)
+Maybe.new(value)        # Some(value), even when value is None
+Maybe.empty()           # Empty()
+Maybe.of_optional(value) # Empty() for None, otherwise Some(value)
+Fallible(computation)   # captures Exception, but not KeyboardInterrupt/SystemExit
+Fallible(computation, ValueError)  # captures only ValueError (and subclasses)
+```
+
+Example usage:
+
+```python
+from typing import Literal
+
+from uogtad import Either, Fallible
+
+def raises() -> str:
+    raise RuntimeError("tada")
+
+tada = Fallible(raises).as_result().swap().map(lambda exc: str(exc.args[0])).narrow().narrow()
+assert tada == "tada"
+
+# Unexpected exceptions remain bugs instead of becoming values. A tuple works
+# just like an ``except`` clause when several exception types are expected.
+parsed = Fallible(lambda: int("not a number"), (ValueError, RuntimeError))
+if failure := parsed.maybe_exception():
+    # ``failure.value`` is statically narrowed to ValueError | RuntimeError.
+    assert isinstance(failure.value, ValueError)
+
+def categorise(num: int) -> Either[Literal['A'], Literal['B']]:
+    if num == 0:
+        return Either.new('A')  # Either is left-biased, like Result[T, E].
+    return Either.right('B')
+
+results = list(map(categorise, [0, 1, 0, 2, 0, 3]))
+assert [result.is_left() for result in results] == [True, False, True, False, True, False]
+
+result = categorise(0)
+if left := result.maybe_left():
+    # Static checkers narrow `left` to Left[Literal['A']].
+    assert left.value == "A"
+
+```
+
+
+# Ops
+
+Install the latest release from PyPI (Python 3.15 or newer):
+
+```shell
+python -m pip install uogtad
+```
+
+Install the current `master` branch directly from GitHub (Python 3.15 or newer)
+with pip:
+
+```shell
+python -m pip install "uogtad @ git+https://github.com/blakehawkins/uogtad.git@master"
+```
+
+Or add the same PyPI-compatible Git dependency to a Pixi project:
+
+```shell
+pixi add --pypi "uogtad @ git+https://github.com/blakehawkins/uogtad.git@master"
+```
+
+Run the test suite:
+
+```shell
+pixi run python -m pytest
+```
+
+Build and validate the PyPI distributions:
+
+```shell
+pixi run package
+```
+
+### Releases
+
+Releases use [Release Please](https://github.com/googleapis/release-please#readme)
+and [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so no
+GitHub repository secrets are required.
+
+## Comparison with other libraries
+
+[`returns`](https://returns.readthedocs.io/) is a broad collection of typed
+functional abstractions, including IO-aware and asynchronous containers. Its
+decorators, point-free helpers, and `flow` utilities encourage building
+annotated function pipelines. Choose it when an application benefits from that
+larger functional-programming ecosystem and composition style.
+
+[`Expression`](https://expression.readthedocs.io/) is inspired by F# and
+provides discriminated unions, computation expressions, immutable collections,
+and functional utilities in addition to `Option` and `Result`. Its decorators,
+free functions, and `pipe` helpers support an F#-style pipeline-oriented
+application design. Choose it when those abstractions should shape more of the
+application.
+
+`uogtad` deliberately has a smaller scope: `Either`, `Maybe`, and `Fallible`,
+with operations exposed directly as methods. It intentionally avoids
+decorator-driven control flow, free-function combinators, and a pipeline DSL.
+Choose it when ordinary method chaining, Python pattern matching, and a compact
+API are preferable.

uogtad-0.2.0/uogtad.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+uogtad/__init__.py
+uogtad/either.py
+uogtad/fallible.py
+uogtad/maybe.py
+uogtad/py.typed
+uogtad/test_properties.py
+uogtad/test_uogtad.py
+uogtad.egg-info/PKG-INFO
+uogtad.egg-info/SOURCES.txt
+uogtad.egg-info/dependency_links.txt
+uogtad.egg-info/requires.txt
+uogtad.egg-info/top_level.txt

uogtad-0.2.0/uogtad.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

uogtad-0.2.0/uogtad.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[test]
+hypothesis>=6
+pytest>=7
+
+[typecheck]
+mypy>=1.19
+pyright>=1.1.408

uogtad-0.2.0/uogtad.egg-info/top_level.txt

@@ -0,0 +1 @@
+uogtad