optionz 0.1.0__py3-none-any.whl

opt.py

@@ -0,0 +1,582 @@
+import builtins
+from typing import Any, Callable, Iterable, Optional, overload
+
+# Raised when trying to unwrap a None value. It is an alias for ValueError to allow
+# mocking it in tests (or global mokey-patching if you are feelling adventurous).
+UnwrapError = ValueError
+
+__all__ = (
+    "UnwrapError",
+    "unwrap",
+    "unwrap_or",
+    "unwrap_or_else",
+    "expect",
+    "map",
+    "coalesce",
+    "values",
+    "together",
+    "zip",
+    "elements",
+    "getattr",
+    "call",
+    "iter",
+)
+
+
+def _any(x: object) -> Any:
+    return x
+
+
+#
+# Unwrappers
+#
+def unwrap[T](value: Optional[T], /) -> T:
+    """
+    Unwrap a value that may be None. If the value is None, raise a ValueError.
+
+    Args:
+        value: The optional value to unwrap.
+
+    Examples:
+        >>> opt.unwrap(42)
+        42
+        >>> opt.unwrap(None)
+        Traceback (most recent call last):
+        ...
+        ValueError: Value is None
+
+    See also:
+        - :func:`opt.expect`
+        - :func:`opt.unwrap_or`
+        - :func:`opt.unwrap_or_else`
+    """
+    if value is None:
+        raise UnwrapError("Value is None")
+    return value
+
+
+def unwrap_or[T](value: Optional[T], /, default: T) -> T:
+    """
+    Unwrap a value that may be None. If the value is None, return the default
+    value.
+
+    Args:
+        value: The optional value to unwrap.
+        default: The value to return if the optional value is None.
+
+    Examples:
+        >>> opt.unwrap_or(0, 42)
+        0
+        >>> opt.unwrap_or(None, 42)
+        42
+
+    See also:
+        - :func:`opt.unwrap`
+        - :func:`opt.unwrap_or_else`
+    """
+    return value if value is not None else default
+
+
+def unwrap_or_else[T](value: Optional[T], /, default_fn: Callable[[], T]) -> T:
+    """
+    Unwrap a value that may be None. If the value is None, return the result of
+    calling the default function.
+
+    This may be used instead of :func:`opt.unwrap_or` when the default value is
+    expensive to compute or produces side effects.
+
+    Args:
+        value: The optional value to unwrap.
+        default_fn: The function to call if the optional value is None.
+
+    Examples:
+        >>> opt.unwrap_or_else(0, lambda: 42)
+        0
+        >>> opt.unwrap_or_else(None, lambda: 42)
+        42
+
+    See also:
+        - :func:`opt.unwrap`
+        - :func:`opt.unwrap_or`
+    """
+    return value if value is not None else default_fn()
+
+
+def expect[T](value: Optional[T], /, message: str) -> T:
+    """
+    Unwrap a value that may be None. If the value is None, raise a ValueError
+    with the given message.
+
+    Args:
+        value: The optional value to unwrap.
+        message: The message to include in the ValueError if the value is None.
+
+    Examples:
+        >>> opt.expect(42, "Value is None")
+        42
+        >>> opt.expect(None, "Value is None")
+        Traceback (most recent call last):
+        ...
+        ValueError: Value is None
+
+    See also:
+        - :func:`opt.unwrap`
+    """
+    if value is None:
+        raise UnwrapError(message)
+    return value
+
+
+@overload
+def map[T, R](fn: Callable[[T], R], value: Optional[T], /) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, R](
+    fn: Callable[[T1, T2], R], value: Optional[T1], value2: Optional[T2], /
+) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, T3, R](
+    fn: Callable[[T1, T2, T3], R],
+    value: Optional[T1],
+    value2: Optional[T2],
+    value3: Optional[T3],
+    /,
+) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, R](
+    fn: Callable[[T1, T2, T3, T4], R],
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    /,
+) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, R](
+    fn: Callable[[T1, T2, T3, T4, T5], R],
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    /,
+) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, T6, R](
+    fn: Callable[[T1, T2, T3, T4, T5, T6], R],
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    /,
+) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, T6, T7, R](
+    fn: Callable[[T1, T2, T3, T4, T5, T6, T7], R],
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    x7: Optional[T7],
+    /,
+) -> Optional[R]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, T6, T7, T8, R](
+    fn: Callable[[T1, T2, T3, T4, T5, T6, T7, T8], R],
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    x7: Optional[T7],
+    x8: Optional[T8],
+    /,
+) -> Optional[R]: ...
+
+
+def map(fn: Any, *values: Any) -> Any:
+    """
+    Apply the function to the values if none of them are None, otherwise return None.
+
+
+    Args:
+        fn:
+            The function to apply to the values if none of them are None.
+        x1, x2, ...:
+            The optional values to apply the function to.
+            It accepts any number of arguments (but only type checks up to 8).
+
+    Examples:
+        >>> opt.map(lambda x: x + 1, 41)
+        42
+        >>> opt.map(lambda x, y: x + y, 40, 2)
+        42
+        >>> opt.map(lambda x, y: x + y, 42, None)
+        None
+    """
+    if any(value is None for value in values):
+        return None
+    return fn(*values)
+
+
+@overload
+def coalesce[T](values: Iterable[Optional[T]], /) -> Optional[T]: ...
+
+
+@overload
+def coalesce[T](x: Optional[T], /, *rest: Optional[T]) -> Optional[T]: ...
+
+
+def coalesce(*values: Any) -> Any:
+    """
+    Return the first value that is not None, or None if all values are None.
+
+    Examples:
+        >>> opt.coalesce(None, None, 42, 43, ...)
+        42
+        >>> opt.coalesce(None, None)
+        None
+        >>> opt.coalesce([None, None, 42, 43, ...])
+        42
+    """
+    if len(values) == 1:
+        values = values[0]
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def values[T](seq: Iterable[Optional[T]], /) -> Iterable[T]:
+    """
+    Return an iterable of the non-None values in the given sequence.
+
+    Args:
+        seq: The sequence of options to filter.
+
+    Examples:
+        >>> list(opt.values([1, None, 2, None, 3]))
+        [1, 2, 3]
+        >>> list(opt.values([None, None]))
+        []
+    """
+    return (value for value in seq if value is not None)
+
+
+@overload
+def together[T1, T2](
+    x1: Optional[T1], x2: Optional[T2], /
+) -> tuple[Optional[T1], Optional[T2]]: ...
+
+
+@overload
+def together[T1, T2, T3](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    /,
+) -> tuple[Optional[T1], Optional[T2], Optional[T3]]: ...
+
+
+@overload
+def together[T1, T2, T3, T4](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    /,
+) -> tuple[Optional[T1], Optional[T2], Optional[T3], Optional[T4]]: ...
+
+
+@overload
+def together[T1, T2, T3, T4, T5](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    /,
+) -> tuple[Optional[T1], Optional[T2], Optional[T3], Optional[T4], Optional[T5]]: ...
+
+
+@overload
+def together[T1, T2, T3, T4, T5, T6](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    /,
+) -> tuple[
+    Optional[T1], Optional[T2], Optional[T3], Optional[T4], Optional[T5], Optional[T6]
+]: ...
+
+
+@overload
+def together[T1, T2, T3, T4, T5, T6, T7](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    x7: Optional[T7],
+    /,
+) -> tuple[
+    Optional[T1],
+    Optional[T2],
+    Optional[T3],
+    Optional[T4],
+    Optional[T5],
+    Optional[T6],
+    Optional[T7],
+]: ...
+
+
+@overload
+def together[T1, T2, T3, T4, T5, T6, T7, T8](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    x7: Optional[T7],
+    x8: Optional[T8],
+    /,
+) -> tuple[
+    Optional[T1],
+    Optional[T2],
+    Optional[T3],
+    Optional[T4],
+    Optional[T5],
+    Optional[T6],
+    Optional[T7],
+    Optional[T8],
+]: ...
+
+
+def together(*args: Any) -> Any:
+    """
+    Return a tuple of nones if any argument is None, otherwise return the
+    arguments as a tuple.
+
+    Args:
+        x1, x2, ...:
+            The optional values to check.
+            It accepts any number of arguments (but only type checks up to 8).
+
+    Examples:
+        >>> opt.together(1, 2, 3)
+        (1, 2, 3)
+        >>> opt.together(1, 2, None)
+        (None, None, None)
+
+    See also:
+        - :func:`zip`, which returns None if any argument is None instead of a tuple of nones.
+    """
+    if any(arg is None for arg in args):
+        return tuple(None for _ in args)
+    return args
+
+
+@overload
+def zip[T1, T2](x1: T1 | None, x2: T2 | None, /) -> tuple[T1, T2] | None: ...
+
+
+@overload
+def zip[T1, T2, T3](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    /,
+) -> Optional[tuple[T1, T2, T3]]: ...
+
+
+@overload
+def zip[T1, T2, T3, T4](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    /,
+) -> Optional[tuple[T1, T2, T3, T4]]: ...
+
+
+@overload
+def zip[T1, T2, T3, T4, T5](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    /,
+) -> Optional[tuple[T1, T2, T3, T4, T5]]: ...
+
+
+@overload
+def zip[T1, T2, T3, T4, T5, T6](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    /,
+) -> Optional[tuple[T1, T2, T3, T4, T5, T6]]: ...
+
+
+@overload
+def zip[T1, T2, T3, T4, T5, T6, T7](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    x7: Optional[T7],
+    /,
+) -> Optional[tuple[T1, T2, T3, T4, T5, T6, T7]]: ...
+
+
+@overload
+def zip[T1, T2, T3, T4, T5, T6, T7, T8](
+    x1: Optional[T1],
+    x2: Optional[T2],
+    x3: Optional[T3],
+    x4: Optional[T4],
+    x5: Optional[T5],
+    x6: Optional[T6],
+    x7: Optional[T7],
+    x8: Optional[T8],
+    /,
+) -> Optional[tuple[T1, T2, T3, T4, T5, T6, T7, T8]]: ...
+
+
+def zip(*args: Any) -> Any:
+    """
+    Return a tuple if no argument is None and None otherwise.
+
+    Args:
+        x1, x2, ...:
+            The optional values to check.
+            It accepts any number of arguments (but only type checks up to 8).
+
+    Examples:
+        >>> opt.zip(1, 2, 3)
+        (1, 2, 3)
+        >>> opt.zip(1, 2, None)
+        None
+
+    See also:
+        - :func:`together`, which returns a tuple of nones if any argument is None instead of None.
+    """
+    if any(arg is None for arg in args):
+        return None
+    return args
+
+
+def elements[T](value: T | None) -> Iterable[T]:
+    """
+    Yield nothing or the optional value, if it exists.
+
+    Args:
+        value: The optional value to yield.
+
+    Examples:
+        >>> list(opt.elements(42))
+        [42]
+        >>> list(opt.elements(None))
+        []
+    """
+    if value is not None:
+        yield value
+
+
+def iter[T](value: Iterable[T] | None) -> Iterable[T]:
+    """
+    Yield nothing or the elements of an iterable.
+
+    Args:
+        value: The optional iterable to yield from.
+
+    Examples:
+        >>> list(opt.iter([42]))
+        [42]
+        >>> list(opt.iter(None))
+        []
+    """
+    return iter(()) if value is None else iter(value)
+
+
+def call[**P, R](
+    fn: Optional[Callable[P, R]], *args: P.args, **kwargs: P.kwargs
+) -> Optional[R]:
+    """
+    Call the optional function with the given arguments or return None.
+
+    Args:
+        fn: The optional function to call.
+        *args: The positional arguments to pass to the function.
+        **kwargs: The keyword arguments to pass to the function.
+
+    Examples:
+        >>> opt.call(lambda x: x + 1, 41)
+        42
+        >>> opt.call(None, 40, 2)
+        None
+    """
+    return fn(*args, **kwargs) if fn is not None else None
+
+
+def getattr[T, R: type](
+    obj: Optional[T], attr: str, *, type: type[R] = _any(None)
+) -> Optional[R]:
+    """
+    Get the attribute of an object if it is not None, otherwise return None.
+
+    It raises an AttributeError if the attribute do not exist.
+
+    You can optionally specify the expected result type to get better type checking.
+
+    Args:
+        obj: The optional object to get the attribute from.
+        attr: The name of the attribute to get.
+        type: The expected type of the attribute (optional).
+
+    Examples:
+        >>> opt.getattr(42, "real")
+        42
+        >>> opt.getattr(None, "imag")
+        None
+    """
+    if obj is None:
+        return None
+
+    value = builtins.getattr(obj, attr)
+    if type is not None and not isinstance(value, type):
+        msg = (
+            f"Expected attribute {attr} to be of type {type}, "
+            f"got {builtins.type(value)}"
+        )
+        raise TypeError(msg)
+    return value  # type: ignore

optionz-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: optionz
+Version: 0.1.0
+Summary: Some utility functions for Optional values.
+Project-URL: Homepage, http://github.com/fabiomacedomendes/optionz
+Project-URL: Repository, http://github.com/fabiomacedomendes/optionz
+Author-email: Fábio Macêdo Mendes <fabiomacedomendes@gmail.com>
+Maintainer-email: Fábio Macêdo Mendes <fabiomacedomendes@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Optionz
+
+A nullable type is needed when there can be an absence of a value. Python uses
+`None` to represent the empty value and `Optional[T]`, i.e., `T | None` to 
+represent a nullable `T`. The other option is to use exceptions, but they are 
+not expressed as values in the type system, which can be brittle and error-prone.
+
+Python approach is a compromise between the "million dollar mistake",
+in which `null` is a valid member of every type and the more structured
+`Maybe[T]`, that models nullables as a tagged union of `Just[T]` and `Nothing`.
+
+This library provides some utility functions for working with `Optional` values
+in a more functional style, inspired by the `Maybe` monad in Haskell and Rust's
+equivalent `Option` type. 
+
+The main philosophy is that we *do not* want to introduce a new type like
+[returns](https://returns.readthedocs.io/) and other similar libraries. 
+Instead, we want to provide a similar functionality using plain `Optional` values 
+so that your code can adopt it incrementally without feeling like an alien in 
+the Python ecosystem.
+
+As much as I like functional programming and the `Maybe` monad, I think Python's
+approach is fine and offers most of the same static guarantees. The crucial
+difference is that `Maybe` is a **tagged union** of two types and Python's
+`Optional` is a **union of sets**. They behave mostly the same, but the latter do
+not allow nesting: `Optional[Optional[T]]` flattens to `Optional[T]`, while
+`Maybe[Maybe[T]]` is a whole new type. This is a difference that rarely
+matters in practice, and I don't any anyone is clearly superior to the other.
+
+
+## Installation
+
+Install Optionz using pip/uv/poetry whatever you like. For example:
+
+```bash
+pip install optionz
+```
+
+Optionz consists of a single file, so you can also just copy `opt.py` to your 
+project and import it from there. It do not define any new type so there is
+no conflict with code that import vs ones that vendorize it.
+
+
+## Usage
+
+Import `opt` and use the functions as needed. 
+
+```python
+import opt
+
+opt.unwrap(42) # 42
+opt.unwrap(None) # raises ValueError
+```
+
+## Documentation
+
+The documentation is available at https://optionz.rtfd.io/ and includes more 
+examples and explanations of the functions provided by the library.
+
+## License
+
+Optionz is licensed under the MIT License. See [LICENSE](LICENSE) for more details.

optionz-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+opt.py,sha256=B86FCvpiW1jOE0yetUo3IAHYggTv8rrM7-RvwDA8cmY,13032
+optionz-0.1.0.dist-info/METADATA,sha256=L-B-Mt1egTbfhTBhQqfr69fq2z-c6WtSXcxDJ25L_74,3214
+optionz-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+optionz-0.1.0.dist-info/licenses/LICENSE,sha256=H_RNRyTRIzs8yhgeBUPYa1U1MyJZUZtoWBBSDVAhE-c,1079
+optionz-0.1.0.dist-info/RECORD,,

optionz-0.1.0.dist-info/WHEEL

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

optionz-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Fábio Macêdo Mendes
+
+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.