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

pythonic_fp/gadgets/__init__.py

@@ -13,44 +13,28 @@
 # limitations under the License.
 
 """
-**Module level function names.**
+Gadgets
+-------
 
-========================== ================================================
-Function                   Description                                     
-========================== ================================================
-``first_common_ancestor``  Find least common base class in a type hierarchy
-``iterate_over_arguments`` Return an iterator over the function's arguments
-========================== ================================================
+.. 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.
 
 """
 
 from collections.abc import Iterator
 from inspect import getmro
 
-__all__ = ['iterate_over_arguments', 'first_common_ancestor']
+__all__ = ['first_common_ancestor', 'iterate_over_arguments']
 
 __author__ = 'Geoffrey R. Scheller'
 __copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'
 
 
-def iterate_over_arguments[A](*args: A) -> Iterator[A]:
-    """Function returning an iterator of its arguments.
-
-    .. note::
-
-        Does not create an object to iterate over.
-
-        - well, not in the Python world
-        - maybe in the C world
-
-    :param args: Objects to iterate over.
-    :returns: An iterator of the arguments.
-
-    """
-    yield from args
-
-
 def first_common_ancestor(cls1: type, cls2: type) -> type:
     """Find the least upper bound in the inheritance graph
     of two classes.
@@ -69,7 +53,8 @@ def first_common_ancestor(cls1: type, cls2: type) -> 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 by ``inspect.getmro``.
+    :raises TypeError: Raised when no common ancestor or not
+                       caught when raised by ``inspect.getmro``.
 
     """
     if issubclass(cls1, cls2):
@@ -81,3 +66,20 @@ def first_common_ancestor(cls1: type, cls2: type) -> type:
         if issubclass(cls1, common_ancestor) and issubclass(cls2, common_ancestor):
             return common_ancestor
     raise TypeError("latest_common_ancestor: no common ancestor found!!!")
+
+
+def iterate_over_arguments[A](*args: A) -> Iterator[A]:
+    """Function returning an iterator of its arguments.
+
+    .. note::
+
+        Does not create an object to iterate over.
+
+        - well, not in the Python world
+        - maybe in the C world
+
+    :param args: Objects to iterate over.
+    :returns: An iterator of the functions arguments.
+
+    """
+    yield from args

pythonic_fp/gadgets/box.py

@@ -47,7 +47,8 @@ class Box[T]:
 
     def __init__(self, item: T | _Sentinel = _sentinel) -> None:
         """
-        :param item: An "optional" initial contained ``item`` for the ``Box``.
+        :param item: An optional initial contained ``item``
+                     for the ``Box``.
         """
         self._item = item
 
@@ -67,6 +68,14 @@ class Box[T]:
         return 1 if self else 0
 
     def __eq__(self, other: object) -> bool:
+        """
+        Efficiently compare 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``.
+        """
         if not isinstance(other, type(self)):
             return False
 
@@ -82,11 +91,15 @@ class Box[T]:
     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.
+        """Return the contained item, if it exists, otherwise
+        an alternate item, if given.
 
-        :param alt: an "optional" item of type ``T`` to return if ``Box`` is empty
-        :returns: contents of ``Box``, or an alternate item if given and ``Box`` empty
-        :raises ValueError: when an ``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:
@@ -146,8 +159,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: a new instance
+        :param f: Mapping function.
+        :returns: A new instance.
 
         """
         if self._item is _sentinel:
@@ -157,8 +170,8 @@ class Box[T]:
     def bind[U](self, f: Callable[[T], 'Box[U]']) -> 'Box[U]':
         """Flatmap ``Box`` with function ``f``.
 
-        :param f: binding function
-        :returns: a new instance
+        :param f: Binding function.
+        :returns: A new instance.
 
         """
         if self._item is _sentinel:

pythonic_fp/gadgets/sentinels/flavored.py

@@ -13,7 +13,9 @@
 # limitations under the License.
 
 """
-**Sentinel values labeled by different (hashable) flavors.**
+.. admonition:: Sentinel values labeled by different (hashable) flavors.
+
+    When different flavors of the truth are needed.
 
 .. note::
 

pythonic_fp/gadgets/sentinels/novalue.py

@@ -13,9 +13,8 @@
 # limitations under the License.
 
 """
-**Singleton class representing an actually, not potentially, missing value.**
-
-.. note:
+.. admonition:: Singleton class representing an actually,
+                not potentially, missing value.
 
     ``NoValue()`` is a singleton object representing a missing value.
 
@@ -52,7 +51,7 @@
 
     Similarly for not equals.
 
-    .. table:: ``x != y``
+    .. table:: ``x != y``:wq
 
         +-----------+-----------+--------+--------+
         |    x∖y    | NoValue() | 42     | 57     |
@@ -113,12 +112,12 @@ class NoValue():
 
     def __eq__(self, other: object) -> bool:
         """
-        :returns: False
+        :returns: ``False``
         """
         return False
 
     def __ne__(self, other: object) -> bool:
         """
-        :returns: False
+        :returns: ``False``
         """
         return False

pythonic_fp/gadgets/wrap.py

@@ -42,6 +42,14 @@ class Wrap[T]():
         return 'Wrap(' + repr(self._item) + ')'
 
     def __eq__(self, other: object) -> bool:
+        """
+        Efficiently compare 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
 
@@ -73,7 +81,11 @@ class HWrap[T: Hashable](Hashable):
 
     .. tip::
 
-        ``Wrap`` objects can be used in Python match statements.
+        ``HWrap`` objects can be used in Python match statements.
+
+    .. tip::
+
+        ``HWrap`` objects are hashable..
 
     """
     __slots__ = ('_item', '_hash')
@@ -96,6 +108,14 @@ class HWrap[T: Hashable](Hashable):
         return 'Wrap(' + repr(self._item) + ')'
 
     def __eq__(self, other: object) -> bool:
+        """
+        Efficiently compare to another object.
+
+        :param other: The object to be compared with,
+        :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
 

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 4.0.0
-Summary: **Module level function names.**
+Version: 4.0.2
+Summary: Gadgets
 Keywords: gadgets
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Requires-Dist: pythonic-fp-circulararray>=6.0.0 ; extra == "test"
+Requires-Dist: pythonic-fp-circulararray>=6.0.1 ; 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/
@@ -33,9 +33,10 @@ Library of simple, but useful, classes and functions with no dependencies
 outside the Python Standard Library.
 
 - Gadgets
+
   - single item box
   - function returning iterator of its arguments
-  - find the latest common ancestor of two classes
+  - function to find the latest common ancestor of two classes
 
 Part of the
 `pythonic-fp

{pythonic_fp_gadgets-4.0.0.dist-info → pythonic_fp_gadgets-4.0.2.dist-info}/RECORD

@@ -1,17 +1,17 @@
-pythonic_fp/gadgets/__init__.py,sha256=PXZJRwsDkGrI2_B3nbwU4n3tzeSGONquV-_inWroxsg,2811
+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=aSR9V_PuAhjqQ8Vs7fj80zgirb8BWzkUFr1pWvSbBDc,4994
+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=5FonuzJ6E3SeUoneUoUsjM6x9COZUnyzWQHPKN45cRo,3259
+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=RMqDRmN_ImbRlf_Yaqj7jwnOc6YBeEdAfi8xGCyw1xs,2195
+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=RA5foyWFgSHCpaJPJ0N0Td7cldLEbwX_bzkTgs_ZW-o,3573
+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.0.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-pythonic_fp_gadgets-4.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_gadgets-4.0.0.dist-info/METADATA,sha256=sbyH2GplSHaJ52be21JwZasacpNr5v2bG72MIvWQMVA,1827
-pythonic_fp_gadgets-4.0.0.dist-info/RECORD,,
+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,,