stdlibx-option 0.1.0__tar.gz

stdlibx_option-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucino772
+
+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.

stdlibx_option-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: stdlibx-option
+Version: 0.1.0
+Summary: stdlibx-option
+Author: Lucino772
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.10.0,<5
+Requires-Python: >=3.9
+Project-URL: Documentation, http://stdlibx.lucapalmi.com/
+Project-URL: Repository, https://github.com/Lucino772/stdlibx
+Description-Content-Type: text/markdown
+
+[![docs](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml/badge.svg?branch=main)](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml)
+
+# stdlibx
+**stdlibx** is a collection of small, focused Python utilities that simplify common programming patterns and help you write clearer, more composable code.
+
+It provides practical tools for handling optional values, explicit error management, cancellation, composition, configuration, pattern matching, and reactive flows.
+
+## Documentation
+Checkout the [documentation](http://stdlibx.lucapalmi.com/)
+
+## Licence
+This project uses a **MIT** Licence [view](https://github.com/Lucino772/stdlibx/blob/main/LICENSE)

stdlibx_option-0.1.0/README.md

@@ -0,0 +1,12 @@
+[![docs](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml/badge.svg?branch=main)](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml)
+
+# stdlibx
+**stdlibx** is a collection of small, focused Python utilities that simplify common programming patterns and help you write clearer, more composable code.
+
+It provides practical tools for handling optional values, explicit error management, cancellation, composition, configuration, pattern matching, and reactive flows.
+
+## Documentation
+Checkout the [documentation](http://stdlibx.lucapalmi.com/)
+
+## Licence
+This project uses a **MIT** Licence [view](https://github.com/Lucino772/stdlibx/blob/main/LICENSE)

stdlibx_option-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "stdlibx-option"
+version = "0.1.0"
+description = "stdlibx-option"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+readme = "README.md"
+authors = [
+    { name = "Lucino772" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "typing_extensions>=4.10.0,<5"
+]
+
+[project.urls]
+Documentation = "http://stdlibx.lucapalmi.com/"
+Repository = "https://github.com/Lucino772/stdlibx"
+
+[tool.uv.build-backend]
+module-name = "stdlibx.option"
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"

stdlibx_option-0.1.0/src/stdlibx/option/__init__.py

@@ -0,0 +1,23 @@
+from stdlibx.option._errors import OptionError, OptionExpectError, OptionUnwrapError
+from stdlibx.option._option import (
+    Nothing,
+    Option,
+    Some,
+    as_optional,
+    is_none,
+    is_some,
+    optional_of,
+)
+
+__all__ = [
+    "Nothing",
+    "Option",
+    "OptionError",
+    "OptionExpectError",
+    "OptionUnwrapError",
+    "Some",
+    "as_optional",
+    "is_none",
+    "is_some",
+    "optional_of",
+]

stdlibx_option-0.1.0/src/stdlibx/option/_errors.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+class OptionError(Exception): ...
+
+
+class OptionUnwrapError(OptionError): ...
+
+
+class OptionExpectError(OptionError): ...

stdlibx_option-0.1.0/src/stdlibx/option/_option.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, Callable, Generic, TypeVar
+
+from typing_extensions import ParamSpec, TypeAlias, TypeGuard
+
+if TYPE_CHECKING:
+    from stdlibx.option._types import Operation
+
+
+T = TypeVar("T")
+E = TypeVar("E")
+U = TypeVar("U")
+P = ParamSpec("P")
+
+Option: TypeAlias = "Some[T] | Nothing[T]"
+
+
+def is_some(opt: Option[T]) -> TypeGuard[Some[T]]:
+    return opt.is_some()
+
+
+def is_none(opt: Option[T]) -> TypeGuard[Nothing[T]]:
+    return opt.is_none()
+
+
+def optional_of(
+    func: Callable[P, T | None], *args: P.args, **kwargs: P.kwargs
+) -> Option[T]:
+    value = func(*args, **kwargs)
+    if value is None:
+        return Nothing()
+    return Some(value)
+
+
+def as_optional(func: Callable[P, T | None]) -> Callable[P, Option[T]]:
+    @wraps(func)
+    def _wrapped(*args: P.args, **kwargs: P.kwargs) -> Option[T]:
+        result = func(*args, **kwargs)
+        if result is None:
+            return Nothing()
+        return Some(result)
+
+    return _wrapped
+
+
+class Some(Generic[T]):
+    __match_args__ = ("value",)
+    __slots__ = ("value",)
+
+    value: T
+
+    def __init__(self, value: T) -> None:
+        self.value = value
+
+    def __repr__(self) -> str:
+        return f"Some({self.value!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Some):
+            return other.value == self.value
+        return False
+
+    def is_some(self):
+        return True
+
+    def is_none(self):
+        return False
+
+    def apply(self, operation: Operation[Option[T], U]) -> U:
+        return operation(self)
+
+
+class Nothing(Generic[T]):
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "Nothing()"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Nothing)
+
+    def is_some(self):
+        return False
+
+    def is_none(self):
+        return True
+
+    def apply(self, operation: Operation[Option[T], U]) -> U:
+        return operation(self)

stdlibx_option-0.1.0/src/stdlibx/option/_types.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Callable, TypeVar
+
+from typing_extensions import TypeAlias
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+Operation: TypeAlias = Callable[[T], U]

stdlibx_option-0.1.0/src/stdlibx/option/fn/__init__.py

@@ -0,0 +1,51 @@
+from stdlibx.option.fn.base import (
+    and_,
+    and_then,
+    expect,
+    filter_,
+    flatten,
+    inspect,
+    is_none_or,
+    is_some_and,
+    map_,
+    map_or,
+    map_or_else,
+    or_,
+    or_else,
+    unwrap,
+    unwrap_or,
+    unwrap_or_else,
+    xor,
+    zipped,
+)
+from stdlibx.option.fn.collect import collect, collect_all
+
+__all__ = [
+    "and_",
+    "and_then",
+    "collect",
+    "collect_all",
+    "expect",
+    "filter_",
+    "flatten",
+    "inspect",
+    "is_none_or",
+    "is_some_and",
+    "map_",
+    "map_or",
+    "map_or_else",
+    "or_",
+    "or_else",
+    "unwrap",
+    "unwrap_or",
+    "unwrap_or_else",
+    "xor",
+    "zipped",
+]
+
+try:
+    from stdlibx.option.fn.result import ok_or, ok_or_else, transpose
+
+    __all__ += ["ok_or", "ok_or_else", "transpose"]
+except ImportError:
+    pass

stdlibx_option-0.1.0/src/stdlibx/option/fn/base.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Callable, TypeVar
+
+from stdlibx.option import Option, methods
+from typing_extensions import TypeVarTuple, Unpack
+
+if TYPE_CHECKING:
+    from stdlibx.option._option import Operation
+
+T = TypeVar("T")
+U = TypeVar("U")
+Ts = TypeVarTuple("Ts")
+
+
+def is_some_and(func: Callable[[T], bool]) -> Operation[Option[T], bool]:
+    return partial(methods.is_some_and, func=func)
+
+
+def is_none_or(func: Callable[[T], bool]) -> Operation[Option[T], bool]:
+    return partial(methods.is_none_or, func=func)
+
+
+def expect(msg: str) -> Operation[Option[T], T]:
+    return partial(methods.expect, msg=msg)
+
+
+def unwrap() -> Operation[Option[T], T]:
+    return methods.unwrap
+
+
+def unwrap_or(default: T) -> Operation[Option[T], T]:
+    return partial(methods.unwrap_or, default=default)
+
+
+def unwrap_or_else(func: Callable[[], T]) -> Operation[Option[T], T]:
+    return partial(methods.unwrap_or_else, func=func)
+
+
+def map_(func: Callable[[T], U]) -> Operation[Option[T], Option[U]]:
+    return partial(methods.map_, func=func)
+
+
+def inspect(func: Callable[[T], None]) -> Operation[Option[T], Option[T]]:
+    return partial(methods.inspect, func=func)
+
+
+def map_or(default: U, func: Callable[[T], U]) -> Operation[Option[T], U]:
+    return partial(methods.map_or, default=default, func=func)
+
+
+def map_or_else(
+    default: Callable[[], U], func: Callable[[T], U]
+) -> Operation[Option[T], U]:
+    return partial(methods.map_or_else, default=default, func=func)
+
+
+def and_(other: Option[U]) -> Operation[Option[T], Option[U]]:
+    return partial(methods.and_, other=other)
+
+
+def and_then(func: Callable[[T], Option[U]]) -> Operation[Option[T], Option[U]]:
+    return partial(methods.and_then, func=func)
+
+
+def filter_(predicate: Callable[[T], bool]) -> Operation[Option[T], Option[T]]:
+    return partial(methods.filter_, predicate=predicate)
+
+
+def or_(default: Option[T]) -> Operation[Option[T], Option[T]]:
+    return partial(methods.or_, default=default)
+
+
+def or_else(default: Callable[[], Option[T]]) -> Operation[Option[T], Option[T]]:
+    return partial(methods.or_else, default=default)
+
+
+def xor(other: Option[T]) -> Operation[Option[T], Option[T]]:
+    return partial(methods.xor, other=other)
+
+
+def flatten() -> Operation[Option[Option[T]], Option[T]]:
+    return methods.flatten
+
+
+def zipped(
+    func: Callable[[Unpack[Ts]], Option[U]],
+) -> Operation[Option[tuple[Unpack[Ts]]], Option[tuple[Unpack[Ts], U]]]:
+    return partial(methods.zipped, func=func)

stdlibx_option-0.1.0/src/stdlibx/option/fn/collect.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import functools
+from typing import Any, Iterable, TypeVar, overload
+
+from stdlibx.option._option import Nothing, Option, Some, is_some
+
+T = TypeVar("T")
+T1 = TypeVar("T1")
+T2 = TypeVar("T2")
+T3 = TypeVar("T3")
+T4 = TypeVar("T4")
+T5 = TypeVar("T5")
+T6 = TypeVar("T6")
+T7 = TypeVar("T7")
+T8 = TypeVar("T8")
+T9 = TypeVar("T9")
+
+
+@overload
+def collect(a: Option[T1], b: Option[T2], /) -> Option[tuple[T1, T2]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1], b: Option[T2], c: Option[T3], /
+) -> Option[tuple[T1, T2, T3]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1], b: Option[T2], c: Option[T3], d: Option[T4], /
+) -> Option[tuple[T1, T2, T3, T4]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1], b: Option[T2], c: Option[T3], d: Option[T4], e: Option[T5], /
+) -> Option[tuple[T1, T2, T3, T4, T5]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1],
+    b: Option[T2],
+    c: Option[T3],
+    d: Option[T4],
+    e: Option[T5],
+    f: Option[T6],
+    /,
+) -> Option[tuple[T1, T2, T3, T4, T5, T6]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1],
+    b: Option[T2],
+    c: Option[T3],
+    d: Option[T4],
+    e: Option[T5],
+    f: Option[T6],
+    g: Option[T7],
+    /,
+) -> Option[tuple[T1, T2, T3, T4, T5, T6, T7]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1],
+    b: Option[T2],
+    c: Option[T3],
+    d: Option[T4],
+    e: Option[T5],
+    f: Option[T6],
+    g: Option[T7],
+    h: Option[T8],
+    /,
+) -> Option[tuple[T1, T2, T3, T4, T5, T6, T7, T8]]: ...
+
+
+@overload
+def collect(
+    a: Option[T1],
+    b: Option[T2],
+    c: Option[T3],
+    d: Option[T4],
+    e: Option[T5],
+    f: Option[T6],
+    g: Option[T7],
+    h: Option[T8],
+    i: Option[T9],
+    /,
+) -> Option[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9]]: ...
+
+
+def collect(initial: Option[Any], *others: Option[Any]) -> Option[tuple[Any, ...]]:
+    def _combine(a: Option[tuple[Any, ...]], b: Option[Any]) -> Option[tuple[Any, ...]]:
+        if is_some(a) and is_some(b):
+            return Some(((*a.value, b.value)))
+        return Nothing()
+
+    return functools.reduce(_combine, [initial, *others], Some(()))
+
+
+def collect_all(iterable: Iterable[Option[T]]) -> Option[tuple[T, ...]]:
+    def _combine(a: Option[tuple[T, ...]], b: Option[T]) -> Option[tuple[T, ...]]:
+        if is_some(a) and is_some(b):
+            return Some(((*a.value, b.value)))
+        return Nothing()
+
+    return functools.reduce(_combine, iterable, Some(()))

stdlibx_option-0.1.0/src/stdlibx/option/fn/result.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Callable, TypeVar
+
+from stdlibx.option import Option, methods
+
+if TYPE_CHECKING:
+    from stdlibx.option._option import Operation
+    from stdlibx.result import Result
+
+T = TypeVar("T")
+U = TypeVar("U")
+E = TypeVar("E")
+
+
+def ok_or(error: E) -> Operation[Option[T], Result[T, E]]:
+    return partial(methods.ok_or, error=error)
+
+
+def ok_or_else(error: Callable[[], E]) -> Operation[Option[T], Result[T, E]]:
+    return partial(methods.ok_or_else, error=error)
+
+
+def transpose() -> Operation[Option[Result[U, E]], Result[Option[U], E]]:
+    return methods.transpose

stdlibx_option-0.1.0/src/stdlibx/option/methods/__init__.py

@@ -0,0 +1,48 @@
+from stdlibx.option.methods.base import (
+    and_,
+    and_then,
+    expect,
+    filter_,
+    flatten,
+    inspect,
+    is_none_or,
+    is_some_and,
+    map_,
+    map_or,
+    map_or_else,
+    or_,
+    or_else,
+    unwrap,
+    unwrap_or,
+    unwrap_or_else,
+    xor,
+    zipped,
+)
+
+__all__ = [
+    "and_",
+    "and_then",
+    "expect",
+    "filter_",
+    "flatten",
+    "inspect",
+    "is_none_or",
+    "is_some_and",
+    "map_",
+    "map_or",
+    "map_or_else",
+    "or_",
+    "or_else",
+    "unwrap",
+    "unwrap_or",
+    "unwrap_or_else",
+    "xor",
+    "zipped",
+]
+
+try:
+    from stdlibx.option.methods.result import ok_or, ok_or_else, transpose
+
+    __all__ += ["ok_or", "ok_or_else", "transpose"]
+except ImportError:
+    pass

stdlibx_option-0.1.0/src/stdlibx/option/methods/base.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from typing import Callable, TypeVar
+
+from stdlibx.option import (
+    Nothing,
+    Option,
+    OptionExpectError,
+    OptionUnwrapError,
+    Some,
+    is_none,
+    is_some,
+)
+from typing_extensions import TypeVarTuple, Unpack
+
+T = TypeVar("T")
+U = TypeVar("U")
+Ts = TypeVarTuple("Ts")
+
+
+def is_some_and(opt: Option[T], func: Callable[[T], bool]) -> bool:
+    return is_some(opt) and func(opt.value)
+
+
+def is_none_or(opt: Option[T], func: Callable[[T], bool]) -> bool:
+    return is_none(opt) or (is_some(opt) and func(opt.value))
+
+
+def expect(opt: Option[T], msg: str) -> T:
+    if is_some(opt):
+        return opt.value
+    raise OptionExpectError(msg)
+
+
+def unwrap(opt: Option[T]) -> T:
+    if is_some(opt):
+        return opt.value
+    raise OptionUnwrapError
+
+
+def unwrap_or(opt: Option[T], default: T) -> T:
+    if is_some(opt):
+        return opt.value
+    return default
+
+
+def unwrap_or_else(opt: Option[T], func: Callable[[], T]) -> T:
+    if is_some(opt):
+        return opt.value
+    return func()
+
+
+def map_(opt: Option[T], func: Callable[[T], U]) -> Option[U]:
+    if is_some(opt):
+        return Some(func(opt.value))
+    return Nothing()
+
+
+def inspect(opt: Option[T], func: Callable[[T], None]) -> Option[T]:
+    if is_some(opt):
+        func(opt.value)
+    return opt
+
+
+def map_or(opt: Option[T], default: U, func: Callable[[T], U]) -> U:
+    if is_some(opt):
+        return func(opt.value)
+    return default
+
+
+def map_or_else(opt: Option[T], default: Callable[[], U], func: Callable[[T], U]) -> U:
+    if is_some(opt):
+        return func(opt.value)
+    return default()
+
+
+def and_(opt: Option[T], other: Option[U]) -> Option[U]:
+    if is_some(opt):
+        return other
+    return Nothing()
+
+
+def and_then(opt: Option[T], func: Callable[[T], Option[U]]) -> Option[U]:
+    if is_some(opt):
+        return func(opt.value)
+    return Nothing()
+
+
+def filter_(opt: Option[T], predicate: Callable[[T], bool]) -> Option[T]:
+    if is_some(opt) and predicate(opt.value) is True:
+        return Some(opt.value)
+    return Nothing()
+
+
+def or_(opt: Option[T], default: Option[T]) -> Option[T]:
+    if is_some(opt):
+        return Some(opt.value)
+    return default
+
+
+def or_else(opt: Option[T], default: Callable[[], Option[T]]) -> Option[T]:
+    if is_some(opt):
+        return Some(opt.value)
+    return default()
+
+
+def xor(opt: Option[T], other: Option[T]) -> Option[T]:
+    if is_some(opt) and is_none(other):
+        return Some(opt.value)
+    elif is_some(other) and is_none(opt):
+        return Some(other.value)
+    else:
+        return Nothing()
+
+
+def flatten(opt: Option[Option[T]]) -> Option[T]:
+    if is_some(opt):
+        return opt.value
+    return Nothing()
+
+
+def zipped(
+    opt: Option[tuple[Unpack[Ts]]], func: Callable[[Unpack[Ts]], Option[U]]
+) -> Option[tuple[Unpack[Ts], U]]:
+    if is_some(opt):
+        return map_(func(*opt.value), lambda val: (*opt.value, val))
+    return Nothing()

stdlibx_option-0.1.0/src/stdlibx/option/methods/result.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Callable, TypeVar
+
+from stdlibx.option import Nothing, Option, Some, is_some
+from stdlibx.result import Error, Ok, Result, is_err, is_ok
+
+T = TypeVar("T")
+U = TypeVar("U")
+E = TypeVar("E")
+
+
+def ok_or(opt: Option[T], error: E) -> Result[T, E]:
+    if is_some(opt):
+        return Ok(opt.value)
+    return Error(error)
+
+
+def ok_or_else(opt: Option[T], error: Callable[[], E]) -> Result[T, E]:
+    if is_some(opt):
+        return Ok(opt.value)
+    return Error(error())
+
+
+def transpose(opt: Option[Result[U, E]]) -> Result[Option[U], E]:
+    if is_some(opt) and is_ok(opt.value):
+        return Ok(Some(opt.value.value))
+    elif is_some(opt) and is_err(opt.value):
+        return Error(opt.value.error)
+    else:
+        return Ok(Nothing())