pythonic-fp-gadgets 4.0.2__py3-none-any.whl → 4.0.4__py3-none-any.whl

pythonic_fp/gadgets/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,14 +14,15 @@
 
 """
 Gadgets
--------
+=======
 
 .. admonition:: Collection of mostly self-contained functions and classes
 
     - Functions and classes which could go multiple places or have
       no good place to go.
     - Self-contained with minimal dependencies.
-    - No pythonic_fp dependencies.
+
+      - No pythonic_fp dependencies at all.
 
 """
 
@@ -31,31 +32,33 @@ from inspect import getmro
 __all__ = ['first_common_ancestor', 'iterate_over_arguments']
 
 __author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2026 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'
 
 
 def first_common_ancestor(cls1: type, cls2: type) -> type:
-    """Find the least upper bound in the inheritance graph
-    of two classes.
+    """
+    .. admonition:: Least upper bound
 
-    .. warning::
+        Find the least upper bound in the inheritance graph
+        of two classes.
 
-        This function can fail with a TypeError. Some error messages
-        seen are
+        :param cls1: A class in the inheritance hierarchy.
+        :param cls2: A class in the inheritance hierarchy.
+        :returns: First common ancestor based on ``getmro`` order.
+        :raises TypeError: Raised when no common ancestor exists, or when
+                           not caught when raised by ``inspect.getmro``.
 
-        - multiple bases have instance lay-out conflict
-        - type 'bool' is not an acceptable base type
+        .. warning::
 
-        This happens frequently when the function is given
-        Python builtin types or in multiple inheritance situations.
+            This function can fail with a TypeError. Some error messages
+            seen are
 
-    :param cls1: A class in the inheritance hierarchy.
-    :param cls2: A class in the inheritance hierarchy.
-    :returns: First common ancestor based on getmro order.
-    :raises TypeError: Raised when no common ancestor or not
-                       caught when raised by ``inspect.getmro``.
+            - multiple bases have instance lay-out conflict
+            - type 'bool' is not an acceptable base type
 
+            This happens frequently when the function is given
+            Python builtin types or in multiple inheritance situations.
     """
     if issubclass(cls1, cls2):
         return cls2
@@ -69,17 +72,17 @@ def first_common_ancestor(cls1: type, cls2: type) -> type:
 
 
 def iterate_over_arguments[A](*args: A) -> Iterator[A]:
-    """Function returning an iterator of its arguments.
+    """
+    .. admonition:: Iterate over arguments.
 
-    .. note::
+        Function returning an iterator over its arguments.
 
-        Does not create an object to iterate over.
+        :param args: Objects to iterate over.
+        :returns: An iterator of the function's arguments.
 
-        - well, not in the Python world
-        - maybe in the C world
+        .. note::
 
-    :param args: Objects to iterate over.
-    :returns: An iterator of the functions arguments.
+            Does not create a Python object to iterate over.
 
     """
     yield from args

pythonic_fp/gadgets/__init__.pyi

@@ -1,6 +1,6 @@
 from collections.abc import Iterator
 
-__all__ = ['iterate_over_arguments', 'first_common_ancestor']
+__all__ = ['first_common_ancestor', 'iterate_over_arguments']
 
-def iterate_over_arguments[A](*args: A) -> Iterator[A]: ...
 def first_common_ancestor(cls1: type, cls2: type) -> type: ...
+def iterate_over_arguments[A](*args: A) -> Iterator[A]: ...

pythonic_fp/gadgets/box.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,29 +12,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__all__ = ['Box']
-
 from collections.abc import Callable, Iterator
 from typing import cast, Final, overload
 
+__all__ = ['Box']
+
 type _Sentinel = object
 _sentinel: Final[_Sentinel] = object()
 
 
 class Box[T]:
-    """Container holding at most one item of a given type.
-
-    .. note::
+    """
+    .. admonition:: Box
 
-       - ``Box(item: T)``: contains at one item of type ``T``
-       - ``Box[T]()``: creates empty container
+        Container holding at most one item of a given type.
 
-       Where type ``T`` is some definite type, which
-       could be ``None`` or even ``Never``.
+        .. tip::
 
-    .. tip ::
+            Objects of the ``Box`` type
 
-       ``Box`` objects can be used in Python match statements.
+            - Are truthy if not empty.
+            - Can be combined with other iterators before being filled.
+            - Can be used like a promise.
+            - Can be used in Python match statements.
+            - Threadsafe
 
     """
     __slots__ = ('_item',)
@@ -47,34 +48,57 @@ class Box[T]:
 
     def __init__(self, item: T | _Sentinel = _sentinel) -> None:
         """
-        :param item: An optional initial contained ``item``
-                     for the ``Box``.
+        .. admonition:: Initializer
+
+            Initialize ``Box`` with 0 or 1 items.
+
+        :param item: An optional initial ``item`` for the ``Box``.
+
         """
         self._item = item
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: Bool
+
+            Truthy if not empty.
+
+        """
         return self._item is not _sentinel
 
     def __iter__(self) -> Iterator[T]:
-        if self:
-            yield cast(T, self._item)
+        """
+        .. admonition:: Iterability
 
-    def __repr__(self) -> str:
+            Iterates boxed item.
+
+        """
         if self:
-            return 'Box(' + repr(self._item) + ')'
-        return 'Box()'
+            yield cast(T, self._item)
 
     def __len__(self) -> int:
+        """
+        .. admonition:: Length
+
+            - 1 if ``Box`` contains an item
+            - 0 if ``Box`` is empty
+
+        :returns: The number of items currently in the ``Box``.
+
+        """
         return 1 if self else 0
 
     def __eq__(self, other: object) -> bool:
         """
-        Efficiently compare to another object.
+        .. admonition:: Equality comparison
+
+            Efficiently compare ``Box`` to another object.
 
-        :param other: The object to be compared with,
-        :returns: ``True`` if ``other`` is of type Box and contains
+        :param other: The object to be compared.
+        :returns: ``True`` if ``other`` is another ``Box`` and contains
                   an object which compares as equal to the object
                   contained in the ``Box``, otherwise ``False``.
+
         """
         if not isinstance(other, type(self)):
             return False
@@ -85,16 +109,34 @@ class Box[T]:
             return True
         return False
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: Representation string
+
+            Construct string 'Box()' if empty, otherwise 'Box(item_repr)'
+            where ``item_repr = repr(item)`` for the currently contained
+            item. 
+
+        :returns: A string to reproduce the current state of the ``Box``. 
+
+        """
+        if self:
+            return 'Box(' + repr(self._item) + ')'
+        return 'Box()'
+
     @overload
     def get(self) -> T: ...
     @overload
     def get(self, alt: T) -> T: ...
 
     def get(self, alt: T | _Sentinel = _sentinel) -> T:
-        """Return the contained item, if it exists, otherwise
-        an alternate item, if given.
+        """
+        .. admonition:: Get
+
+            Return the boxed item, if it exists, otherwise
+            an alternate item, if given.
 
-        :param alt: An optional item of type ``T`` to return 
+        :param alt: An optional item of type ``T`` to return
                     if the ``Box`` is empty.
         :returns: Contents of ``Box`` or an alternate item, if given,
                   when the ``Box`` is empty.
@@ -110,7 +152,10 @@ class Box[T]:
         return cast(T, alt)
 
     def pop(self) -> T:
-        """Pop the contained item if ``Box`` is not empty.
+        """
+        .. admonition:: Pop
+
+            Pop item from ``Box`` if not empty.
 
         :returns: The item contained in the ``Box``.
         :raises ValueError: If Box is empty.
@@ -124,7 +169,10 @@ class Box[T]:
         return popped
 
     def push(self, item: T) -> None:
-        """Push an item into an empty ``Box``.
+        """
+        .. admonition:: Push
+
+            Push an item into ``Box`` if empty.
 
         :param item: Item to push into the empty ``Box``.
         :raises ValueError: If ``Box`` is not empty.
@@ -138,15 +186,24 @@ class Box[T]:
         return None
 
     def put(self, item: T) -> None:
-        """Put an item in the Box. Discard any previous contents."""
+        """
+        .. admonition:: Put
+
+            Put an item in the Box. Discard any previous contents.
+
+        """
         self._item = item
 
     def exchange(self, new_item: T) -> T:
-        """Exchange an item with what is in the Box.
+        """
+        .. admonition:: Exchange
+
+            Exchange an item with what is in the Box.
 
         :param ``new_item``: New item to exchange for current item.
         :returns: Original contents of the ``Box``.
         :raises ValueError: If Box is empty.
+
         """
         if self._item is _sentinel:
             msg = 'Box: Trying to exchange items from an empty Box'
@@ -156,11 +213,14 @@ class Box[T]:
         return popped
 
     def map[U](self, f: Callable[[T], U]) -> 'Box[U]':
-        """Map function ``f`` over contents. We need to return a new
-        instance since the type of Box can change.
+        """
+        .. admonition:: Map
+
+            Map function ``f`` over contents. We need to return a new
+            instance since the type of Box can change.
 
         :param f: Mapping function.
-        :returns: A new instance.
+        :returns: New instance.
 
         """
         if self._item is _sentinel:
@@ -168,10 +228,13 @@ class Box[T]:
         return Box(f(cast(T, self._item)))
 
     def bind[U](self, f: Callable[[T], 'Box[U]']) -> 'Box[U]':
-        """Flatmap ``Box`` with function ``f``.
+        """
+        .. admonition:: Bind
+
+            Flatmap ``Box`` with function ``f``.
 
         :param f: Binding function.
-        :returns: A new instance.
+        :returns: New instance.
 
         """
         if self._item is _sentinel:

pythonic_fp/gadgets/sentinels/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,6 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
-__license__ = 'Apache License 2.0'
+"""
+sentinels
+---------
+
+.. admonition:: Sentinel values
+
+    - Singletons
+    - Threadsafe
+    - Useful for both
+
+      - referenced objects
+      - hidden implementation details
+
+"""

pythonic_fp/gadgets/sentinels/flavored.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,29 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-.. admonition:: Sentinel values labeled by different (hashable) flavors.
-
-    When different flavors of the truth are needed.
-
-.. note::
-
-    Can be compared using ``==`` and ``!=``. A flavored sentinel
-    value always equals itself and never equals anything else,
-    especially other flavored sentinel values.
-
-    Useful for union types where ``Sentinel[H]`` is one of the
-    types making up the union.
-
-    To ensure that reference equality is used, put the known
-    sentinel value first in the comparison.
-
-.. note::
-
-    Threadsafe.
-
-"""
-
 import threading
 from typing import ClassVar, final, Hashable
 
@@ -43,12 +20,34 @@ __all__ = ['Sentinel']
 
 @final
 class Sentinel[H: Hashable]:
+    """
+    .. admonition:: Sentinel
+
+        Sentinel values labeled by different (hashable) flavors.
+
+        .. note::
+
+            - Useful for union types.
+            - A flavored ``Sentinel`` value always equals itself
+              and never equals anything else, especially other
+              flavored sentinel values.
+
+    """
+
     __slots__ = ('_flavor',)
 
     _flavors: 'dict[H, Sentinel[H]]' = {}
     _lock: ClassVar[threading.Lock] = threading.Lock()
 
     def __new__(cls, flavor: H) -> 'Sentinel[H]':
+        """
+        .. admonition:: new
+
+            :param flavor: Hashable value determining which
+                           flavored ``Sentinel`` to return.
+            :returns: The ``Sentinel(flavor)`` singleton instance.
+
+        """
         if flavor not in cls._flavors:
             with cls._lock:
                 if flavor not in cls._flavors:
@@ -57,18 +56,44 @@ class Sentinel[H: Hashable]:
 
     def __init__(self, flavor: H) -> None:
         """
-        :param flavor: Some Hashable value of generic type ``H``.
-        :returns: The ``Sentinel`` singleton instance with flavor ``flavor``.
-        :rtype: ``Sentinel[H]`` where ``H`` is a subtype of Hashable.
+        .. admonition:: init
+
+            :param flavor: Hashable value to initially cache the flavor
+            :type flavor: ``H: Hashable``
+
         """
         if not hasattr(self, '_flavor'):
             self._flavor = flavor
 
     def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            Construct string 'Sentinel(flavor)' where the flavor
+            is displayed with ``repr()``.
+
+            :returns: A string to reproduce the flavored sentinel.
+
+        """
         return "Sentinel('" + repr(self._flavor) + "')"
 
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Construct string 'Sentinel(flavor)' where the flavor
+            is displayed with ``str()``.
+
+            :returns: A string meaningful to an end user.
+
+        """
+        return "Sentinel('" + str(self._flavor) + "')"
+
     def flavor(self) -> H:
         """
-        :returns: The sentinel's flavor. A ``Hashable`` value of type ``H``.
+        .. admonition:: get flavor
+
+            :returns: The sentinel's flavor.
+
         """
         return self._flavor

pythonic_fp/gadgets/sentinels/novalue.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,112 +12,176 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-.. admonition:: Singleton class representing an actually,
-                not potentially, missing value.
+import threading
+from typing import ClassVar, final
 
-    ``NoValue()`` is a singleton object representing a missing value.
+__all__ = ['NoValue']
 
-    While ``None`` and ``()`` are frequently used as sentinel values,
-    I prefer to think of them as
 
-    - ``None``: Returns, or returned, no values.
-    - ``()``: An empty, possibly typed, iterable collection.
+@final
+class NoValue:
+    """
+    .. admonition:: missing value
 
-.. important::
+        Singleton class representing an actual, not
+        potential, missing value.
 
-    Given variables
+        While ``None`` and ``()`` are frequently used as sentinel values,
+        I prefer to think of them as
 
-    .. code:: python
+        - ``None`` as returns, or returned, no values.
+        - ``()`` as an empty, possibly typed, iterable collection.
 
-        x: int | NoValue
-        y: int | NoValue
+        .. important::
 
-    Equality between ``x`` and ``y`` means both values exist and compare
-    as equal. If one or both of theses values are missing, then what is
-    there to compare?
+            Given variables
 
-    .. table:: ``x == y``
+            .. code:: python
 
-        +-----------+-----------+--------+--------+
-        |    x∖y    | NoValue() | 42     | 57     |
-        +===========+===========+========+========+
-        | NoValue() | false     | false  | false  |
-        +-----------+-----------+--------+--------+
-        | 42        | false     | true   | false  |
-        +-----------+-----------+--------+--------+
-        | 57        | false     | false  | true   |
-        +-----------+-----------+--------+--------+
+                x: int | NoValue
+                y: int | NoValue
 
-    Similarly for not equals.
+            Equality between ``x`` and ``y`` means both values exist
+            and compare as equal.
 
-    .. table:: ``x != y``:wq
+            .. table:: ``x == y``
 
-        +-----------+-----------+--------+--------+
-        |    x∖y    | NoValue() | 42     | 57     |
-        +===========+===========+========+========+
-        | NoValue() | false     | false  | false  |
-        +-----------+-----------+--------+--------+
-        | 42        | false     | false  | true   |
-        +-----------+-----------+--------+--------+
-        | 57        | false     | true   | false  |
-        +-----------+-----------+--------+--------+
+                +-------------------+-------------------+------------+------------+
+                |                   |                   |            |            |
+                +===================+===================+============+============+
+                |                   | ``y = NoValue()`` | ``y = 42`` | ``y = 57`` |
+                +-------------------+-------------------+------------+------------+
+                | ``x = NoValue()`` | ``False``         | ``False``  | ``False``  |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 42``        | ``False``         | ``True``   | ``False``  |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 57``        | ``False``         | ``False``  | ``True``   |
+                +-------------------+-------------------+------------+------------+
 
-.. warning::
+            .. table:: ``x != y``
 
-    Only use ``==`` or ``!=`` in value comparisons. To directly
-    identity the ``NoValue`` singleton, use ``is`` and ``is not``
-    instead.
+                +-------------------+-------------------+------------+------------+
+                |                   |                   |            |            |
+                +===================+===================+============+============+
+                |                   | ``y = NoValue()`` | ``y = 42`` | ``y = 57`` |
+                +-------------------+-------------------+------------+------------+
+                | ``x = NoValue()`` | ``False``         | ``False``  | ``False``  |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 42``        | ``False``         | ``False``  | ``True``   |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 57``        | ``False``         | ``True``   | ``False``  |
+                +-------------------+-------------------+------------+------------+
 
-.. note::
+            .. warning::
 
-    Threadsafe.
+                - use ``==`` or ``!=`` only in value comparisons
+                - use ``is`` and ``is not`` to identity the ``NoValue()``
+                  singleton itself
 
-.. tip::
+        .. tip::
 
-    Use as a hidden implementation detail when creating "optional"
-    arguments to functions and methods.
+            Use in a union type when creating "optional" arguments
+            to functions and methods.
 
-    To help ensure the abstraction does not leak,
+            To help ensure the abstraction stays a hidden implementation
+            detail and does not leak out into user code,
 
-    - Do not export the sentinel value.
-    - Use ``@overload`` to keep the NoValue type out of documentation and IDEs.
- 
-"""
-import threading
-from typing import ClassVar, final
+            - Do not export the sentinel value.
 
-__all__ = ['NoValue']
+              - A new reference can always be generated via ``NoValue()``.
 
+            - Use ``@overload`` to keep the ``NoValue`` type out of
+              documentation and IDEs.
+
+    """
 
-@final
-class NoValue():
     __slots__ = ()
 
     _instance: 'ClassVar[NoValue | None]' = None
     _lock: ClassVar[threading.Lock] = threading.Lock()
+    _hash: ClassVar[int] = 0
 
     def __new__(cls) -> 'NoValue':
         """
-        :returns: The ``NoValue`` singleton instance.
+        .. admonition:: new
+
+            :returns: The ``NoValue()`` singleton instance.
+
         """
         if cls._instance is None:
             with cls._lock:
                 if cls._instance is None:
+                    cls._hash = id(cls)
                     cls._instance = super().__new__(cls)
         return cls._instance
 
+    def __hash__(self) -> int:
+        """
+        .. admonition:: hash
+
+            :returns: The singleton's unique integer hash value.
+        """
+        return type(self)._hash
+
     def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            :returns: The string 'NoValue()'.
+
+        """
         return 'NoValue()'
 
+    def __bool__(self) -> bool:
+        """
+        .. admonition:: bool
+
+            Always falsy.
+
+            :returns: False
+
+            .. tip
+
+                Can be used to provide a fallback value when used
+                with Python shortcut logic.
+
+                .. code:: python
+
+                    result: str | NoValue = NoValue()
+                    if predicate(x):
+                        result = 'some non-empty string'
+                    value = result or 'fallback string'
+
+        """
+        return False
+
     def __eq__(self, other: object) -> bool:
         """
-        :returns: ``False``
+        .. admonition:: Equality comparison
+
+            :param other: The object to be compared.
+            :returns: ``False`` even if compared to itself.
+
+            .. warning::
+
+                - non-standard comparison semantics
+                - always returns ``False``
+                - if one or both values are missing,
+                  then what is there to compare?
+
         """
         return False
 
     def __ne__(self, other: object) -> bool:
         """
-        :returns: ``False``
+        .. admonition:: not equal
+
+            :returns: ``False``
+
+            .. warning::
+
+                - non-standard comparison semantics
+                - always returns ``False``
+
         """
         return False

pythonic_fp/gadgets/sentinels/novalue.pyi

@@ -2,5 +2,7 @@ __all__ = ['NoValue']
 
 class NoValue:
     def __new__(cls) -> NoValue: ...
+    def __hash__(self) -> int: ...
+    def __bool__(self) -> bool: ...
     def __eq__(self, other: object) -> bool: ...
     def __ne__(self, other: object) -> bool: ...

pythonic_fp/gadgets/wrap.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -11,6 +11,15 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+.. admonition:: Module wrap
+
+    Wrap objects in ways to make them "immutable."
+
+    - Class ``Wrap``: wrap an object
+    - Class ``HWrap``: wrap a hashable object
+
+"""
 
 __all__ = ['Wrap', 'HWrap']
 
@@ -18,37 +27,71 @@ from collections.abc import Callable, Iterator, Hashable
 
 
 class Wrap[T]():
-    """Immutablely wrap exactly one value of a given type.
-
-    .. tip::
+    """
+    .. admonition:: Wrap object
 
-        ``Wrap`` objects can be used in Python match statements.
+        Immutablely wrap exactly one value of a
+        given type. ``Wrap`` objects can be used
+        in Python match statements.
 
     """
     __slots__ = ('_item',)
     __match_args__ = ('_item',)
 
     def __init__(self, item: T) -> None:
+        """
+        .. admonition:: Initializer
+
+            Initialize ``Wrap`` with 1 required item.
+
+        :param item: Item to be wrapped.
+
+        """
         self._item = item
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: Bool
+
+            Truthiness same as wrapped object.
+
+        """
         return bool(self._item)
 
     def __iter__(self) -> Iterator[T]:
+        """
+        .. admonition:: Iter
+
+            Iterable, iterates wrapped item.
+
+        """
         if self:
             yield self._item
 
-    def __repr__(self) -> str:
-        return 'Wrap(' + repr(self._item) + ')'
+    def __str__(self) -> str:
+        """
+        .. admonition:: User string
+
+            Construct string 'Box(item_str)'
+            where ``item_str = str(item)`` for the currently contained
+            item. 
+
+        :returns: A string to reproduce the current state of the ``Box``. 
+
+        """
+        return 'Wrap(' + str(self._item) + ')'
 
     def __eq__(self, other: object) -> bool:
         """
-        Efficiently compare to another object.
+        .. admonition:: Equality comparison
+
+            Efficiently compare ``Wrap`` to another object.
 
         :param other: The object to be compared with,
         :returns: ``True`` if ``other`` is of type Wrap and wraps
                   an object which compares as equal to the wrapped
                   object, otherwise ``False``.
+
         """
         if not isinstance(other, type(self)):
             return False
@@ -58,36 +101,46 @@ class Wrap[T]():
         return self._item == other._item
 
     def map[U](self, f: Callable[[T], U]) -> 'Wrap[U]':
-        """Map function ``f`` over contents.
+        """
+        .. admonition:: Map
+
+            Map function ``f`` over contents.
+
+        Map function ``f`` over contents.
 
         :param f: Mapping function.
-        :returns: A new instance.
+        :returns: New instance.
 
         """
         return Wrap(f(self._item))
 
     def bind[U](self, f: Callable[[T], 'Wrap[U]']) -> 'Wrap[U]':
-        """Flatmap the ``Wrap`` with function ``f``.
+        """
+        .. admonition:: Bind
+
+            Flatmap wrapped object with function ``f``.
 
         :param f: Binding function.
-        :returns: A new instance.
+        :returns: New instance.
 
         """
         return f(self._item)
 
 
 class HWrap[T: Hashable](Hashable):
-    """Immutablely wrap exactly one hashable value of a given type.
-
-    .. tip::
+    """
+    .. admonition:: Wrap hashable object
 
-        ``HWrap`` objects can be used in Python match statements.
+        Immutablely wrap exactly one value of a
+        given hashable type. ``HWrap`` objects can
+        be used in Python match statements.
 
-    .. tip::
+        .. tip::
 
-        ``HWrap`` objects are hashable..
+            ``HWrap`` objects are hashable.
 
     """
+
     __slots__ = ('_item', '_hash')
     __match_args__ = ('_item',)
 
@@ -98,9 +151,21 @@ class HWrap[T: Hashable](Hashable):
         return self._hash
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: Bool
+
+            Truthiness same as wrapped object.
+
+        """
         return bool(self._item)
 
     def __iter__(self) -> Iterator[T]:
+        """
+        .. admonition:: Iter
+
+            Iterable, iterates wrapped item.
+
+        """
         if self:
             yield self._item
 
@@ -109,12 +174,15 @@ class HWrap[T: Hashable](Hashable):
 
     def __eq__(self, other: object) -> bool:
         """
-        Efficiently compare to another object.
+        .. admonition:: Equality comparison
 
-        :param other: The object to be compared with,
+            Efficiently compare to another object.
+
+        :param other: Object to be compared
         :returns: ``True`` if ``other`` is of type HWrap and wraps
                   an object which compares as equal to the wrapped
                   object, otherwise ``False``.
+
         """
         if not isinstance(other, type(self)):
             return False
@@ -126,19 +194,26 @@ class HWrap[T: Hashable](Hashable):
         return self._item == other._item
 
     def map[U](self, f: Callable[[T], U]) -> 'HWrap[U]':
-        """Map function ``f`` over contents.
+        """
+        .. admonition:: Map
+
+            Map function ``f`` over wrapped the wrapped object
+            returning a new ``HWrap`` instance.
 
         :param f: Mapping function.
-        :returns: A new instance.
+        :returns: New instance.
 
         """
         return HWrap(f(self._item))
 
     def bind[U](self, f: Callable[[T], 'HWrap[U]']) -> 'HWrap[U]':
-        """Flatmap the ``Wrap`` with function ``f``.
+        """
+        .. admonition:: Bind
+
+            Flatmap ``Box`` with function ``f``.
 
         :param f: Binding function.
-        :returns: A new instance.
+        :returns: New instance.
 
         """
         return f(self._item)

{pythonic_fp_gadgets-4.0.2.dist-info → pythonic_fp_gadgets-4.0.4.dist-info}/METADATA

@@ -1,24 +1,24 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 4.0.2
+Version: 4.0.4
 Summary: Gadgets
 Keywords: gadgets
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13
 Description-Content-Type: text/x-rst
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Requires-Dist: pythonic-fp-circulararray>=6.0.1 ; extra == "test"
+Requires-Dist: pythonic-fp-circulararray>=6.0.4 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-gadgets/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/gadgets/development/build/html/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/projects/gadgets.html
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-gadgets
 Provides-Extra: test
 
@@ -27,7 +27,7 @@ Pythonic FP - Gadgets
 
 PyPI project
 `pythonic-fp-gadgets
-<https://pypi.org/project/pythonic-fp>`_.
+<https://pypi.org/project/pythonic-fp-gadgets>`_.
 
 Library of simple, but useful, classes and functions with no dependencies
 outside the Python Standard Library.
@@ -35,24 +35,26 @@ outside the Python Standard Library.
 - Gadgets
 
   - single item box
+  - immutable wrapped (hashable) references
   - function returning iterator of its arguments
   - function to find the latest common ancestor of two classes
+  - sentinel values
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
-Documentation for this project is hosted on
+Documentation and other links for this project are hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/gadgets>`_.
+<https://grscheller.github.io/pythonic-fp/projects/gadgets.html>`_.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2025-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.
 

pythonic_fp_gadgets-4.0.4.dist-info/RECORD

@@ -0,0 +1,17 @@
+pythonic_fp/gadgets/__init__.py,sha256=-pgzuWq-DTORXvy8JDQpnNPhQou85oiySH2-gArNeWc,2806
+pythonic_fp/gadgets/__init__.pyi,sha256=-O921ioE28UPnDm_EL928vl6dDxhrfXHBQenusBo1_o,224
+pythonic_fp/gadgets/box.py,sha256=Dx5wF3x9LyUs5MHjvHP6yTM05f4ojHPqqzfjuXJOo8I,6580
+pythonic_fp/gadgets/box.pyi,sha256=UkJBY8Xiv4oe70Q3bhJL1jGHwYmFWwkTIdxvf2zR3v4,837
+pythonic_fp/gadgets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/gadgets/wrap.py,sha256=tAnG7P3EYl_1-CH2cs7IfY-0h4LET1LEIjmMo26OzCg,5388
+pythonic_fp/gadgets/wrap.pyi,sha256=TRbBph_517VNCKchwU-pdtPCn73c09gq8EchDFM7Uyo,868
+pythonic_fp/gadgets/sentinels/__init__.py,sha256=Xh63-GTwiqqcBqs5OEYBSiLXuWtq_CVHfUz0mKO_2H0,775
+pythonic_fp/gadgets/sentinels/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/gadgets/sentinels/flavored.py,sha256=LPmA-XOadcN5gJgxxo2prSnwRvq8bJ7o0Ae2_Y70Au0,2774
+pythonic_fp/gadgets/sentinels/flavored.pyi,sha256=K3YSyXLyylPII2ahRP0olhzLJruOeR73TFJDC6rCUwk,212
+pythonic_fp/gadgets/sentinels/novalue.py,sha256=gaQNm1TRtphbmWgDV8O0sblH7eU2M-Zymu_B67mwsJ8,6097
+pythonic_fp/gadgets/sentinels/novalue.pyi,sha256=1_iUI6FEwYma8P4XXVCb6CKhSYmfq53S8dLmiwNtJw4,244
+pythonic_fp_gadgets-4.0.4.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+pythonic_fp_gadgets-4.0.4.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_gadgets-4.0.4.dist-info/METADATA,sha256=SbxLXeCZA7LOtg3Q_mpBPlux1FR6-shkI9S2tutdVgk,1895
+pythonic_fp_gadgets-4.0.4.dist-info/RECORD,,

pythonic_fp_gadgets-4.0.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-pythonic_fp/gadgets/__init__.py,sha256=iEm1j8DIchgQvH4Tom6IyMeYz8i3LSAXBBBtz_gPykE,2673
-pythonic_fp/gadgets/__init__.pyi,sha256=cAf10WX2ZHMs-Tf93mImmDdZw7lNEmwjorkiVF04s_E,224
-pythonic_fp/gadgets/box.py,sha256=cmHe2kZhEMNtH51xlpdyd68SV-bBXxC6gRH8N0W6TqE,5443
-pythonic_fp/gadgets/box.pyi,sha256=UkJBY8Xiv4oe70Q3bhJL1jGHwYmFWwkTIdxvf2zR3v4,837
-pythonic_fp/gadgets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/gadgets/wrap.py,sha256=x3mvawiRh9G3vMq3ub5Va6qBJgKcvkCKvWeR6pWrJBw,3929
-pythonic_fp/gadgets/wrap.pyi,sha256=TRbBph_517VNCKchwU-pdtPCn73c09gq8EchDFM7Uyo,868
-pythonic_fp/gadgets/sentinels/__init__.py,sha256=81T-HGQ9BgXj57PO_pduo8MpSQpRgZwT8LIXwODhHkI,724
-pythonic_fp/gadgets/sentinels/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/gadgets/sentinels/flavored.py,sha256=sXgjhBPHEulH9C3Yc09PwAPDscfRH2vKj5JldgS6Sak,2260
-pythonic_fp/gadgets/sentinels/flavored.pyi,sha256=K3YSyXLyylPII2ahRP0olhzLJruOeR73TFJDC6rCUwk,212
-pythonic_fp/gadgets/sentinels/novalue.py,sha256=UbyQ4AVTdM2flLmF2WE0sh7_dErPQiTeM8U6GdWaHN4,3602
-pythonic_fp/gadgets/sentinels/novalue.pyi,sha256=zhZdePpWoQ3ZXOq7xQWGR0A4W_XzasdBQKcoywXZEZI,173
-pythonic_fp_gadgets-4.0.2.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-pythonic_fp_gadgets-4.0.2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_gadgets-4.0.2.dist-info/METADATA,sha256=GsyqIcxiofODEI34GKxzySI-FBv-pkwxaEhnTfZzcOs,1815
-pythonic_fp_gadgets-4.0.2.dist-info/RECORD,,