py-maybetype 0.5.0__py3-none-any.whl

maybetype/__init__.py

@@ -0,0 +1,185 @@
+import warnings
+from collections.abc import Callable, Iterable
+from typing import Any, Never
+
+
+class Maybe[T]:
+    """
+    Wraps a value that may be ``T`` or ``None``, providing methods for conditionally using that value or
+    short-circuiting to ``None`` without longer checks.
+    """
+    __match_args__ = ('val',)
+
+    def __init__(self, val: T | None) -> None:
+        warnings.warn(
+            'Direct instancing of Maybe() is not recommended as of v0.5.0, use the maybe() function instead',
+            stacklevel=2,
+        )
+        self.val = val
+
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}({self.val!r})'
+
+    def __bool__(self) -> bool:
+        return self.val is not None
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Returns ``False`` if the compared object is not a ``Maybe`` instance, otherwise compares their wrapped values.
+        """
+        if not isinstance(other, Maybe):
+            return False
+        return self.val == other.val
+
+    def __hash__(self) -> int:
+        return self.val.__hash__()
+
+    @staticmethod
+    def cat(vals: 'Iterable[Maybe[T]]') -> list[T]:
+        """
+        Takes an iterable of ``Maybe`` and returns a list of the unwrapped values of all ``Some`` objects.
+
+        >>> vals = [maybe(5), maybe(None), maybe(10), maybe(None)]
+        >>> assert vals == [Some(5), Nothing, Some(10), Nothing]
+        >>> assert Maybe.cat(vals) == [5, 10]
+        """
+        return [i.unwrap() for i in vals if i]
+
+    @staticmethod
+    def int(val: Any) -> 'Maybe[int]':  # noqa: ANN401
+        """
+        Attempts to convert ``val`` to an ``int``, returning a ``Some``-wrapped ``int`` if successful, or
+        ``Nothing`` on failure.
+        """
+        try:
+            i: int = int(val)
+            return Some(i)
+        except ValueError:
+            return Nothing
+
+    @staticmethod
+    def map[A, B](fn: 'Callable[[A], Maybe[B]]', vals: Iterable[A]) -> list[B]:
+        """Maps ``fn`` onto ``vals``, taking the unwrapped values of ``Some``s and discarding ``Nothing``s."""
+        return [i.unwrap() for i in map(fn, vals) if i]
+
+    def attr[V](self, name: str, typ: type[V] | None = None, *, err: bool = False) -> 'Maybe[V]':
+        """
+        Attempts to access an attribute ``name`` on the wrapped object, returning a ``Some`` instance wrapping the
+        the value if it exists, or ``Nothing`` otherwise.
+
+        :param typ: Specifies the generic type of the resulting ``Maybe``. Note that the potential value returned by
+            this method will not be coerced to the given type at runtime; this argument is only for typing purposes.
+        :param err: If ``True``, ``AttributeError`` is raised instead of returning ``Nothing`` if ``name`` does not
+            exist.
+        """
+        return Some(getattr(self.val, name)) if err else maybe(getattr(self.val, name, None))
+
+    def attr_or[V](self, name: str, default: V) -> V:
+        """
+        Similar to the ``attr`` method, but unwraps the result if the attribute exists or returns the required default
+        value otherwise.
+        """
+        try:
+            return self.attr(name, err=True).unwrap()
+        except AttributeError:
+            return default
+
+    def get[V](self,
+            accessor: Any,  # noqa: ANN401
+            _typ: type[V] | None = None,
+            *,
+            err: bool = False,
+            default: V | None = None,
+        ) -> 'Maybe[V]':
+        """
+        Attempts to access an item by ``accessor`` on the wrapped object, assuming the wrapped value implements
+        ``__getitem__``. If it does not, or if the value does not exist (list index out of range, key does not exist on
+        a dictionary, etc.), ``Nothing`` is returned.
+
+        :param typ: Specifies the generic type of the resulting ``Maybe``. Note that the potential value returned by
+            this method will not be coerced to the given type at runtime; this argument is only for typing purposes.
+        :param err: By default, ``IndexError`` and ``KeyError`` are not raised when ``__getitem__`` is called on the
+            wrapped value, and ``Nothing`` is returned instead. Setting ``err`` to ``True`` allows these errors to
+            be raised as they normally would. Note that if ``__getitem__`` did not exist on the wrapped value in the
+            first placed (such as with ``Nothing``), no error is raised, and ``Nothing`` is returned regardless.
+        :param default: Specifies an alternate value to return a ``Some`` of instead of returning ``Nothing``.
+        """
+        if hasattr(self.val, '__getitem__'):
+            try:
+                return Some(self.val.__getitem__(accessor)) # type: ignore
+            except (IndexError, KeyError):
+                if err:
+                    raise
+        return maybe(default)
+
+    def then[R](self, func: Callable[[T], R]) -> R | None:
+        """
+        Calls ``func`` with the wrapped value as the argument and returns its value, or returns ``None`` if the wrapped
+        value is ``None``.
+
+        :param func: A ``Callable`` which takes a type of the possible wrapped value (``T``) and can return any type
+            (``R``).
+        """
+        return func(self.val) if self.val is not None else None
+
+    def this_or(self, other: T) -> 'Maybe[T]':
+        """Returns the original wrapped value if not ``None``, otherwise returns a ``Some``-wrapped ``other``."""
+        return self if self else Some(other)
+
+    def unwrap(self,
+            exc: Exception | Callable[..., Never] | None = None,
+            *exc_args: object,
+        ) -> T:
+        """
+        Returns the wrapped value if it is not ``None``, otherwise raises ``ValueError`` by default.
+
+        :param exc: The exception to raise if the wrapped value is ``None``. Can be either an ``Exception`` object, or a
+            ``Callable`` which takes any arguments and does not return. If given ``None``, the default behavior is to
+            raise a ``ValueError`` with the message ``Maybe[<type>] unwrapped into None``.
+        :param exc_args: Arguments to call ``exc`` with, if ``exc`` is a ``Callable``. Otherwise, this argument is not
+            used.
+        """
+        if self.val is None:
+            if isinstance(exc, Exception):
+                raise exc
+            if isinstance(exc, Callable):
+                exc(*exc_args)
+            raise ValueError(f'Maybe[{T.__name__}] unwrapped into None')
+        return self.val
+
+    def unwrap_or(self, other: T) -> T:
+        """Returns the wrapped value if it is not ``None``, otherwise returns ``other``."""
+        return self.val if self.val is not None else other
+
+class Some[T](Maybe[T]):
+    def __init__(self, val: T) -> None:
+        self.val = val
+
+    def __bool__(self) -> bool:
+        return True
+
+class _Nothing[T](Maybe[T]):
+    __match_args__ = ()
+
+    def __init__(self, _: None = None) -> None:
+        self.val = None
+
+    def __repr__(self) -> str:
+        return 'Nothing'
+
+    def __bool__(self) -> bool:
+        return False
+
+Nothing = _Nothing()
+
+def maybe[T](val: T | None, predicate: Callable[[T], bool] = lambda v: v is not None) -> Maybe[T]:
+    """
+    Returns a ``Some`` instance wrapping ``val`` if either ``val`` is not ``None`` or ``predicate(val)`` is ``True``,
+    otherwise returns the ``Nothing`` singleton.
+
+    :param val: A value to wrap.
+    :param predicate: An optional function that takes ``val`` and, if it returns ``False``, discards ``val``
+        and returns a ``Nothing`` instance. Regardless of the predicate, ``Nothing`` is always returned if
+        ``val`` is ``None``.
+    """
+    return Nothing if (val is None) or not predicate(val) else Some(val)

maybetype/const.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+PROJECT_VERSION: str = importlib.metadata.version('maybetype')

py_maybetype-0.5.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: py-maybetype
+Version: 0.5.0
+Summary: A basic implementation of a maybe/option type in Python, largely inspired by Rust's Option.
+Project-URL: Homepage, https://github.com/svioletg/py-maybetype
+Project-URL: Repository, https://github.com/svioletg/py-maybetype
+Project-URL: Documentation, https://py-maybetype.readthedocs.io/en/latest/
+Project-URL: Changelog, https://github.com/svioletg/py-maybetype/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/svioletg/py-maybetype/issues
+Author: Seth 'Violet' Gibbs
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.14.8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2025.12.19; extra == 'docs'
+Requires-Dist: myst-parser>=4.0.1; extra == 'docs'
+Requires-Dist: sphinx-autobuild>=2025.8.25; extra == 'docs'
+Requires-Dist: sphinx<9.0,>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# py-maybetype
+
+Documentation: <https://py-maybetype.readthedocs.io/en/latest/>
+
+A basic implementation of a maybe/option type in Python, largely inspired by Rust's `Option`.
+This was created as part of a separate project I had been working on, but I decided to make it into
+its own package as I wanted to use it elsewhere and its scope grew. This is not meant to be a 1:1
+replication or replacement for Rust's `Option` or Haskell's `Maybe`, but rather just an
+interperetation of the idea that I feel works for Python.
+
+## Usage
+
+Install the package with `pip` using the repository link:
+
+```bash
+pip install git+https://github.com/svioletg/py-maybetype
+```
+
+Call the `maybe()` function with a `T | None` value to return a `Maybe[T]`—either a `Some` instance
+containing the wrapped value, or the `Nothing` singleton.
+
+```python
+from maybetype import Maybe, maybe
+
+# Only the maybe() function should be used,
+# the Maybe class is only imported here for type annotations
+
+def try_int(x: str) -> int | None:
+    """Attempts to convert a string of digits into an `int`, returning `None` if not possible."""
+    try:
+        return int(x)
+    except ValueError:
+        return None
+
+num1: Maybe[int] = maybe(try_int('5'))
+num2: Maybe[int] = maybe(try_int('five'))
+
+print(num1.unwrap()) # 5
+print(num2.unwrap()) # (raises ValueError)
+
+# Some() instances are always truthy, Nothing is falsy
+
+assert bool(num1) is True
+assert bool(num2) is False
+```
+
+This example in particular can also be done with `Maybe`'s built-in `int()` class method:
+
+```python
+num1: Maybe[int] = Maybe.int('5')
+num2: Maybe[int] = Maybe.int('five')
+```
+
+The `maybe` constructor can be given an optional predicate argument to specify a custom condition
+for which `Some(value)` is returned. This argument must be a `Callable` that returns `bool`,
+where returning `False` causes the constructor to return `Nothing`.
+
+```python
+import re
+import uuid
+
+from maybetype import maybe
+
+def is_valid_uuid(s: str) -> bool:
+    return re.match(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}|[0-9a-f]{32}", s) is not None
+
+assert maybe('3b1bcc3a-41d5-49a5-8273-10cc605e31f9', is_valid_uuid)
+assert maybe('3b1bcc3a41d549a5827310cc605e31f9', is_valid_uuid)
+assert not maybe('qwertyuiopasdfghjklzxcvbnm', is_valid_uuid)
+assert not maybe('nf0cmmdq-l0gt-rq5a-upry-706trht3ocv9', is_valid_uuid)
+```
+
+`Maybe` instances can also be used in `match`/`case` pattern matching to access the wrapped value,
+like so:
+
+```python
+from maybetype import maybe, Some
+
+match maybe(1):
+    case Some(val):
+        print('Value: ', val)
+    case _:
+        print('No value')
+```
+
+## Other examples
+
+Converting a `str | None` timestamp into a `datetime` object if not `None`, otherwise returning `None`:
+
+```python
+from datetime import datetime
+from maybetype import maybe
+
+date_str = '2025-09-06T030000'
+date = maybe('2025-09-06T030000').then(datetime.fromisoformat)
+# date == datetime.datetime(2025, 9, 6, 3, 0)
+
+date_str = None
+date = maybe(date_str).then(datetime.fromisoformat)
+# date == None
+
+date_str = ''
+date = maybe(date_str or None).then(datetime.fromisoformat)
+# date == None
+# Maybe does not treat falsy values as None, only strictly x-is-None values
+# Without `or None` here, datetime.fromisoformat would have raised a ValueError
+```

py_maybetype-0.5.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+maybetype/__init__.py,sha256=CQFFyrpwovLYg_17QDcxY8jssh9CISi6UMlsilL-3kc,7696
+maybetype/const.py,sha256=Vu_oNFgMuJFf4wGqh2ywIO7I0rA0zlrJb4KdPeoupns,90
+py_maybetype-0.5.0.dist-info/METADATA,sha256=jxcQQqsJTYiZ_qhQFrMqJ_d6lpMJosG-JrdHzW39KEc,4562
+py_maybetype-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+py_maybetype-0.5.0.dist-info/licenses/LICENSE,sha256=eMbi_IczZg-O56zEg00k6bmfExkQTpx01DN1xLY2w9I,1076
+py_maybetype-0.5.0.dist-info/RECORD,,

py_maybetype-0.5.0.dist-info/WHEEL

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

py_maybetype-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Seth "Violet" Gibbs
+
+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.