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

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

@@ -17,16 +17,32 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Corrected incorrect dependencies.
+
 PyPI v3.0.0 - 2025-08-31
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Discovered I was not quite compliant with Python typing 3.12+ conventions.
+Discovered I was not quite compliant with
+Python typing 3.12+ conventions.
 
 - No longer explicitly using TypeVar directly.
-- Removed Unions with Never from .py files
 
-  - only "happy path" return types (pythonic convention)
-  - stubgen actually puts them back in .pyi files
+  - Removed Unions with Never from .py files
+
+    - the "happy path" returns just types (pythonic convention)
+    - stubgen actually puts them back in .pyi files
 
 - renamed it.it -> iterate_arguments.ita
 - renamed lca.latest_common_ancestor -> latest_common_ancestor.lca
@@ -34,11 +50,12 @@ Discovered I was not quite compliant with Python typing 3.12+ conventions.
 PyPI v2.2.0 - 2025-08-30
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Moved for pythonic_fp.gadgets package to a new GitHub repo, pythonic-fp-gadgets.
-Replaced it with the empty Python module ``pythonic_fp.name_claim``.
+Moved for pythonic_fp.gadgets package to a new GitHub repo,
+pythonic-fp-gadgets. Replaced it with the empty Python
+module pythonic_fp.name_claim in pythonic-fp.
 
-The gadgets package being different from the other namespace packages
-was throwing off my workflow.
+The gadgets package being different from the other namespace
+packages was throwing off my workflow.
 
 - added function it.it
 - added function lca.latest_common_ancestor
@@ -59,6 +76,7 @@ Released pythonic-fp v1.1.0 which contains pythonic_fp.gadgets package.
 Update - 2025-08-01
 ~~~~~~~~~~~~~~~~~~~
 
-Added package pythonic_fp.gadgets to the "name-claim" PyPI project pythonic-fp.
-The gadgets library is for simple, but useful, functions and data structures
-with minimal dependencies.
+Added package pythonic_fp.gadgets to the "name-claim" PyPI
+project pythonic-fp. The gadgets library is for simple,
+but useful, functions and data structures with minimal
+dependencies.

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 3.0.1
-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
@@ -14,11 +14,11 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-sentinels>=2.1.0
 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
 
@@ -29,22 +29,25 @@ PyPI project
 `pythonic-fp-gadgets
 <https://pypi.org/project/pythonic-fp>`_.
 
-Library of simple, but useful, data structures with minimal dependencies.
+Library of simple, but useful, classes and functions with no dependencies
+outside the Python Standard Library.
 
-- single item box
-- function returning iterator of its arguments
-- find the last common ancestor of two classes
+- Gadgets
+  - single item box
+  - function returning iterator of its arguments
+  - find the latest common ancestor of two classes
 
-This PyPI project is part of of the grscheller
-`pythonic-fp namespace projects
-<https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
+Part of the
+`pythonic-fp
+<https://grscheller.github.io/pythonic-fp>`_
+PyPI projects.
 
 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-4.0.0/README.rst

@@ -0,0 +1,32 @@
+Pythonic FP - Gadgets
+=====================
+
+PyPI project
+`pythonic-fp-gadgets
+<https://pypi.org/project/pythonic-fp>`_.
+
+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
+
+Part of the
+`pythonic-fp
+<https://grscheller.github.io/pythonic-fp>`_
+PyPI projects.
+
+Documentation
+-------------
+
+Documentation for this project is hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/gadgets>`_.
+
+Copyright and License
+---------------------
+
+Copyright (c) 2025 Geoffrey R. Scheller. Licensed under the Apache
+License, Version 2.0. See the LICENSE file for details.

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

@@ -1,6 +1,6 @@
 [project]
 name = "pythonic-fp-gadgets"
-version = "3.0.1"
+version = "4.0.0"
 readme = "README.rst"
 requires-python = ">=3.13"
 license = { file = "LICENSE" }
@@ -17,20 +17,19 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Typing :: Typed",
 ]
-dependencies = [
-  "pythonic-fp-sentinels>=2.1.0",
-]
+dependencies = []
 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]
 test = [
   "pytest>=8.4.1",
+  "pythonic-fp-circulararray>=6.0.0",
 ]
 
 [build-system]
@@ -70,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.0.1 → pythonic_fp_gadgets-4.0.0}/src/pythonic_fp/gadgets/box.py

@@ -12,13 +12,13 @@
 # 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
-from typing import ClassVar, cast, Final, overload
-from pythonic_fp.sentinels.flavored import Sentinel
+from typing import cast, Final, overload
+
+type _Sentinel = object
+_sentinel: Final[_Sentinel] = object()
 
 
 class Box[T]:
@@ -26,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``.
@@ -40,23 +40,19 @@ class Box[T]:
     __slots__ = ('_item',)
     __match_args__ = ('_item',)
 
-    _sentinel: Final[ClassVar[Sentinel[str]]] = Sentinel('_Box')
-
-    @overload
-    def __init__(self) -> None: ...
     @overload
     def __init__(self, item: T) -> None: ...
+    @overload
+    def __init__(self) -> None: ...
 
-    def __init__(self, item: T | Sentinel[str] = Sentinel('_Box')) -> None:
+    def __init__(self, item: T | _Sentinel = _sentinel) -> None:
         """
-        :param item: an "optional" initial contained ``item`` for the ``Box``.
-        :returns: New ``Box`` instance.
-
+        :param item: An "optional" initial contained ``item`` for the ``Box``.
         """
         self._item = item
 
     def __bool__(self) -> bool:
-        return self._item is not Sentinel('_Box')
+        return self._item is not _sentinel
 
     def __iter__(self) -> Iterator[T]:
         if self:
@@ -85,7 +81,7 @@ class Box[T]:
     @overload
     def get(self, alt: T) -> T: ...
 
-    def get(self, alt: T | Sentinel[str] = Sentinel('_Box')) -> T:
+    def get(self, alt: T | _Sentinel = _sentinel) -> T:
         """Return the contained item if it exists, otherwise an alternate item.
 
         :param alt: an "optional" item of type ``T`` to return if ``Box`` is empty
@@ -93,9 +89,9 @@ class Box[T]:
         :raises ValueError: when an ``alt`` item is not provided but needed
 
         """
-        if self._item is not self._sentinel:
+        if self._item is not _sentinel:
             return cast(T, self._item)
-        if alt is self._sentinel:
+        if alt is _sentinel:
             msg = 'Box: get from empty Box with no alternate return item provided'
             raise ValueError(msg)
         return cast(T, alt)
@@ -103,15 +99,15 @@ class Box[T]:
     def pop(self) -> T:
         """Pop the contained item if ``Box`` is not empty.
 
-        :returns: 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 self._sentinel:
+        if self._item is _sentinel:
             msg = 'Box: Trying to pop an item from an empty Box'
             raise ValueError(msg)
         popped = cast(T, self._item)
-        self._item = self._sentinel
+        self._item = _sentinel
         return popped
 
     def push(self, item: T) -> None:
@@ -121,7 +117,7 @@ class Box[T]:
         :raises ValueError: If ``Box`` is not empty.
 
         """
-        if self._item is Sentinel('_Box'):
+        if self._item is _sentinel:
             self._item = item
         else:
             msg = 'Box: Trying to push an item in a non-empty Box'
@@ -139,7 +135,7 @@ class Box[T]:
         :returns: Original contents of the ``Box``.
         :raises ValueError: If Box is empty.
         """
-        if self._item is self._sentinel:
+        if self._item is _sentinel:
             msg = 'Box: Trying to exchange items from an empty Box'
             raise ValueError(msg)
         popped = cast(T, self._item)
@@ -154,7 +150,7 @@ class Box[T]:
         :returns: a new instance
 
         """
-        if self._item is Sentinel('_Box'):
+        if self._item is _sentinel:
             return Box()
         return Box(f(cast(T, self._item)))
 
@@ -165,6 +161,6 @@ class Box[T]:
         :returns: a new instance
 
         """
-        if self._item is self._sentinel:
+        if self._item is _sentinel:
             return Box()
         return f(cast(T, self._item))

{pythonic_fp_gadgets-3.0.1 → pythonic_fp_gadgets-4.0.0}/src/pythonic_fp/gadgets/box.pyi

@@ -4,12 +4,13 @@ from typing import overload
 
 __all__ = ['Box']
 
+type _Sentinel = object
 class Box[T]:
     __match_args__: Incomplete
     @overload
-    def __init__(self) -> None: ...
-    @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: ...

pythonic_fp_gadgets-3.0.1/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-4.0.0/src/pythonic_fp/gadgets/sentinels/flavored.py

@@ -0,0 +1,72 @@
+# 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.
+
+"""
+**Sentinel values labeled by different (hashable) flavors.**
+
+.. note::
+
+    Can be compared using ``==`` and ``!=``. A flavored sentinel
+    value always equals itself and never equals anything else,
+    especially other flavored sentinel values.
+
+    Useful for union types where ``Sentinel[H]`` is one of the
+    types making up the union.
+
+    To ensure that reference equality is used, put the known
+    sentinel value first in the comparison.
+
+.. note::
+
+    Threadsafe.
+
+"""
+
+import threading
+from typing import ClassVar, final, Hashable
+
+__all__ = ['Sentinel']
+
+
+@final
+class Sentinel[H: Hashable]:
+    __slots__ = ('_flavor',)
+
+    _flavors: 'dict[H, Sentinel[H]]' = {}
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    def __new__(cls, flavor: H) -> 'Sentinel[H]':
+        if flavor not in cls._flavors:
+            with cls._lock:
+                if flavor not in cls._flavors:
+                    cls._flavors[flavor] = super().__new__(cls)
+        return cls._flavors[flavor]
+
+    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.
+        """
+        if not hasattr(self, '_flavor'):
+            self._flavor = flavor
+
+    def __repr__(self) -> str:
+        return "Sentinel('" + repr(self._flavor) + "')"
+
+    def flavor(self) -> H:
+        """
+        :returns: The sentinel's flavor. A ``Hashable`` value of type ``H``.
+        """
+        return self._flavor

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: ...