pythonic-fp-gadgets 4.0.3__py3-none-any.whl → 4.1.0__py3-none-any.whl

pythonic_fp/gadgets/__init__.py

@@ -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 at all.
+
+      - No pythonic_fp dependencies at all.
 
 """
 
@@ -42,22 +43,22 @@ def first_common_ancestor(cls1: type, cls2: type) -> type:
         Find the least upper bound in the inheritance graph
         of two classes.
 
-    .. warning::
+        :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``.
 
-        This function can fail with a TypeError. Some error messages
-        seen are
+        .. warning::
 
-        - multiple bases have instance lay-out conflict
-        - type 'bool' is not an acceptable base type
+            This function can fail with a TypeError. Some error messages
+            seen are
 
-        This happens frequently when the function is given
-        Python builtin types or in multiple inheritance situations.
+            - multiple bases have instance lay-out conflict
+            - type 'bool' is not an acceptable base type
 
-    :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``.
+            This happens frequently when the function is given
+            Python builtin types or in multiple inheritance situations.
 
     """
     if issubclass(cls1, cls2):
@@ -77,12 +78,12 @@ def iterate_over_arguments[A](*args: A) -> Iterator[A]:
 
         Function returning an iterator over its arguments.
 
-    .. note::
+        :param args: Objects to iterate over.
+        :returns: An iterator of the function's arguments.
 
-        Does not create a Python object to iterate over.
+        .. 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

@@ -11,28 +11,12 @@
 # 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 box
-
-    Containers holding at most one item of a given type.
-
-    .. tip::
-
-        Objects of the ``Box`` type
-
-        - Are truthy if not empty.
-        - Can be combined with other iterators before being filled.
-        - Can be used like a promise.
-        - Threadsafe
-        - Can be used in Python match statements.
-
-"""
-
-__all__ = ['Box']
 
 from collections.abc import Callable, Iterator
 from typing import cast, Final, overload
 
+__all__ = ['Box']
+
 type _Sentinel = object
 _sentinel: Final[_Sentinel] = object()
 
@@ -43,6 +27,16 @@ class Box[T]:
 
         Container holding at most one item of a given type.
 
+        .. tip::
+
+            Objects of the ``Box`` type
+
+            - 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',)
     __match_args__ = ('_item',)
@@ -54,24 +48,44 @@ class Box[T]:
 
     def __init__(self, item: T | _Sentinel = _sentinel) -> None:
         """
-        :param item: An optional initial ``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:: iter
 
-    def __repr__(self) -> str:
+            :yields: 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:
@@ -80,10 +94,10 @@ class Box[T]:
 
             Efficiently compare ``Box`` to another object.
 
-        :param other: The object to be compared with,
-        :returns: ``True`` if ``other`` is of type Box and contains
-                  an object which compares as equal to the object
-                  contained in the ``Box``, otherwise ``False``.
+            :param other: The object to be compared.
+            :returns: ``True`` if ``other`` is another ``Box`` containing
+                      an object which compares as equal to the item
+                      contained in the ``Box``, otherwise ``False``.
 
         """
         if not isinstance(other, type(self)):
@@ -95,6 +109,37 @@ class Box[T]:
             return True
         return False
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr 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()'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Construct string 'Box()' if empty, otherwise 'Box(item_str)'
+            where ``item_str = str(item)`` for the currently contained
+            item. 
+
+            :returns: A user meaningful string to represent the current
+                      state of the ``Box``. 
+
+        """
+        if self:
+            return 'Box(' + str(self._item) + ')'
+        return 'Box()'
+
     @overload
     def get(self) -> T: ...
     @overload
@@ -107,12 +152,12 @@ class Box[T]:
             Return the boxed item, if it exists, otherwise
             an alternate item, if given.
 
-        :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.
-        :raises ValueError: When the ``alt`` item is not provided
-                            but needed.
+            :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.
+            :raises ValueError: When the ``alt`` item is not provided
+                                but needed.
 
         """
         if self._item is not _sentinel:
@@ -128,8 +173,8 @@ class Box[T]:
 
             Pop item from ``Box`` if not empty.
 
-        :returns: The item contained in the ``Box``.
-        :raises ValueError: If Box is empty.
+            :returns: The item contained in the ``Box``.
+            :raises ValueError: If Box is empty.
 
         """
         if self._item is _sentinel:
@@ -145,8 +190,8 @@ class Box[T]:
 
             Push an item into ``Box`` if empty.
 
-        :param item: Item to push into the empty ``Box``.
-        :raises ValueError: If ``Box`` is not empty.
+            :param item: Item to push into the empty ``Box``.
+            :raises ValueError: If ``Box`` is not empty.
 
         """
         if self._item is _sentinel:
@@ -171,9 +216,9 @@ class Box[T]:
 
             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.
+            :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:
@@ -190,8 +235,8 @@ class Box[T]:
             Map function ``f`` over contents. We need to return a new
             instance since the type of Box can change.
 
-        :param f: Mapping function.
-        :returns: New instance.
+            :param f: Mapping function.
+            :returns: New instance.
 
         """
         if self._item is _sentinel:
@@ -204,8 +249,8 @@ class Box[T]:
 
             Flatmap ``Box`` with function ``f``.
 
-        :param f: Binding function.
-        :returns: New instance.
+            :param f: Binding function.
+            :returns: New instance.
 
         """
         if self._item is _sentinel:

pythonic_fp/gadgets/sentinels/__init__.py

@@ -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-2026 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

@@ -12,30 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-.. admonition:: When different flavors of the truth are needed.
-
-    Sentinel values labeled by different (hashable) flavors.
-    Threadsafe.
-
-.. tip::
-
-    Can be compared using ``==`` and ``!=``. A flavored sentinel
-    value always equals itself and never equals anything else,
-    especially other flavored sentinel values.
-
-.. tip::
-
-    Useful for union types where ``Sentinel[H]`` is one of the
-    types making up the union.
-
-.. tip::
-
-    To ensure that reference equality is used, put the known
-    sentinel value first in the comparison.
-
-"""
-
 import threading
 from typing import ClassVar, final, Hashable
 
@@ -44,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:
@@ -58,25 +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 flavor(self) -> H:
+    def __str__(self) -> str:
         """
-        .. admonition:: Get flavor
+        .. admonition:: user string
+
+            Construct string 'Sentinel(flavor)' where the flavor
+            is displayed with ``str()``.
 
-            Get the sentinel's flavor, a hashable
-            value of type ``H``.
+            :returns: A string meaningful to an end user.
+
+        """
+        return "Sentinel('" + str(self._flavor) + "')"
+
+    def flavor(self) -> H:
+        """
+        .. admonition:: get flavor
 
-        :returns: The sentinel's flavor.
+            :returns: The sentinel's flavor.
 
         """
         return self._flavor

pythonic_fp/gadgets/sentinels/novalue.py

@@ -12,117 +12,176 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-.. admonition:: Missing value.
+import threading
+from typing import ClassVar, final
 
-    Singleton class representing an actually,
-    not potentially, missing value.
+__all__ = ['NoValue']
 
-    ``NoValue()`` is a singleton object representing a missing value.
 
-    While ``None`` and ``()`` are frequently used as sentinel values,
-    I prefer to think of them as
+@final
+class NoValue:
+    """
+    .. admonition:: missing value
 
-    - ``None``: Returns, or returned, no values.
-    - ``()``: An empty, possibly typed, iterable collection.
+        Singleton class representing an actual, not
+        potential, missing value.
 
-.. important::
+        While ``None`` and ``()`` are frequently used as sentinel values,
+        I prefer to think of them as
 
-    Given variables
+        - ``None`` as returns, or returned, no values.
+        - ``()`` as an empty, possibly typed, iterable collection.
 
-    .. code:: python
+        .. important::
 
-        x: int | NoValue
-        y: int | NoValue
+            Given variables
 
-    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?
+            .. code:: python
 
-    .. table:: ``x == y``
+                x: int | NoValue
+                y: int | NoValue
 
-        +-----------+-----------+--------+--------+
-        |    x∖y    | NoValue() | 42     | 57     |
-        +===========+===========+========+========+
-        | NoValue() | false     | false  | false  |
-        +-----------+-----------+--------+--------+
-        | 42        | false     | true   | false  |
-        +-----------+-----------+--------+--------+
-        | 57        | false     | false  | true   |
-        +-----------+-----------+--------+--------+
+            Equality between ``x`` and ``y`` means both values exist
+            and compare as equal.
 
-    Similarly for not equals.
+            .. table:: ``x == y``
 
-    .. table:: ``x != y``:wq
+                +-------------------+-------------------+------------+------------+
+                |                   |                   |            |            |
+                +===================+===================+============+============+
+                |                   | ``y = NoValue()`` | ``y = 42`` | ``y = 57`` |
+                +-------------------+-------------------+------------+------------+
+                | ``x = NoValue()`` | ``False``         | ``False``  | ``False``  |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 42``        | ``False``         | ``True``   | ``False``  |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 57``        | ``False``         | ``False``  | ``True``   |
+                +-------------------+-------------------+------------+------------+
 
-        +-----------+-----------+--------+--------+
-        |    x∖y    | NoValue() | 42     | 57     |
-        +===========+===========+========+========+
-        | NoValue() | false     | false  | false  |
-        +-----------+-----------+--------+--------+
-        | 42        | false     | false  | true   |
-        +-----------+-----------+--------+--------+
-        | 57        | false     | true   | false  |
-        +-----------+-----------+--------+--------+
+            .. table:: ``x != y``
 
-.. warning::
+                +-------------------+-------------------+------------+------------+
+                |                   |                   |            |            |
+                +===================+===================+============+============+
+                |                   | ``y = NoValue()`` | ``y = 42`` | ``y = 57`` |
+                +-------------------+-------------------+------------+------------+
+                | ``x = NoValue()`` | ``False``         | ``False``  | ``False``  |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 42``        | ``False``         | ``False``  | ``True``   |
+                +-------------------+-------------------+------------+------------+
+                | ``x = 57``        | ``False``         | ``True``   | ``False``  |
+                +-------------------+-------------------+------------+------------+
 
-    Only use ``==`` or ``!=`` in value comparisons. To directly
-    identity the ``NoValue`` singleton, use ``is`` and ``is not``
-    instead.
+            .. warning::
 
-.. note::
+                - use ``==`` or ``!=`` only in value comparisons
+                - use ``is`` and ``is not`` to identity the ``NoValue()``
+                  singleton itself
 
-    Threadsafe.
+        .. tip::
 
-.. tip::
+            Use in a union type when creating "optional" arguments
+            to functions and methods.
 
-    Use as a hidden implementation detail when creating "optional"
-    arguments to functions and methods.
+            To help ensure the abstraction stays a hidden implementation
+            detail and does not leak out into user code,
 
-    To help ensure the abstraction does not leak,
+            - Do not export the sentinel value.
 
-    - 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
+              - A new reference can always be generated via ``NoValue()``.
 
-__all__ = ['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

@@ -11,15 +11,6 @@
 # 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']
 
@@ -28,9 +19,13 @@ from collections.abc import Callable, Iterator, Hashable
 
 class Wrap[T]():
     """
-    .. admonition:: Wrap object
+    .. admonition:: Wrap
+
+        Immutablely wrap exactly one item.
 
-        Immutablely wrap exactly one value of a given type.
+        .. tip::
+
+            ``Wrap`` objects are matchable.
 
     """
     __slots__ = ('_item',)
@@ -38,43 +33,55 @@ class Wrap[T]():
 
     def __init__(self, item: T) -> None:
         """
-        :param item: Item to be wrapped.
+        .. admonition:: init
+
+            Initialize ``Wrap`` with 1 required item.
+
+            :param item: Item to be wrapped.
 
         """
         self._item = item
 
     def __bool__(self) -> bool:
         """
-        .. admonition:: Bool
+        .. admonition:: bool
 
             Truthiness same as wrapped object.
 
         """
         return bool(self._item)
 
+    def __len__(self) -> int:
+        """
+        .. admonition:: len
+
+            Wrapped items always contain just one item.
+
+            :returns: 1
+
+        """
+        return 1
+
     def __iter__(self) -> Iterator[T]:
         """
-        .. admonition:: Iter
+        .. admonition:: iter
 
-            Iterable, iterates wrapped item.
+            :yields: A reference to the wrapped item.
 
         """
         if self:
             yield self._item
 
-    def __repr__(self) -> str:
-        return 'Wrap(' + repr(self._item) + ')'
-
     def __eq__(self, other: object) -> bool:
         """
-        .. admonition:: Equality comparison
+        .. admonition:: equality comparison
 
-            Efficiently compare ``Wrap`` to another object.
+            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``.
+            :param other: Object to be compared.
+            :returns: ``True`` if ``other`` is of type Wrap and wraps
+                      an item which compares as equal to the wrapped
+                      item, otherwise ``False``.
 
         """
         if not isinstance(other, type(self)):
@@ -84,28 +91,50 @@ class Wrap[T]():
             return True
         return self._item == other._item
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            Construct string 'Wrap(item_str)'
+            where ``item_str = repr(item)`` for the contained item. 
+
+            :returns: A string to reproduce of the wrapped item. 
+
+        """
+        return 'Wrap(' + repr(self._item) + ')'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Construct string 'Wrap(item_str)'
+            where ``item_str = str(item)`` for the contained item. 
+
+            :returns: A string meaningful to an end user.
+
+        """
+        return 'Wrap(' + str(self._item) + ')'
+
     def map[U](self, f: Callable[[T], U]) -> 'Wrap[U]':
         """
-        .. admonition:: Map
+        .. admonition:: map
 
             Map function ``f`` over contents.
 
-        Map function ``f`` over contents.
-
-        :param f: Mapping function.
-        :returns: New instance.
+            :param f: Mapping function.
+            :returns: New instance.
 
         """
         return Wrap(f(self._item))
 
     def bind[U](self, f: Callable[[T], 'Wrap[U]']) -> 'Wrap[U]':
         """
-        .. admonition:: Bind
+        .. admonition:: bind
 
             Flatmap wrapped object with function ``f``.
 
-        :param f: Binding function.
-        :returns: New instance.
+            :param f: Binding function.
+            :returns: New instance.
 
         """
         return f(self._item)
@@ -113,23 +142,28 @@ class Wrap[T]():
 
 class HWrap[T: Hashable](Hashable):
     """
-    .. admonition:: Wrap hashable object
+    .. admonition:: HWrap
 
-        Immutablely wrap exactly one value of a given hashable type.
+        Immutablely wrap exactly one hashable item.
 
-    .. tip::
+        .. tip::
 
-        ``HWrap`` objects can be used in Python match statements.
-
-    .. tip::
-
-        ``HWrap`` objects are hashable.
+            ``HWrap`` objects are hashable and matchable.
 
     """
+
     __slots__ = ('_item', '_hash')
     __match_args__ = ('_item',)
 
     def __init__(self, item: T) -> None:
+        """
+        .. admonition:: init
+
+            Initialize ``HWrap`` with 1 required item.
+
+            :param item: Item to be wrapped.
+
+        """
         self._item, self._hash = item, hash(item)
 
     def __hash__(self) -> int:
@@ -137,36 +171,44 @@ class HWrap[T: Hashable](Hashable):
 
     def __bool__(self) -> bool:
         """
-        .. admonition:: Bool
+        .. admonition:: bool
 
             Truthiness same as wrapped object.
 
         """
         return bool(self._item)
 
+    def __len__(self) -> int:
+        """
+        .. admonition:: len
+
+            HWrapped items always contain just one item.
+
+            :returns: 1
+
+        """
+        return 1
+
     def __iter__(self) -> Iterator[T]:
         """
-        .. admonition:: Iter
+        .. admonition:: iter
 
-            Iterable, iterates wrapped item.
+            :yields: A reference to the wrapped item.
 
         """
         if self:
             yield self._item
 
-    def __repr__(self) -> str:
-        return 'Wrap(' + repr(self._item) + ')'
-
     def __eq__(self, other: object) -> bool:
         """
-        .. admonition:: Equality comparison
+        .. admonition:: equality comparison
 
-            Efficiently compare to another object.
+            Compare ``HWrap`` 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``.
+            :param other: Object to be compared.
+            :returns: ``True`` if ``other`` is of type HWrap and wraps
+                      an item which compares as equal to the wrapped
+                      item, otherwise ``False``.
 
         """
         if not isinstance(other, type(self)):
@@ -178,27 +220,51 @@ class HWrap[T: Hashable](Hashable):
             return True
         return self._item == other._item
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            Construct string 'HWrap(item_str)'
+            where ``item_str = repr(item)`` for the contained item. 
+
+            :returns: A string to reproduce of the wrapped object. 
+
+        """
+        return 'Wrap(' + repr(self._item) + ')'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Construct string 'HWrap(item_str)'
+            where ``item_str = str(item)`` for the contained item. 
+
+            :returns: A string meaningful to an end user.
+
+        """
+        return 'Wrap(' + str(self._item) + ')'
+
     def map[U](self, f: Callable[[T], U]) -> 'HWrap[U]':
         """
-        .. admonition:: Map
+        .. admonition:: map
 
             Map function ``f`` over wrapped the wrapped object
             returning a new ``HWrap`` instance.
 
-        :param f: Mapping function.
-        :returns: New instance.
+            :param f: Mapping function.
+            :returns: New instance.
 
         """
         return HWrap(f(self._item))
 
     def bind[U](self, f: Callable[[T], 'HWrap[U]']) -> 'HWrap[U]':
         """
-        .. admonition:: Bind
+        .. admonition:: bind
 
             Flatmap ``Box`` with function ``f``.
 
-        :param f: Binding function.
-        :returns: New instance.
+            :param f: Binding function.
+            :returns: New instance.
 
         """
         return f(self._item)

{pythonic_fp_gadgets-4.0.3.dist-info → pythonic_fp_gadgets-4.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 4.0.3
+Version: 4.1.0
 Summary: Gadgets
 Keywords: gadgets
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
@@ -17,8 +17,8 @@ License-File: LICENSE
 Requires-Dist: pytest>=8.4.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/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/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
 
@@ -35,22 +35,22 @@ outside the Python Standard Library.
 - Gadgets
 
   - single item box
-  - wrapped (hashable) references
+  - 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/homepage/html/>`_
+<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
 ---------------------

pythonic_fp_gadgets-4.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pythonic_fp/gadgets/__init__.py,sha256=zwRgxkaQYUbqjR-kX8pQeuPqipCB1bllVOEVBtGXl6I,2807
+pythonic_fp/gadgets/__init__.pyi,sha256=-O921ioE28UPnDm_EL928vl6dDxhrfXHBQenusBo1_o,224
+pythonic_fp/gadgets/box.py,sha256=gcW9mg-QCjc2lLTcOeqYJK0NAkHAbFs1JxhFjVTW1uQ,7115
+pythonic_fp/gadgets/box.pyi,sha256=UkJBY8Xiv4oe70Q3bhJL1jGHwYmFWwkTIdxvf2zR3v4,837
+pythonic_fp/gadgets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/gadgets/wrap.py,sha256=Bdi-0rg7x37NWd0ciRi_IeDrsmlKQHJOMY9HcCnKt9M,6465
+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.1.0.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+pythonic_fp_gadgets-4.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_gadgets-4.1.0.dist-info/METADATA,sha256=eI5gy-KQSFKzOW1E18RF8lzF7EQcEcF-WWWFEeX63Ko,1894
+pythonic_fp_gadgets-4.1.0.dist-info/RECORD,,

pythonic_fp_gadgets-4.0.3.dist-info/RECORD

@@ -1,17 +0,0 @@
-pythonic_fp/gadgets/__init__.py,sha256=29fNYn8LLhCUfvZ_vcofSoGhs9_Hw95cPF3sd0G1z9M,2739
-pythonic_fp/gadgets/__init__.pyi,sha256=cAf10WX2ZHMs-Tf93mImmDdZw7lNEmwjorkiVF04s_E,224
-pythonic_fp/gadgets/box.py,sha256=2PL0wkimRwgsL15aTkB2QTo4B40IY6G0lCo0Esa0CTU,5860
-pythonic_fp/gadgets/box.pyi,sha256=UkJBY8Xiv4oe70Q3bhJL1jGHwYmFWwkTIdxvf2zR3v4,837
-pythonic_fp/gadgets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/gadgets/wrap.py,sha256=EVhp115DcokaBa-0xN3CN3Qlr4vkHvEZQIPuMYYxHas,4950
-pythonic_fp/gadgets/wrap.pyi,sha256=TRbBph_517VNCKchwU-pdtPCn73c09gq8EchDFM7Uyo,868
-pythonic_fp/gadgets/sentinels/__init__.py,sha256=WsGXds578j1y7FsLEGer59P1c8EItUBTp60cuA0T56E,724
-pythonic_fp/gadgets/sentinels/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/gadgets/sentinels/flavored.py,sha256=W33020r3U8jxIDdJDaa-xE7o4cI1NY0bLZi8puIUBqA,2353
-pythonic_fp/gadgets/sentinels/flavored.pyi,sha256=K3YSyXLyylPII2ahRP0olhzLJruOeR73TFJDC6rCUwk,212
-pythonic_fp/gadgets/sentinels/novalue.py,sha256=9wya9NBDQzfr2rxwrCd7uh74Trm4iVsK53UAUZo5Iyk,3613
-pythonic_fp/gadgets/sentinels/novalue.pyi,sha256=zhZdePpWoQ3ZXOq7xQWGR0A4W_XzasdBQKcoywXZEZI,173
-pythonic_fp_gadgets-4.0.3.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-pythonic_fp_gadgets-4.0.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_gadgets-4.0.3.dist-info/METADATA,sha256=z6LP-dUh7AgGHq-TTbn3qS0QyIDc-5GNohGM23QXMzU,1868
-pythonic_fp_gadgets-4.0.3.dist-info/RECORD,,