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

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

@@ -1,12 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pythonic-fp-gadgets
-Version: 4.0.4
-Summary: Gadgets
+Version: 4.2.0
+Summary: Gadgets without external Pythonic FP dependencies.
 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
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -14,46 +14,37 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Requires-Dist: pythonic-fp-circulararray>=6.0.4 ; 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/projects/gadgets.html
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-gadgets/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-gadgets/release/html/
 Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-gadgets
-Provides-Extra: test
+Import-Name: pythonic_fp.gadgets
+Import-Namespace: pythonic_fp
 
-Pythonic FP - Gadgets
-=====================
-
-PyPI project
-`pythonic-fp-gadgets
-<https://pypi.org/project/pythonic-fp-gadgets>`_.
+# Pythonic FP - Gadgets
 
 Library of simple, but useful, classes and functions with no dependencies
 outside the Python Standard Library.
 
-- Gadgets
+PyPI project
+[pythonic-fp-gadgets](https://pypi.org/project/pythonic-fp-gadgets).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
+
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/gadgets.html).
 
+- Gadgets
   - single item box
   - immutable wrapped (hashable) references
   - function returning iterator of its arguments
   - function to find the latest common ancestor of two classes
   - sentinel values
 
-Part of the
-`pythonic-fp
-<https://grscheller.github.io/pythonic-fp/>`_
-PyPI projects.
-
-Documentation
--------------
-
-Documentation and other links for this project are hosted on
-`GitHub Pages
-<https://grscheller.github.io/pythonic-fp/projects/gadgets.html>`_.
-
-Copyright and License
----------------------
+## Copyright and License
 
 Copyright (c) 2025-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

pythonic_fp_gadgets-4.0.4/README.rst → pythonic_fp_gadgets-4.2.0/README.md

@@ -1,35 +1,27 @@
-Pythonic FP - Gadgets
-=====================
-
-PyPI project
-`pythonic-fp-gadgets
-<https://pypi.org/project/pythonic-fp-gadgets>`_.
+# Pythonic FP - Gadgets
 
 Library of simple, but useful, classes and functions with no dependencies
 outside the Python Standard Library.
 
-- Gadgets
+PyPI project
+[pythonic-fp-gadgets](https://pypi.org/project/pythonic-fp-gadgets).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
+
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/gadgets.html).
 
+- Gadgets
   - single item box
   - immutable wrapped (hashable) references
   - function returning iterator of its arguments
   - function to find the latest common ancestor of two classes
   - sentinel values
 
-Part of the
-`pythonic-fp
-<https://grscheller.github.io/pythonic-fp/>`_
-PyPI projects.
-
-Documentation
--------------
-
-Documentation and other links for this project are hosted on
-`GitHub Pages
-<https://grscheller.github.io/pythonic-fp/projects/gadgets.html>`_.
-
-Copyright and License
----------------------
+## Copyright and License
 
 Copyright (c) 2025-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

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

@@ -4,9 +4,10 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "pythonic-fp-gadgets"
-version = "4.0.4"
-readme = "README.rst"
-requires-python = ">=3.13"
+version = "4.2.0"
+description = "Gadgets without external Pythonic FP dependencies."
+readme = "README.md"
+requires-python = ">=3.13"  # syntactic floor: known to SyntaxError below this
 authors = [
   { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
 ]
@@ -14,32 +15,48 @@ keywords = [
   "gadgets",
 ]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Framework :: Pytest",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.14",  # tested: pytest test suite successful
   "Typing :: Typed",
 ]
 dependencies = []
-dynamic = ["description"]
 
 [project.urls]
-Changelog = "https://github.com/grscheller/pythonic-fp-gadgets/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp/projects/gadgets.html"
+Changelog = "https://github.com/grscheller/pythonic-fp-gadgets/blob/main/CHANGELOG.md"
+Documentation ="https://grscheller.github.io/pythonic-fp-gadgets/release/html/"
 Homepage = "https://grscheller.github.io/pythonic-fp/"
 Source = "https://github.com/grscheller/pythonic-fp-gadgets"
 
-[project.optional-dependencies]
+[dependency-groups]
+docs = [
+  "furo>=2025.12.19",
+  "sphinx>=9.1",
+]
+pub = [
+  "flit",
+]
 test = [
   "pytest>=8.4.1",
-  "pythonic-fp-circulararray>=6.0.4",
 ]
 
 [tool.flit.module]
 name = "pythonic_fp.gadgets"
 
+[tool.flit.sdist]
+exclude = [
+  "docs/",
+  "tests/",
+]
+
+[tool.pytest]
+addopts = ["-ra"]
+consider_namespace_packages = true
+testpaths = ["tests/"]
+
 [tool.mypy]
 explicit_package_bases = true
 local_partial_types = true
@@ -48,23 +65,12 @@ warn_redundant_casts = true
 warn_return_any = true
 warn_unused_configs = true
 
-[tool.pylsp-mypy]
-enabled = true
-live-mode = true
-dmypy = false
-strict = true
-report_progress = true
-
-[tool.pytest]
-addopts = [
-  "-ra",
-]
-consider_namespace_packages = true
-testpaths = ["tests/"]
-
 [tool.ruff]
 target-version = "py314"
 
+[tool.ruff.lint]
+ignore = ["RUF022", "E741"]
+
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
 
@@ -73,7 +79,6 @@ docstring-quotes = "double"
   "E731",
   "C901",
 ]
-"**/*.py" = ["E741"]
 
 [tool.ruff.format]
 quote-style = "single"

{pythonic_fp_gadgets-4.0.4 → pythonic_fp_gadgets-4.2.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.2.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.2.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)