pythonic-fp-gadgets 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

pythonic_fp/gadgets/__init__.py

@@ -16,17 +16,21 @@
 Simple Gadgets
 ==============
 
-Library of simple, but useful, functions and classes with minimal dependencies.
+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`` |
-+------------------------------+------------------+------------------------------------------------+
++------------------------------+----------------------+------------------------------------------------+
+| 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``              |
++------------------------------+----------------------+------------------------------------------------+
 
 """
 

pythonic_fp/gadgets/box.py

@@ -17,8 +17,10 @@
 __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]:
@@ -40,23 +42,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: ...
 
-    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 +83,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 +91,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 +101,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 +119,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 +137,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 +152,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 +163,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/sentinels/__init__.py

@@ -0,0 +1,31 @@
+# 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/sentinels/flavored.py

@@ -0,0 +1,86 @@
+# 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.
+
+"""
+Flavored Sentinels
+==================
+
+Sentinel values labeled by different (hashable) flavors. Can be used
+with functions or classes.
+
+.. note::
+
+    Threadsafe.
+
+.. 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.
+
+.. 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
+
+      - which may be using either ``None`` or ``()`` as a "sentinel" values
+
+"""
+
+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/sentinels/novalue.py

@@ -0,0 +1,106 @@
+# 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.0.0.dist-info → pythonic_fp_gadgets-3.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-gadgets
-Version: 3.0.0
+Version: 3.1.0
 Summary: Simple Gadgets
 Keywords: gadgets
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
@@ -14,8 +14,8 @@ 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
@@ -29,15 +29,18 @@ 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/homepage/build/html/index.html>`_
+PyPI projects.
 
 Documentation
 -------------

pythonic_fp_gadgets-3.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pythonic_fp/gadgets/__init__.py,sha256=dWSy355mwnu8WWX473KMLgSduFaUwmCqFyc93aWJ0yA,2122
+pythonic_fp/gadgets/box.py,sha256=gdlCI0BXXRvlaHrN8j0gjcVh5omZnE_g0fTpEYLBBxE,5068
+pythonic_fp/gadgets/iterate_arguments.py,sha256=7gFQgqn8vpBQIxOPYlpAgW26Fyzfjnux3Y2cxHYZuSM,1057
+pythonic_fp/gadgets/latest_common_ancestor.py,sha256=CHN5q82p8n05XPuA5rTq9gwtOkvuz9U-QMJEqOjlqqM,1689
+pythonic_fp/gadgets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/gadgets/sentinels/__init__.py,sha256=2166dSxuQqQT_f7QKOsD6vKrMkFy6XzIJKhPnXMCKy0,1493
+pythonic_fp/gadgets/sentinels/flavored.py,sha256=g1Y2qGAGL06GDmF7d6jTuPj11OCWaxbQ89E7TtXGWtU,2543
+pythonic_fp/gadgets/sentinels/novalue.py,sha256=Whu0BPSWrl7t_V2dITlyLT6lt2UiNphMr_fWT_heOfI,3077
+pythonic_fp_gadgets-3.1.0.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+pythonic_fp_gadgets-3.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_gadgets-3.1.0.dist-info/METADATA,sha256=hwYMFjf0xfV4z8cfwWHC-E5oUySAFcEHHtdB6Qr67Ls,1876
+pythonic_fp_gadgets-3.1.0.dist-info/RECORD,,

pythonic_fp/gadgets/box.pyi

@@ -1,26 +0,0 @@
-from _typeshed import Incomplete
-from collections.abc import Callable, Iterator
-from typing import overload
-
-__all__ = ['Box']
-
-class Box[T]:
-    __match_args__: Incomplete
-    @overload
-    def __init__(self) -> None: ...
-    @overload
-    def __init__(self, item: T) -> 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/iterate_arguments.pyi

@@ -1,5 +0,0 @@
-from collections.abc import Iterator
-
-__all__ = ['ita']
-
-def ita[A](*args: A) -> Iterator[A]: ...

pythonic_fp/gadgets/latest_common_ancestor.pyi

@@ -1,3 +0,0 @@
-__all__ = ['lca']
-
-def lca(cls1: type, cls2: type) -> type: ...

pythonic_fp_gadgets-3.0.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-pythonic_fp/gadgets/__init__.py,sha256=2nrTFkbHHW2ZbbEwmMypXrU5aO70JwLZrQt131pdF7E,1755
-pythonic_fp/gadgets/box.py,sha256=VR_MOCRDH5tyM6BaM7uFcHW-jKqDJlxfb_WbxKuZ6fs,5244
-pythonic_fp/gadgets/box.pyi,sha256=4TAYuLnnxzXsADX8JwblsH-020pYkXJRsPqeDqkK44Q,813
-pythonic_fp/gadgets/iterate_arguments.py,sha256=7gFQgqn8vpBQIxOPYlpAgW26Fyzfjnux3Y2cxHYZuSM,1057
-pythonic_fp/gadgets/iterate_arguments.pyi,sha256=BXyRZUTToIVQls9jpIbRGAtp8PCmZ-onJeKH29UzQkM,98
-pythonic_fp/gadgets/latest_common_ancestor.py,sha256=CHN5q82p8n05XPuA5rTq9gwtOkvuz9U-QMJEqOjlqqM,1689
-pythonic_fp/gadgets/latest_common_ancestor.pyi,sha256=dDta0kOY7T4mjPknJnMWDV9X4pveW4euxi_0V176hbc,64
-pythonic_fp/gadgets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp_gadgets-3.0.0.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-pythonic_fp_gadgets-3.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_gadgets-3.0.0.dist-info/METADATA,sha256=uWPQwLeEFGtq5Mzsd2dpYd5FVcpDVr61aT33DTmnAYM,1828
-pythonic_fp_gadgets-3.0.0.dist-info/RECORD,,