py-maybetype 0.6.0__tar.gz → 0.7.0__tar.gz

py_maybetype-0.6.0/.github/workflows/python-lint-test.yml → py_maybetype-0.7.0/.github/workflows/lint-test.yml

@@ -13,17 +13,24 @@ jobs:
   build:
     name: Lint and test
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.12', '3.13', '3.14' ]
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.12
+    - name: Set up Python
       uses: actions/setup-python@v3
       with:
-        python-version: "3.12"
+        python-version: ${{ matrix.python-version }}
+        architecture: x64
     - name: Install project + dependencies
       run: |
         python -m pip install --upgrade pip
         pip install .[dev]
+    - name: Check with ty
+      run: |
+        ty check .
     - name: Lint with ruff
       run: |
         ruff check .

{py_maybetype-0.6.0 → py_maybetype-0.7.0}/.github/workflows/publish-to-pypi.yml

@@ -40,7 +40,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: pypi
-      url: https://pypi.org/p/maybetype
+      url: https://pypi.org/p/py-maybetype
     permissions:
       id-token: write
     steps:
@@ -59,7 +59,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: testpypi
-      url: https://test.pypi.org/p/maybetype
+      url: https://test.pypi.org/p/py-maybetype
     permissions:
       id-token: write
     steps:

{py_maybetype-0.6.0 → py_maybetype-0.7.0}/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+Generally, more significant breaking changes will be put near the top of each category.
+
+## [0.7.0]
+
+### Added
+
+- Added static method `Maybe.sequence()`
+- Added methods to `Maybe`:
+  - `and_then()`: Similar to `Maybe.then()`, but returns a `Maybe` instance
+  - `test()`: Returns `Some` if the instance is `Some` and the test function returns `True` when
+    called with the wrapped value, otherwise returns `Nothing`
+
+### Changed
+
+- Renamed static method `Maybe.int()` to `Maybe.try_int()`
+- `Maybe.__hash__()` now returns `hash()` called with the wrapped value instead of accessing its
+  `__hash__()` method
+- Most type signatures now use the more standard type variable naming of `T`, `U`, `V`...
+  - The only exception currently is the static method `Maybe.map()`, which uses `A` and `B` since
+    `T` already belongs the `Maybe` class' scope and the method operates on unrelated types
+
+### Removed
+
+- Removed method `Maybe.this_or()`
+  - Redundant, `maybe(x).this_or(y)` is exactly the same as `maybe(x) or Some(y)`
+
 ## [0.6.0] - 2026-01-21
 
 ### Changed

{py_maybetype-0.6.0 → py_maybetype-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-maybetype
-Version: 0.6.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'
@@ -41,6 +44,10 @@ its own package as I wanted to use it elsewhere and its scope grew. This is not
 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 with `pip`:
@@ -77,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
@@ -112,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.6.0 → py_maybetype-0.7.0}/README.md

@@ -12,6 +12,10 @@ its own package as I wanted to use it elsewhere and its scope grew. This is not
 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 with `pip`:
@@ -48,17 +52,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
@@ -83,29 +90,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.6.0 → py_maybetype-0.7.0}/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,

{py_maybetype-0.6.0 → py_maybetype-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "py-maybetype"
-version = "0.6.0"
+version = "0.7.0"
 description = "A basic implementation of a maybe/option type in Python, largely inspired by Rust's Option."
 authors = [
     { name = "Seth 'Violet' Gibbs" }
@@ -17,6 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 
 [project.urls]
@@ -28,8 +29,10 @@ Issues = "https://github.com/svioletg/py-maybetype/issues"
 
 [project.optional-dependencies]
 dev = [
+    "ipython>=9.10.0",
     "pytest>=9.0.2",
-    "ruff>=0.14.8",
+    "ruff>=0.15.0",
+    "ty>=0.0.15",
 ]
 docs = [
     "furo>=2025.12.19",

{py_maybetype-0.6.0 → py_maybetype-0.7.0}/tests/test_maybe.py

@@ -1,18 +1,21 @@
 import re
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from copy import deepcopy
 from dataclasses import dataclass
 from string import ascii_lowercase
 from types import EllipsisType
 from typing import Any
 
-import pytest
+import pytest  # ty:ignore[unresolved-import, unused-ignore-comment]; seems to only show up in workflow runs?
 
-from maybetype import Maybe, Nothing, Some, maybe
+from maybetype import Maybe, Nothing, Some, _Nothing, maybe
 
 ALPHANUMERIC: str = ascii_lowercase + '0123456789'
 MAYBE_UNWRAP_NONE_REGEX: re.Pattern[str] = re.compile(r"Maybe\[.*\] unwrapped into None")
 
+def square(n: int) -> int:
+    return n * n
+
 def test_maybe_none_unwrap_error() -> None:
     m_none: Maybe[Any] = Nothing
     assert bool(m_none) is False
@@ -24,11 +27,27 @@ def test_maybe_none_unwrap_error() -> None:
 def test_maybe_none_is_nothing() -> None:
     assert maybe(None) is Nothing
 
-def test_maybe_this_or() -> None:
-    assert Maybe.int('10').this_or(0).unwrap() == 10  # noqa: PLR2004
-    assert Maybe.int('ten').this_or(0).unwrap() == 0
+@pytest.mark.parametrize(('val'),
+    [
+        None,
+        0,
+        1,
+        '',
+        'string',
+        [],
+        [1, 2, 3],
+        True,
+        False,
+    ],
+)
+def test_nothing_instance_always_wraps_none(val: object) -> None:
+    assert _Nothing(val).val is None # type: ignore
+
+def test_maybe_or() -> None:
+    assert Maybe.try_int('10') or Some(0).unwrap() == 10  # noqa: PLR2004
+    assert Maybe.try_int('ten') or Some(0).unwrap() == 0
     with pytest.raises(ValueError, match=MAYBE_UNWRAP_NONE_REGEX):
-        Maybe.int('ten').unwrap()
+        Maybe.try_int('ten').unwrap()
 
 @pytest.mark.parametrize(('val', 'default'),
     [
@@ -122,14 +141,14 @@ def test_maybe_get(val: object, accessor: object, result: object) -> None:
     assert m.get(accessor) == result
 
 def test_maybe_cat() -> None:
-    assert Maybe.cat(map(Maybe.int, ALPHANUMERIC)) == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+    assert Maybe.cat(map(Maybe.try_int, ALPHANUMERIC)) == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
 def test_maybe_cat_failure() -> None:
     with pytest.raises(AttributeError, match='has no attribute \'unwrap\''):
         Maybe.cat([1, 2, 3]) # type: ignore
 
 def test_maybe_map() -> None:
-    assert Maybe.map(Maybe.int, ALPHANUMERIC) == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+    assert Maybe.map(Maybe.try_int, ALPHANUMERIC) == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
 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
@@ -147,10 +166,13 @@ def is_valid_uuid(s: str) -> bool:
         ('nf0cmmdq-l0gt-rq5a-upry-706trht3ocv9', is_valid_uuid, False),
     ],
 )
-def test_maybe_with_predicate[T](value: T, predicate: Callable[[T], bool], expected_bool: bool) -> None:
+def test_maybe_with_predicate_and_test[T](value: T, predicate: Callable[[T], bool], expected_bool: bool) -> None:
     assert bool(maybe(value, predicate)) is expected_bool
     if expected_bool is False:
         assert maybe(value, predicate) is Nothing
+        assert maybe(value).test(predicate) is Nothing
+    else:
+        assert maybe(value).test(predicate)
 
 @pytest.mark.parametrize(('value', 'predicate', 'expected'),
     [
@@ -176,3 +198,24 @@ def test_maybe_pattern_matching[T](value: T, predicate: Callable[[T], bool], exp
             result = None
 
     assert result == expected
+
+@pytest.mark.parametrize(('value', 'fn', 'expected'),
+    [
+        (None, square, Nothing),
+        (0, square, Some(0)),
+        (5, square, Some(25)),
+        ('image.png', lambda s: s.split('.')[0], Some('image')),
+    ],
+)
+def test_maybe_and_then[T, U](value: T, fn: Callable[[T], U], expected: Maybe[T]) -> None:
+    assert maybe(value).and_then(fn) == expected
+
+@pytest.mark.parametrize(('vals', 'expected'),
+    [
+        ([Some(1), Some(2), Some(3)], Some([1, 2, 3])),
+        ([Some(1), Nothing, Some(3)], Nothing),
+        ([Nothing, Nothing, Nothing], Nothing),
+    ],
+)
+def test_maybe_sequence[T](vals: Iterable[Maybe[T]], expected: Maybe[list[T]]) -> None:
+    assert Maybe.sequence(vals) == expected