pythonic-fp-gadgets 4.0.4__tar.gz → 4.1.0__tar.gz

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/.github/workflows/static.yml

@@ -6,8 +6,8 @@ on:
   workflow_dispatch:
 
 env:
-  RELEASE: '4.0.4'
-  DEVEL: '4.0.4'
+  RELEASE: '4.1.0'
+  DEVEL: '4.1.1'
   PYTHON: '3.14'
 
 permissions:

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/CHANGELOG.rst

@@ -17,17 +17,24 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
+PyPI 4.1.0 - 2026-05-12
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- documentation now in maintenance mode
+- development status now "4 - Beta"
+- added a few missing methods
+
 PyPI 4.0.4 - 2026-04-26
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Much docstring work for sentinels. Need to push now going into
-documentation maintenance to fix broken links on PyPI.
+Much docstring work for sentinels. Need to push now to fix
+broken links on PyPI before going into documentation maintenance.
 
 Development Status Reappraisal - 2026-05-05
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Maintainer appraised the Development Status for
-pythonic-fp-gadgets to be ``"3 - Alpha"``.
+pythonic-fp-gadgets to be "3 - Alpha".
 
 PyPI 4.0.3 - 2026-04-26
 ~~~~~~~~~~~~~~~~~~~~~~~

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 4.0.4
+Version: 4.1.0
 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 :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/docs/Makefile

@@ -5,8 +5,8 @@
 #  - later needs to agree with pyproject.toml
 PROJECT_NAME = Gadgets
 PYPI_NAME = gadgets
-RELEASE_VERSION = 4.0.4
-DEVEL_VERSION = 4.0.4
+RELEASE_VERSION = 4.1.0
+DEVEL_VERSION = 4.1.1
 CUSTOM_VERSION = 0.0.0
 
 SPHINXOPTS ?=

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "pythonic-fp-gadgets"
-version = "4.0.4"
+version = "4.1.0"
 readme = "README.rst"
 requires-python = ">=3.13"
 authors = [
@@ -14,7 +14,7 @@ keywords = [
   "gadgets",
 ]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Framework :: Pytest",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/src/pythonic_fp/gadgets/__init__.py

@@ -59,6 +59,7 @@ def first_common_ancestor(cls1: type, cls2: type) -> type:
 
             This happens frequently when the function is given
             Python builtin types or in multiple inheritance situations.
+
     """
     if issubclass(cls1, cls2):
         return cls2

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.1.0}/src/pythonic_fp/gadgets/box.py

@@ -52,7 +52,7 @@ class Box[T]:
 
             Initialize ``Box`` with 0 or 1 items.
 
-        :param item: An optional initial ``item`` for the ``Box``.
+            :param item: An optional initial item for the ``Box``.
 
         """
         self._item = item
@@ -68,9 +68,9 @@ class Box[T]:
 
     def __iter__(self) -> Iterator[T]:
         """
-        .. admonition:: Iterability
+        .. admonition:: iter
 
-            Iterates boxed item.
+            :yields: Boxed item.
 
         """
         if self:
@@ -83,7 +83,7 @@ class Box[T]:
             - 1 if ``Box`` contains an item
             - 0 if ``Box`` is empty
 
-        :returns: The number of items currently in the ``Box``.
+            :returns: The number of items currently in the ``Box``.
 
         """
         return 1 if self else 0
@@ -94,10 +94,10 @@ class Box[T]:
 
             Efficiently compare ``Box`` to another object.
 
-        :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``.
+            :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)):
@@ -111,19 +111,35 @@ class Box[T]:
 
     def __repr__(self) -> str:
         """
-        .. admonition:: Representation string
+        .. 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``. 
+            :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
@@ -136,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:
@@ -157,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:
@@ -174,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:
@@ -200,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:
@@ -219,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:
@@ -233,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-4.1.0/src/pythonic_fp/gadgets/wrap.py

@@ -0,0 +1,270 @@
+# 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+__all__ = ['Wrap', 'HWrap']
+
+from collections.abc import Callable, Iterator, Hashable
+
+
+class Wrap[T]():
+    """
+    .. admonition:: Wrap
+
+        Immutablely wrap exactly one item.
+
+        .. tip::
+
+            ``Wrap`` objects are matchable.
+
+    """
+    __slots__ = ('_item',)
+    __match_args__ = ('_item',)
+
+    def __init__(self, item: T) -> None:
+        """
+        .. admonition:: init
+
+            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 __len__(self) -> int:
+        """
+        .. admonition:: len
+
+            Wrapped items always contain just one item.
+
+            :returns: 1
+
+        """
+        return 1
+
+    def __iter__(self) -> Iterator[T]:
+        """
+        .. admonition:: iter
+
+            :yields: A reference to the wrapped item.
+
+        """
+        if self:
+            yield self._item
+
+    def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            Compare ``Wrap`` to another object.
+
+            :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)):
+            return False
+
+        if self._item is other._item:
+            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
+
+            Map function ``f`` over contents.
+
+            :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
+
+            Flatmap wrapped object with function ``f``.
+
+            :param f: Binding function.
+            :returns: New instance.
+
+        """
+        return f(self._item)
+
+
+class HWrap[T: Hashable](Hashable):
+    """
+    .. admonition:: HWrap
+
+        Immutablely wrap exactly one hashable item.
+
+        .. tip::
+
+            ``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:
+        return self._hash
+
+    def __bool__(self) -> 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
+
+            :yields: A reference to the wrapped item.
+
+        """
+        if self:
+            yield self._item
+
+    def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            Compare ``HWrap`` to another object.
+
+            :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)):
+            return False
+
+        if self._hash != other._hash:
+            return False
+        if self._item is other._item:
+            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
+
+            Map function ``f`` over wrapped the wrapped object
+            returning a new ``HWrap`` 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
+
+            Flatmap ``Box`` with function ``f``.
+
+            :param f: Binding function.
+            :returns: New instance.
+
+        """
+        return f(self._item)

pythonic_fp_gadgets-4.0.4/src/pythonic_fp/gadgets/wrap.py

@@ -1,219 +0,0 @@
-# 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.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# 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']
-
-from collections.abc import Callable, Iterator, Hashable
-
-
-class Wrap[T]():
-    """
-    .. admonition:: Wrap object
-
-        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 __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:
-        """
-        .. 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
-
-        if self._item is other._item:
-            return True
-        return self._item == other._item
-
-    def map[U](self, f: Callable[[T], U]) -> 'Wrap[U]':
-        """
-        .. admonition:: Map
-
-            Map function ``f`` over contents.
-
-        Map function ``f`` over contents.
-
-        :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
-
-            Flatmap wrapped object with function ``f``.
-
-        :param f: Binding function.
-        :returns: New instance.
-
-        """
-        return f(self._item)
-
-
-class HWrap[T: Hashable](Hashable):
-    """
-    .. admonition:: Wrap hashable object
-
-        Immutablely wrap exactly one value of a
-        given hashable type. ``HWrap`` objects can
-        be used in Python match statements.
-
-        .. tip::
-
-            ``HWrap`` objects are hashable.
-
-    """
-
-    __slots__ = ('_item', '_hash')
-    __match_args__ = ('_item',)
-
-    def __init__(self, item: T) -> None:
-        self._item, self._hash = item, hash(item)
-
-    def __hash__(self) -> int:
-        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
-
-    def __repr__(self) -> str:
-        return 'Wrap(' + repr(self._item) + ')'
-
-    def __eq__(self, other: object) -> bool:
-        """
-        .. admonition:: Equality comparison
-
-            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
-
-        if self._hash != other._hash:
-            return False
-        if self._item is other._item:
-            return True
-        return self._item == other._item
-
-    def map[U](self, f: Callable[[T], U]) -> 'HWrap[U]':
-        """
-        .. admonition:: Map
-
-            Map function ``f`` over wrapped the wrapped object
-            returning a new ``HWrap`` 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
-
-            Flatmap ``Box`` with function ``f``.
-
-        :param f: Binding function.
-        :returns: New instance.
-
-        """
-        return f(self._item)