py-maybetype 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

maybetype/__init__.py

@@ -12,7 +12,8 @@ class Maybe[T]:
 
     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',
+            'Direct instancing of Maybe() not intended and may cause unexpected behavior,'
+            + ' use the maybe() function instead',
             stacklevel=2,
         )
         self.val = val
@@ -32,7 +33,7 @@ class Maybe[T]:
         return self.val == other.val
 
     def __hash__(self) -> int:
-        return self.val.__hash__()
+        return hash(self.val)
 
     @staticmethod
     def cat(vals: 'Iterable[Maybe[T]]') -> list[T]:
@@ -46,7 +47,28 @@ class Maybe[T]:
         return [i.unwrap() for i in vals if i]
 
     @staticmethod
-    def int(val: Any) -> 'Maybe[int]':  # noqa: ANN401
+    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]
+
+    @staticmethod
+    def sequence(vals: 'Iterable[Maybe[T]]') -> 'Maybe[list[T]]':
+        """
+        Returns ``Nothing`` if any of ``vals`` is ``Nothing``, otherwise returns a ``Some`` of a list of unwrapped
+        items of ``vals``.
+
+        >>> assert Maybe.sequence([Some(1), Some(2), Some(3)]) == Some([1, 2, 3])
+        >>> assert Maybe.sequence([Some(1), Nothing, Some(3)]) is Nothing
+        """
+        unwrapped: list[T] = []
+        for i in vals:
+            if i is Nothing:
+                return Nothing
+            unwrapped.append(i.unwrap())
+        return Some(unwrapped)
+
+    @staticmethod
+    def try_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.
@@ -57,12 +79,14 @@ class Maybe[T]:
         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 and_then[R](self, func: Callable[[T], R]) -> 'Maybe[R]':
+        """
+        Like :py:meth:`~maybetype.Maybe.then`, but returns a ``Maybe`` instance instead—``Nothing`` if this instance
+        is a ``Nothing``, ``Some(R)`` if the instance is ``Some``, where ``R`` is the returned value of ``func``.
+        """
+        return Some(func(self.val)) if self.val is not None else Nothing
 
-    def attr[V](self, name: str, typ: type[V] | None = None, *, err: bool = False) -> 'Maybe[V]':
+    def attr[U](self, name: str, typ: type[U] | None = None, *, err: bool = False) -> 'Maybe[U]':
         """
         Attempts to access an attribute ``name`` on the wrapped object, returning a ``Some`` instance wrapping the
         the value if it exists, or ``Nothing`` otherwise.
@@ -74,7 +98,7 @@ class Maybe[T]:
         """
         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:
+    def attr_or[U](self, name: str, default: U) -> U:
         """
         Similar to the ``attr`` method, but unwraps the result if the attribute exists or returns the required default
         value otherwise.
@@ -84,13 +108,13 @@ class Maybe[T]:
         except AttributeError:
             return default
 
-    def get[V](self,
+    def get[U](self,
             accessor: Any,  # noqa: ANN401
-            _typ: type[V] | None = None,
+            _typ: type[U] | None = None,
             *,
             err: bool = False,
-            default: V | None = None,
-        ) -> 'Maybe[V]':
+            default: U | None = None,
+        ) -> 'Maybe[U]':
         """
         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
@@ -112,20 +136,27 @@ class Maybe[T]:
                     raise
         return maybe(default)
 
-    def then[R](self, func: Callable[[T], R]) -> R | None:
+    def test(self, predicate: Callable[[T], bool]) -> 'Maybe[T]':
+        """
+        Returns ``Nothing`` if the wrapped value does not return ``True`` when passed to ``predicate``, otherwise
+        returns the instance the method was called from. When called from a ``Nothing`` instance, ``Nothing`` is always
+        returned.
         """
-        Calls ``func`` with the wrapped value as the argument and returns its value, or returns ``None`` if the wrapped
-        value is ``None``.
+        match self:
+            case Some(val):
+                return self if predicate(val) else Nothing
+            case _:
+                return Nothing
+
+    def then[U](self, func: Callable[[T], U]) -> U | None:
+        """
+        Returns ``func`` called with this instance's wrapped value if ``Some``, otherwise returns ``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,

maybetype/const.py

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

{py_maybetype-0.5.0.dist-info → py_maybetype-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-maybetype
-Version: 0.5.0
+Version: 0.7.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
@@ -16,10 +16,13 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.12
 Provides-Extra: dev
+Requires-Dist: ipython>=9.10.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
-Requires-Dist: ruff>=0.14.8; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Requires-Dist: ty>=0.0.15; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: furo>=2025.12.19; extra == 'docs'
 Requires-Dist: myst-parser>=4.0.1; extra == 'docs'
@@ -29,20 +32,28 @@ Description-Content-Type: text/markdown
 
 # py-maybetype
 
+![Linting & testing](https://github.com/svioletg/py-maybetype/actions/workflows/python-lint-test.yml/badge.svg)
+
 Documentation: <https://py-maybetype.readthedocs.io/en/latest/>
 
+PyPI: <https://pypi.org/project/py-maybetype/>
+
 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.
 
+> [!WARNING]
+> Breaking changes are likely each update in the 0.x phase. Please check the changelog for these
+> changes before updating to a new version.
+
 ## Usage
 
-Install the package with `pip` using the repository link:
+Install with `pip`:
 
 ```bash
-pip install git+https://github.com/svioletg/py-maybetype
+pip install py-maybetype
 ```
 
 Call the `maybe()` function with a `T | None` value to return a `Maybe[T]`—either a `Some` instance
@@ -73,17 +84,20 @@ 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:
+This example in particular can also be done with the `Maybe.try_int()` class method:
 
 ```python
-num1: Maybe[int] = Maybe.int('5')
-num2: Maybe[int] = Maybe.int('five')
+num1: Maybe[int] = Maybe.try_int('5')
+num2: Maybe[int] = Maybe.try_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`.
 
+> [!NOTE]
+> `maybe(None)` will always returning `Nothing`, even if `predicate(None)` would return `True`
+
 ```python
 import re
 import uuid
@@ -108,29 +122,42 @@ from maybetype import maybe, Some
 match maybe(1):
     case Some(val):
         print('Value: ', val)
-    case _:
+    case _: # "case Nothing:" also works, but just matching else in this case will be identical
         print('No value')
 ```
 
 ## Other examples
 
-Converting a `str | None` timestamp into a `datetime` object if not `None`, otherwise returning `None`:
+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)
+assert maybe('2025-09-06T030000').then(datetime.fromisoformat) == datetime(2025, 9, 6, 3, 0)
 
-date_str = None
-date = maybe(date_str).then(datetime.fromisoformat)
-# date == None
+assert maybe(None).then(datetime.fromisoformat) is None
 
-date_str = ''
-date = maybe(date_str or None).then(datetime.fromisoformat)
-# date == None
+assert maybe('' or None).then(datetime.fromisoformat) is 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
 ```
+
+Converting a `str | None` timestamp into a `datetime` object if not `None`, then ensuring that date
+meets certain criteria:
+
+```python
+from datetime import datetime
+from maybetype import maybe
+
+assert maybe('2025-09-06T030000').and_then(datetime.fromisoformat).test(lambda dt: dt.year > 2024)
+
+assert not maybe('2024-09-06T030000').and_then(datetime.fromisoformat).test(lambda dt: dt.year > 2024)
+
+match maybe('2025-09-06T030000').and_then(datetime.fromisoformat).test(lambda dt: dt.year > 2024):
+    case Some(date):
+        ... # Do something with the date
+    case _:
+        ... # Do something else
+```

py_maybetype-0.7.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+maybetype/__init__.py,sha256=Ehj90apIBpn0_lUuN_h-wp6JCk22cqYm4FUbC8Q54No,8973
+maybetype/const.py,sha256=_Lc2ZS-9j5n0TcSTEXGWqQ6SO4hyARBcVZ_JNleNKYU,93
+py_maybetype-0.7.0.dist-info/METADATA,sha256=rD3UtHoMBCklaxnkakh6oW2-qhdKWN5RzPubJTiAYgE,5648
+py_maybetype-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+py_maybetype-0.7.0.dist-info/licenses/LICENSE,sha256=eMbi_IczZg-O56zEg00k6bmfExkQTpx01DN1xLY2w9I,1076
+py_maybetype-0.7.0.dist-info/RECORD,,

py_maybetype-0.5.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-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,,