pythonic-fp-gadgets 3.1.0__tar.gz → 4.0.0__tar.gz

{pythonic_fp_gadgets-3.1.0 → pythonic_fp_gadgets-4.0.0}/CHANGELOG.rst

@@ -17,6 +17,15 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
+PyPI v4.0.0 - TBD
+~~~~~~~~~~~~~~~~~
+
+Move functions out of their own packages to __init__.py (2025-10-13).
+
+- latest_common_ancestor.lca -> first_common_ancestor
+- iterate_arguments.ita -> iterate_over_arguments
+
+
 PyPI v3.0.1 - 2025-09-09
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

{pythonic_fp_gadgets-3.1.0 → pythonic_fp_gadgets-4.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 3.1.0
-Summary: Simple Gadgets
+Version: 4.0.0
+Summary: **Module level function names.**
 Keywords: gadgets
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13
@@ -17,8 +17,8 @@ License-File: LICENSE
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
 Requires-Dist: pythonic-fp-circulararray>=6.0.0 ; 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/releases.html
-Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
+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: Source, https://github.com/grscheller/pythonic-fp-gadgets
 Provides-Extra: test
 
@@ -39,7 +39,7 @@ outside the Python Standard Library.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp/homepage/build/html/index.html>`_
+<https://grscheller.github.io/pythonic-fp>`_
 PyPI projects.
 
 Documentation
@@ -47,7 +47,7 @@ Documentation
 
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/gadgets/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp/gadgets>`_.
 
 Copyright and License
 ---------------------

{pythonic_fp_gadgets-3.1.0 → pythonic_fp_gadgets-4.0.0}/README.rst

@@ -15,7 +15,7 @@ outside the Python Standard Library.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp/homepage/build/html/index.html>`_
+<https://grscheller.github.io/pythonic-fp>`_
 PyPI projects.
 
 Documentation
@@ -23,7 +23,7 @@ Documentation
 
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/gadgets/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp/gadgets>`_.
 
 Copyright and License
 ---------------------

{pythonic_fp_gadgets-3.1.0 → pythonic_fp_gadgets-4.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythonic-fp-gadgets"
-version = "3.1.0"
+version = "4.0.0"
 readme = "README.rst"
 requires-python = ">=3.13"
 license = { file = "LICENSE" }
@@ -22,8 +22,8 @@ dynamic = ["description"]
 
 [project.urls]
 Changelog = "https://github.com/grscheller/pythonic-fp-gadgets/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp/gadgets/development/build/html/releases.html"
-Homepage = "https://github.com/grscheller/pythonic-fp/blob/main/README.md"
+Documentation = "https://grscheller.github.io/pythonic-fp/gadgets/development/build/html/"
+Homepage = "https://grscheller.github.io/pythonic-fp/homepage/build/html/"
 Source = "https://github.com/grscheller/pythonic-fp-gadgets"
 
 [project.optional-dependencies]
@@ -69,6 +69,7 @@ docstring-quotes = "double"
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["C901"]
+"tests/**/*.py" = ['E731']
 "**/*.py" = ["E741"]
 
 [tool.ruff.format]

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/__init__.py

@@ -0,0 +1,83 @@
+# Copyright 2023-2025 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.
+
+"""
+**Module level function names.**
+
+========================== ================================================
+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
+========================== ================================================
+
+"""
+
+from collections.abc import Iterator
+from inspect import getmro
+
+__all__ = ['iterate_over_arguments', 'first_common_ancestor']
+
+__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.
+
+    .. warning::
+
+        This function can fail with a TypeError. Some error messages
+        seen are
+
+        - 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.
+
+    :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``.
+
+    """
+    if issubclass(cls1, cls2):
+        return cls2
+    if issubclass(cls2, cls1):
+        return cls1
+
+    for common_ancestor in getmro(type('LcaDiamondClass', (cls1, cls2), {})):
+        if issubclass(cls1, common_ancestor) and issubclass(cls2, common_ancestor):
+            return common_ancestor
+    raise TypeError("latest_common_ancestor: no common ancestor found!!!")

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/__init__.pyi

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

{pythonic_fp_gadgets-3.1.0 → pythonic_fp_gadgets-4.0.0}/src/pythonic_fp/gadgets/box.py

@@ -12,8 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Class for a stateful container that can hold at most one item."""
-
 __all__ = ['Box']
 
 from collections.abc import Callable, Iterator
@@ -28,8 +26,8 @@ class Box[T]:
 
     .. note::
 
-         - ``Box(item: T)``: contains at one item of type ``T``
-         - ``Box[T]()``: creates empty container
+       - ``Box(item: T)``: contains at one item of type ``T``
+       - ``Box[T]()``: creates empty container
 
        Where type ``T`` is some definite type, which
        could be ``None`` or even ``Never``.
@@ -42,10 +40,10 @@ class Box[T]:
     __slots__ = ('_item',)
     __match_args__ = ('_item',)
 
-    @overload
-    def __init__(self) -> None: ...
     @overload
     def __init__(self, item: T) -> None: ...
+    @overload
+    def __init__(self) -> None: ...
 
     def __init__(self, item: T | _Sentinel = _sentinel) -> None:
         """

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/box.pyi

@@ -0,0 +1,27 @@
+from _typeshed import Incomplete
+from collections.abc import Callable, Iterator
+from typing import overload
+
+__all__ = ['Box']
+
+type _Sentinel = object
+class Box[T]:
+    __match_args__: Incomplete
+    @overload
+    def __init__(self, item: T) -> None: ...
+    @overload
+    def __init__(self) -> None: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[T]: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    @overload
+    def get(self) -> T: ...
+    @overload
+    def get(self, alt: T) -> T: ...
+    def pop(self) -> T: ...
+    def push(self, item: T) -> None: ...
+    def put(self, item: T) -> None: ...
+    def exchange(self, new_item: T) -> T: ...
+    def map[U](self, f: Callable[[T], U]) -> Box[U]: ...
+    def bind[U](self, f: Callable[[T], 'Box[U]']) -> Box[U]: ...

pythonic_fp_gadgets-3.1.0/src/pythonic_fp/gadgets/iterate_arguments.py → pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/sentinels/__init__.py

@@ -12,25 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Function which returns an iterator of its arguments."""
-
-from collections.abc import Iterator
-
-__all__ = ['ita']
-
-
-def ita[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
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'

{pythonic_fp_gadgets-3.1.0 → pythonic_fp_gadgets-4.0.0}/src/pythonic_fp/gadgets/sentinels/flavored.py

@@ -13,15 +13,7 @@
 # limitations under the License.
 
 """
-Flavored Sentinels
-==================
-
-Sentinel values labeled by different (hashable) flavors. Can be used
-with functions or classes.
-
-.. note::
-
-    Threadsafe.
+**Sentinel values labeled by different (hashable) flavors.**
 
 .. note::
 
@@ -35,15 +27,9 @@ with functions or classes.
     To ensure that reference equality is used, put the known
     sentinel value first in the comparison.
 
-.. tip::
-
-    Use as a hidden implementation detail when creating "optional"
-    arguments to functions and methods. Do not export the sentinel
-    value.
-
-    - does not clash with end user code
+.. note::
 
-      - which may be using either ``None`` or ``()`` as a "sentinel" values
+    Threadsafe.
 
 """
 

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/sentinels/flavored.pyi

@@ -0,0 +1,8 @@
+from typing import Hashable
+
+__all__ = ['Sentinel']
+
+class Sentinel[H: Hashable]:
+    def __new__(cls, flavor: H) -> Sentinel[H]: ...
+    def __init__(self, flavor: H) -> None: ...
+    def flavor(self) -> H: ...

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/sentinels/novalue.py

@@ -0,0 +1,124 @@
+# Copyright 2023-2025 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.
+
+"""
+**Singleton class representing an actually, not potentially, missing value.**
+
+.. note:
+
+    ``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
+
+    - ``None``: Returns, or returned, no values.
+    - ``()``: An empty, possibly typed, iterable collection.
+
+.. important::
+
+    Given variables
+
+    .. code:: python
+
+        x: int | NoValue
+        y: int | NoValue
+
+    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?
+
+    .. table:: ``x == y``
+
+        +-----------+-----------+--------+--------+
+        |    x∖y    | NoValue() | 42     | 57     |
+        +===========+===========+========+========+
+        | NoValue() | false     | false  | false  |
+        +-----------+-----------+--------+--------+
+        | 42        | false     | true   | false  |
+        +-----------+-----------+--------+--------+
+        | 57        | false     | false  | true   |
+        +-----------+-----------+--------+--------+
+
+    Similarly for not equals.
+
+    .. table:: ``x != y``
+
+        +-----------+-----------+--------+--------+
+        |    x∖y    | NoValue() | 42     | 57     |
+        +===========+===========+========+========+
+        | NoValue() | false     | false  | false  |
+        +-----------+-----------+--------+--------+
+        | 42        | false     | false  | true   |
+        +-----------+-----------+--------+--------+
+        | 57        | false     | true   | false  |
+        +-----------+-----------+--------+--------+
+
+.. warning::
+
+    Only use ``==`` or ``!=`` in value comparisons. To directly
+    identity the ``NoValue`` singleton, use ``is`` and ``is not``
+    instead.
+
+.. note::
+
+    Threadsafe.
+
+.. tip::
+
+    Use as a hidden implementation detail when creating "optional"
+    arguments to functions and methods.
+
+    To help ensure the abstraction does not leak,
+
+    - 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
+
+__all__ = ['NoValue']
+
+
+@final
+class NoValue():
+    __slots__ = ()
+
+    _instance: 'ClassVar[NoValue | None]' = None
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    def __new__(cls) -> 'NoValue':
+        """
+        :returns: The ``NoValue`` singleton instance.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return 'NoValue()'
+
+    def __eq__(self, other: object) -> bool:
+        """
+        :returns: False
+        """
+        return False
+
+    def __ne__(self, other: object) -> bool:
+        """
+        :returns: False
+        """
+        return False

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/sentinels/novalue.pyi

@@ -0,0 +1,6 @@
+__all__ = ['NoValue']
+
+class NoValue:
+    def __new__(cls) -> NoValue: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...

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

@@ -0,0 +1,124 @@
+# Copyright 2023-2025 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]():
+    """Immutablely wrap exactly one value of a given type.
+
+    .. tip::
+
+        ``Wrap`` objects can be used in Python match statements.
+
+    """
+    __slots__ = ('_item',)
+    __match_args__ = ('_item',)
+
+    def __init__(self, item: T) -> None:
+        self._item = item
+
+    def __bool__(self) -> bool:
+        return bool(self._item)
+
+    def __iter__(self) -> Iterator[T]:
+        if self:
+            yield self._item
+
+    def __repr__(self) -> str:
+        return 'Wrap(' + repr(self._item) + ')'
+
+    def __eq__(self, other: object) -> bool:
+        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]':
+        """Map function ``f`` over contents.
+
+        :param f: Mapping function.
+        :returns: A new instance.
+
+        """
+        return Wrap(f(self._item))
+
+    def bind[U](self, f: Callable[[T], 'Wrap[U]']) -> 'Wrap[U]':
+        """Flatmap the ``Wrap`` with function ``f``.
+
+        :param f: Binding function.
+        :returns: A new instance.
+
+        """
+        return f(self._item)
+
+
+class HWrap[T: Hashable](Hashable):
+    """Immutablely wrap exactly one hashable value of a given type.
+
+    .. tip::
+
+        ``Wrap`` objects can be used in Python match statements.
+
+    """
+    __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:
+        return bool(self._item)
+
+    def __iter__(self) -> Iterator[T]:
+        if self:
+            yield self._item
+
+    def __repr__(self) -> str:
+        return 'Wrap(' + repr(self._item) + ')'
+
+    def __eq__(self, other: object) -> bool:
+        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]':
+        """Map function ``f`` over contents.
+
+        :param f: Mapping function.
+        :returns: A new instance.
+
+        """
+        return HWrap(f(self._item))
+
+    def bind[U](self, f: Callable[[T], 'HWrap[U]']) -> 'HWrap[U]':
+        """Flatmap the ``Wrap`` with function ``f``.
+
+        :param f: Binding function.
+        :returns: A new instance.
+
+        """
+        return f(self._item)

pythonic_fp_gadgets-4.0.0/src/pythonic_fp/gadgets/wrap.pyi

@@ -0,0 +1,23 @@
+from _typeshed import Incomplete
+from collections.abc import Callable, Hashable, Iterator
+
+__all__ = ['Wrap', 'HWrap']
+
+class Wrap[T]:
+    __match_args__: Incomplete
+    def __init__(self, item: T) -> None: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[T]: ...
+    def __eq__(self, other: object) -> bool: ...
+    def map[U](self, f: Callable[[T], U]) -> Wrap[U]: ...
+    def bind[U](self, f: Callable[[T], 'Wrap[U]']) -> Wrap[U]: ...
+
+class HWrap[T: Hashable](Hashable):
+    __match_args__: Incomplete
+    def __init__(self, item: T) -> None: ...
+    def __hash__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[T]: ...
+    def __eq__(self, other: object) -> bool: ...
+    def map[U](self, f: Callable[[T], U]) -> HWrap[U]: ...
+    def bind[U](self, f: Callable[[T], 'HWrap[U]']) -> HWrap[U]: ...

pythonic_fp_gadgets-4.0.0/tests/test_first_common_ancestor.py

@@ -0,0 +1,115 @@
+# Copyright 2023-2025 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.
+
+from pythonic_fp.gadgets import first_common_ancestor as fca
+
+
+class A1():
+    pass
+
+class A1B1(A1):
+    pass
+
+class A1B1C1(A1B1):
+    pass
+
+class A1B1C2(A1B1):
+    pass
+
+class A1B2(A1):
+    pass
+
+class A1B2C1(A1B2):
+    pass
+
+class A1B2C2(A1B2):
+    pass
+
+class A2():
+    pass
+
+class A2B1(A2):
+    pass
+
+class A2B1C1(A2B1):
+    pass
+
+class A2B1C2(A2B1):
+    pass
+
+class A2B2(A2):
+    pass
+
+class A2B2C1(A2B2):
+    pass
+
+class A2B2C1D1(A2B2C1):
+    pass
+
+class A2B2C1D2(A2B2C1):
+    pass
+
+class A2B2C2(A2B2):
+    pass
+
+class A2B2C2D1(A2B2C2):
+    pass
+
+class A2B2C2D2(A2B2C2):
+    pass
+
+class TestLatestCommonAncestor:
+    """Functionality testing"""
+
+    def test_self(self) -> None:
+        assert fca(A1, A1) is A1
+        assert fca(A1B1, A1B1) is A1B1
+        assert fca(A1B1C1, A1B1C1) is A1B1C1
+        assert fca(int, int) is int
+        assert fca(bool, bool) is bool
+
+    def test_linear_descent(self) -> None:
+        assert fca(A1, A1B1) is A1
+        assert fca(A1B1, A1) is A1
+        assert fca(A1B1C1, A1) is A1
+        assert fca(A1, A1B1C1) is A1
+        assert fca(A1B1C1, A1B1) is A1B1
+        assert fca(A1B1, A1B1C1) is A1B1
+        assert fca(A1B1C1, A1B1) is A1B1
+        assert fca(A1B1, A1B1C1) is A1B1
+        assert fca(A1B1C1, A1) is A1
+        assert fca(A1, A1B1C1) is A1
+        assert fca(A2B2, A2B2C2D2) is A2B2
+        assert fca(A2B2C2D2, A2B2) is A2B2
+        assert fca(int, object) is object
+        assert fca(object, int) is object
+        assert fca(int, bool) is int
+        assert fca(bool, int) is int
+
+    def test_nonliear_descent(self) -> None:
+        assert fca(A1B1, A1B2) is A1
+        assert fca(A1B2, A1B1) is A1
+        assert fca(A1B2C1, A1B2C2) is A1B2
+        assert fca(A1B2C2, A1B2C1) is A1B2
+        assert fca(A1B1C1, A1B2C2) is A1
+        assert fca(A1B2C2, A1B1C1) is A1
+        assert fca(A1B1C1, A1B2C1) is A1
+        assert fca(A1B2C1, A1B1C1) is A1
+        assert fca(A2B2C1, A2B2C2D2) is A2B2
+        assert fca(A2B2C2D2, A2B2C1) is A2B2
+        assert fca(A2B1C1, A2B2C2D2) is A2
+        assert fca(A2B2C2D2, A2B1C1) is A2
+        assert fca(A1, A2) is object
+        assert fca(A2B2C2D2, A1B2C2) is object
+        assert fca(A1B2C1, A2B1C1) is object

pythonic_fp_gadgets-4.0.0/tests/test_hwrap.py

@@ -0,0 +1,76 @@
+# Copyright 2023-2025 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.
+
+from pythonic_fp.gadgets.wrap import HWrap
+
+
+class TestGadgetHWrapBuiltins:
+    def test_hwrap_simple(self) -> None:
+        w0 = HWrap(0)
+        w1 = HWrap(1)
+        x1 = HWrap(1)
+
+        assert w0 != w1
+        assert w1 == x1
+        assert w1 is w1
+        assert w1 is not x1
+
+        assert hash(w0) == hash(w0)
+        assert hash(w1) == hash(w1)
+        assert hash(w1) == hash(x1)
+        assert hash(w1) != hash(w0)
+
+    def test_map(self) -> None:
+        def cat(s: str) -> str:
+            return s + s
+
+        wa = HWrap('a')
+        waa = HWrap('aa')
+        waaaa = HWrap('aaaa')
+
+        xaa = wa.map(cat)
+        xaaaa = xaa.map(cat)
+
+        assert xaa == waa
+        assert xaa != waaaa
+        assert xaaaa == waaaa
+        assert waaaa == xaaaa
+
+    def test_bind(self) -> None:
+        type TS = tuple[str, ...]
+        type WLS = HWrap[TS]
+        type TI = tuple[int, ...]
+        type WTI = HWrap[TI]
+
+        def cnt(ts: TS) -> WTI:
+            ti: TI = ()
+            for s in ts:
+                ti += (len(s),)
+            return HWrap(ti)
+
+        hw: TS = ('hello', 'world', '!')
+        fb: TS = ('foobar',)
+        nil: TS = ()
+
+        wt_hw: WLS = HWrap(hw)
+        wt_fb: WLS = HWrap(fb)
+        wt_nil: WLS = HWrap(nil)
+
+        wi_hw: WTI = HWrap((5, 5, 1))
+        wi_fb: WTI = HWrap((6,))
+        wi_nil: WTI = HWrap(())
+
+        assert wi_hw == wt_hw.bind(cnt)
+        assert wi_fb == wt_fb.bind(cnt)
+        assert wi_nil == wt_nil.bind(cnt)

pythonic_fp_gadgets-3.1.0/tests/test_it.py → pythonic_fp_gadgets-4.0.0/tests/test_iterate_over_arguments.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from pythonic_fp.circulararray.auto import ca, CA
-from pythonic_fp.gadgets.iterate_arguments import ita
+from pythonic_fp.gadgets import iterate_over_arguments as ita
 
 class TestGadgetIt:
     """Functionality testing"""

pythonic_fp_gadgets-4.0.0/tests/test_wrap.py

@@ -0,0 +1,71 @@
+# Copyright 2023-2025 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.
+
+from pythonic_fp.gadgets.wrap import Wrap
+
+
+class TestGadgetWrapBuiltins:
+    def test_wrap_simple(self) -> None:
+        w0 = Wrap(0)
+        w1 = Wrap(1)
+        x1 = Wrap(1)
+
+        assert w0 != w1
+        assert w1 == x1
+        assert w1 is w1
+        assert w1 is not x1
+
+    def test_map(self) -> None:
+        def cat(s: str) -> str:
+            return s + s
+
+        wa = Wrap('a')
+        waa = Wrap('aa')
+        waaaa = Wrap('aaaa')
+
+        xaa = wa.map(cat)
+        xaaaa = xaa.map(cat)
+
+        assert xaa == waa
+        assert xaa != waaaa
+        assert xaaaa == waaaa
+        assert waaaa == xaaaa
+
+    def test_bind(self) -> None:
+        type LS = list[str]
+        type WLS = Wrap[LS]
+        type LI = list[int]
+        type WLI = Wrap[LI]
+
+        def cnt(ls: LS) -> WLI:
+            li: LI = []
+            for s in ls:
+                li.append(len(s))
+            return Wrap(li)
+
+        hw: LS = ['hello', 'world', '!']
+        fb: LS = ['foobar',]
+        nil: LS = []
+
+        wt_hw: WLS = Wrap(hw)
+        wt_fb: WLS = Wrap(fb)
+        wt_nil: WLS = Wrap(nil)
+
+        wi_hw: WLI = Wrap([5, 5, 1])
+        wi_fb: WLI = Wrap([6,])
+        wi_nil: WLI = Wrap([])
+
+        assert wi_hw == wt_hw.bind(cnt)
+        assert wi_fb == wt_fb.bind(cnt)
+        assert wi_nil == wt_nil.bind(cnt)

pythonic_fp_gadgets-3.1.0/src/pythonic_fp/gadgets/__init__.py

@@ -1,39 +0,0 @@
-# Copyright 2023-2025 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.
-
-"""
-Simple Gadgets
-==============
-
-Library of simple, but useful, functions and classes with no external
-dependencies besides the those from the Python standard Library. This
-includes other Pythonic Functional Programming dependencies.
-
-+------------------------------+----------------------+------------------------------------------------+
-| Description                  | Gadget               | Module                                         |
-+==============================+======================+================================================+
-| Single item box              | class ``Box``        | ``pythonic_fp.gadgets.box``                    |
-+------------------------------+----------------------+------------------------------------------------+
-| Return Iterator of arguments | function ``ita``     | ``pythonic_fp.gadgets.iterate_arguments``      |
-+------------------------------+----------------------+------------------------------------------------+
-| Find least common base class | function ``lca``     | ``pythonic_fp.gadgets.latest_common_ancestor`` |
-+------------------------------+----------------------+------------------------------------------------+
-| sentinels values with extras | module ``sentinals`` | ``pythonic_fp.gadgets.sentinels``              |
-+------------------------------+----------------------+------------------------------------------------+
-
-"""
-
-__author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
-__license__ = 'Apache License 2.0'

pythonic_fp_gadgets-3.1.0/src/pythonic_fp/gadgets/latest_common_ancestor.py

@@ -1,51 +0,0 @@
-# Copyright 2023-2025 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.
-
-"""Last Common Ancestor of Two Classes."""
-
-from inspect import getmro
-
-__all__ = ['lca']
-
-
-def lca(cls1: type, cls2: type) -> type:
-    """Find the least upper bound in the inheritance graph
-    of two classes.
-
-    .. warning::
-
-       This function can fail with a TypeError. Some error messages
-       seen are
-
-         - 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.
-
-    :param cls1: first class
-    :param cls2: second class
-    :returns: Least common ancestor base class of ``cls1`` and ``cls2``.
-    :raises TypeError: theoretically only from ``inspect.getmto``
-
-    """
-    if issubclass(cls1, cls2):
-        return cls2
-    if issubclass(cls2, cls1):
-        return cls1
-
-    for common_ancestor in getmro(type('LcaDiamondClass', (cls1, cls2), {})):
-        if issubclass(cls1, common_ancestor) and issubclass(cls2, common_ancestor):
-            return common_ancestor
-    raise TypeError("latest_common_ancestor: no common ancestor found!!!") 

pythonic_fp_gadgets-3.1.0/src/pythonic_fp/gadgets/sentinels/__init__.py

@@ -1,31 +0,0 @@
-# Copyright 2023-2025 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.
-
-"""
-Sentinels with Extras
-=====================
-
-+-----------------------+---------------------------+-----------------------------------------------+
-| Module                | Class                     | Represents                                    |
-+=======================+===========================+===============================================+
-| ``sentinel.novalue``  | ``NoValue``               | an actually , not potentially, missing value  |
-+-----------------------+---------------------------+-----------------------------------------------+
-| ``sentinel.flavored`` | ``Sentinel[H: Hashable]`` | distinct sentinels labeled by hashable values |
-+-----------------------+---------------------------+-----------------------------------------------+
-
-"""
-
-__author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
-__license__ = 'Apache License 2.0'

pythonic_fp_gadgets-3.1.0/src/pythonic_fp/gadgets/sentinels/novalue.py

@@ -1,106 +0,0 @@
-# Copyright 2023-2025 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.
-
-"""
-Missing Value Sentinel
-======================
-
-Singleton class representing a missing value.
-
-In untyped Python, both ``None`` and ``()`` are often used by end users
-and libraries as sentinel values. I prefer to think of them as
-
-- ``None``: returned (or returns) no values
-- ``()``: an empty, possibly typed, but still iterable collection
-
-While ``NoValue()`` is a singleton object representing a missing value.
-
-Given variables
-
-.. code:: python
-
-    x: int | NoValue
-    y: int | NoValue
-
-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?
-
-.. table:: ``x == y``
-
-    +-----------+-----------+--------+--------+
-    |    x∖y    | NoValue() | 42     | 57     |
-    +===========+===========+========+========+
-    | NoValue() | false     | false  | false  |
-    +-----------+-----------+--------+--------+
-    | 42        | false     | true   | false  |
-    +-----------+-----------+--------+--------+
-    | 57        | false     | false  | true   |
-    +-----------+-----------+--------+--------+
-
-Similarly for not equals.
-
-.. table:: ``x != y``
-
-    +-----------+-----------+--------+--------+
-    |    x∖y    | NoValue() | 42     | 57     |
-    +===========+===========+========+========+
-    | NoValue() | false     | false  | false  |
-    +-----------+-----------+--------+--------+
-    | 42        | false     | false  | true   |
-    +-----------+-----------+--------+--------+
-    | 57        | false     | true   | false  |
-    +-----------+-----------+--------+--------+
-
-.. note::
-
-    Threadsafe.
-
-.. warning::
-
-    Do not use ``==`` or ``!=`` to identify ``NoValue()``,  compare
-    directly by identity using ``is`` and ``is not``.
-
-"""
-
-import threading
-from typing import ClassVar, final
-
-__all__ = ['NoValue']
-
-
-@final
-class NoValue():
-    __slots__ = ()
-
-    _instance: 'ClassVar[NoValue | None]' = None
-    _lock: ClassVar[threading.Lock] = threading.Lock()
-
-    def __new__(cls) -> 'NoValue':
-        """
-        :returns: The ``NoValue`` singleton instance.
-        """
-        if cls._instance is None:
-            with cls._lock:
-                if cls._instance is None:
-                    cls._instance = super().__new__(cls)
-        return cls._instance
-
-    def __repr__(self) -> str:
-        return 'NoValue()'
-
-    def __eq__(self, other: object) -> bool:
-        return False
-
-    def __ne__(self, other: object) -> bool:
-        return False

pythonic_fp_gadgets-3.1.0/tests/test_lca.py

@@ -1,114 +0,0 @@
-# Copyright 2023-2025 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.
-
-from pythonic_fp.gadgets.latest_common_ancestor import lca
-
-class A1():
-    pass
-
-class A1B1(A1):
-    pass
-
-class A1B1C1(A1B1):
-    pass
-
-class A1B1C2(A1B1):
-    pass
-
-class A1B2(A1):
-    pass
-
-class A1B2C1(A1B2):
-    pass
-
-class A1B2C2(A1B2):
-    pass
-
-class A2():
-    pass
-
-class A2B1(A2):
-    pass
-
-class A2B1C1(A2B1):
-    pass
-
-class A2B1C2(A2B1):
-    pass
-
-class A2B2(A2):
-    pass
-
-class A2B2C1(A2B2):
-    pass
-
-class A2B2C1D1(A2B2C1):
-    pass
-
-class A2B2C1D2(A2B2C1):
-    pass
-
-class A2B2C2(A2B2):
-    pass
-
-class A2B2C2D1(A2B2C2):
-    pass
-
-class A2B2C2D2(A2B2C2):
-    pass
-
-class TestLatestCommonAncestor:
-    """Functionality testing"""
-
-    def test_self(self) -> None:
-        assert lca(A1, A1) is A1
-        assert lca(A1B1, A1B1) is A1B1
-        assert lca(A1B1C1, A1B1C1) is A1B1C1
-        assert lca(int, int) is int
-        assert lca(bool, bool) is bool
-
-    def test_linear_descent(self) -> None:
-        assert lca(A1, A1B1) is A1
-        assert lca(A1B1, A1) is A1
-        assert lca(A1B1C1, A1) is A1
-        assert lca(A1, A1B1C1) is A1
-        assert lca(A1B1C1, A1B1) is A1B1
-        assert lca(A1B1, A1B1C1) is A1B1
-        assert lca(A1B1C1, A1B1) is A1B1
-        assert lca(A1B1, A1B1C1) is A1B1
-        assert lca(A1B1C1, A1) is A1
-        assert lca(A1, A1B1C1) is A1
-        assert lca(A2B2, A2B2C2D2) is A2B2
-        assert lca(A2B2C2D2, A2B2) is A2B2
-        assert lca(int, object) is object
-        assert lca(object, int) is object
-        assert lca(int, bool) is int
-        assert lca(bool, int) is int
-
-    def test_nonliear_descent(self) -> None:
-        assert lca(A1B1, A1B2) is A1
-        assert lca(A1B2, A1B1) is A1
-        assert lca(A1B2C1, A1B2C2) is A1B2
-        assert lca(A1B2C2, A1B2C1) is A1B2
-        assert lca(A1B1C1, A1B2C2) is A1
-        assert lca(A1B2C2, A1B1C1) is A1
-        assert lca(A1B1C1, A1B2C1) is A1
-        assert lca(A1B2C1, A1B1C1) is A1
-        assert lca(A2B2C1, A2B2C2D2) is A2B2
-        assert lca(A2B2C2D2, A2B2C1) is A2B2
-        assert lca(A2B1C1, A2B2C2D2) is A2
-        assert lca(A2B2C2D2, A2B1C1) is A2
-        assert lca(A1, A2) is object
-        assert lca(A2B2C2D2, A1B2C2) is object
-        assert lca(A1B2C1, A2B1C1) is object