pythonic-fp.containers 4.0.1__py3-none-any.whl → 4.1.0__py3-none-any.whl

pythonic_fp/containers/__init__.py

@@ -13,16 +13,15 @@
 # limitations under the License.
 
 """
-Container with FP interfaces
-----------------------------
+Containers with FP interfaces
+-----------------------------
 
-+---------------------------------------------+-----------+------------------+
-| module                                      | class     | description      |
-+=============================================+===========+==================+
-| ``pythonic_fp.containers.functional_tuple`` | FTuple    | Functional Tuple |
-+---------------------------------------------+-----------+------------------+
-| ``pythonic_fp.containers.immutable_list``   | IList     | Immutable List   |
-+---------------------------------------------+-----------+------------------+
+.. admonition:: Functional variants of Python builtins
+
+    Not sure the direction this should take.
+
+    - class **FTuple:** A tuple-like object with a functional interface.
+    - class **IList:** An immutable, hashable list-like object.
 
 """
 

pythonic_fp/containers/functional_tuple.py

@@ -13,8 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - Functional Tuple"""
-
 from collections.abc import Callable, Iterator
 from typing import cast, Never, overload, SupportsIndex
 from pythonic_fp.iterables.folding import accumulate
@@ -25,26 +23,42 @@ __all__ = ['FTuple']
 
 class FTuple[D](tuple[D, ...]):
     """
-    .. admonition:: Functional Tuple suitable for inheritance.
+    .. admonition:: Functional Tuple
 
+        - intended for further inheritance
         - supports both indexing and slicing
         - int multiplication and FTuple addition supported
         - addition concatenates results, resulting in a Union type
         - both left and right int multiplication supported
         - homogeneous in its data type
-        - supports being further inherited from
         - unslotted
 
+        .. note::
+
+            Example of code very early in project. Different ways
+            to use __dunders__ than what I do lately.
+
     """
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: reverse iter
+
+            :yields: the tuples elements in reverse order
+
+        """
         for ii in range(len(self) - 1, -1, -1):
             yield (self[ii])
 
-    def __repr__(self) -> str:
-        return f'{self.__class__.__name__}(' + ', '.join(map(repr, self)) + ')'
-
     def __eq__(self, other: object, /) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            :param other: The ``object`` to which to be compared.
+            :returns: ``True`` if ``other`` is the same type and 
+                      corresponding elements compare as equal.
+
+        """
         if not isinstance(other, self.__class__):
             return False
         if (length := len(self)) != len(other):
@@ -67,6 +81,9 @@ class FTuple[D](tuple[D, ...]):
         else:
             return super().__getitem__(idx)
 
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}(' + ', '.join(map(repr, self)) + ')'
+
     def foldl[L](
         self,
         f: Callable[[L, D], L],
@@ -74,16 +91,20 @@ class FTuple[D](tuple[D, ...]):
         start: L | None = None,
         default: L | None = None,
     ) -> L:
-        """Fold Left with optional starting and default values.
+        """
+        .. admonition:: fold left
 
-        - fold left with an optional starting value
-        - first argument of function ``f`` is for the accumulated value
+            Reduce left with optional starting and default values.
 
-        :param f: The folding function, first argument is for the accumulated value.
-        :param start: An optional starting value.
-        :param default: An optional default value if fold does not exist.
-        :raises ValueError: When ``FTuple`` empty and a start value not given.
-        :returns: The folded value if it exists, otherwise the default value.
+            :param f: The folding function, first argument is for
+                      the accumulated value.
+            :param start: An optional starting value.
+            :param default: An optional default value
+                            if fold does not exist.
+            :raises ValueError: When ``FTuple`` empty and a start value
+                                was not not given.
+            :returns: Folded value if it exists, otherwise
+                      the default value if given.
 
         """
         it_self = iter(self)
@@ -107,13 +128,20 @@ class FTuple[D](tuple[D, ...]):
         start: R | None = None,
         default: R | None = None,
     ) -> R:
-        """Fold Right with optional starting and default values.
+        """
+        .. admonition:: fold right
 
-        :param f: The folding function, second argument is for the accumulated value.
-        :param start: An optional starting value.
-        :param default: An optional default value if fold does not exist.
-        :raises ValueError: when FTuple empty and a start value not given
-        :returns: The folded value if it exists, otherwise the default value.
+            Reduce right with optional starting and default values.
+
+            :param f: The folding function, second argument is for
+                    the accumulated value.
+            :param start: An optional starting value.
+            :param default: An optional default value
+                            if fold does not exist.
+            :raises ValueError: when ``FTuple`` empty and a start value
+                                was not given
+            :returns: The folded value if it exists, otherwise
+                      the default value if given.
 
         """
         it_self = reversed(self)
@@ -131,9 +159,13 @@ class FTuple[D](tuple[D, ...]):
         return acc
 
     def copy(self) -> 'FTuple[D]':
-        """Return a shallow copy of ``FTuple`` in O(1) time & space complexity.
+        """
+        .. admonition:: copy
 
-        :returns: New ``FTuple``.
+            Return a shallow copy of ``FTuple`` in O(1)
+            time & space complexity.
+
+            :returns: A new ``FTuple`` instance.
 
         """
         return self.__class__(self)
@@ -153,14 +185,12 @@ class FTuple[D](tuple[D, ...]):
     def accummulate[L](
         self, f: Callable[[L, D], L], s: L | None = None, /
     ) -> 'FTuple[L]':
-        """Accumulate partial folds.
-
-        Accumulate partial fold with an optional starting value,
-        results in an ``FTuple``.
+        """
+        .. admonition:: accumulate partial folds
 
-        :param f: Folding function used to produce partial folds.
-        :param s: Optional starting value.
-        :returns: New ``FTuple`` of the partial folds.
+            :param f: Folding function used to produce partial folds.
+            :param s: Optional starting value.
+            :returns: New ``FTuple`` of the partial folds.
 
         """
         if s is None:
@@ -168,6 +198,13 @@ class FTuple[D](tuple[D, ...]):
         return FTuple(accumulate(self, f, s))
 
     def map[U](self, f: Callable[[D], U], /) -> 'FTuple[U]':
+        """
+        .. admonition:: map
+
+            :param f: Folding function used to produce partial folds.
+            :returns: A new ``FTuple`` instance.
+
+        """
         return FTuple(map(f, self))
 
     def bind[U](
@@ -176,13 +213,17 @@ class FTuple[D](tuple[D, ...]):
         merge_type: MergeEnum = MergeEnum.Concat,
         yield_partials: bool = False,
     ) -> 'FTuple[U] | Never':
-        """Bind function ``f`` to the ``FTuple``.
+        """
+        .. admonition:: bind
+
+            Flat map function ``f`` with the ``FTuple`` with different
+            merging strategies.
 
-        :param f: Function ``D -> FTuple[U]``
-        :param merge_type: ``MergeEnum`` to determine how to merge the result. 
-        :param yield_partials: Yield unmatched values if ``MergeEnum`` given as merge type.
-        :return: Resulting ``FTuple``.
-        :raises ValueError: If given an unknown merge enumeration.
+            :param f: Function ``D -> FTuple[U]``
+            :param merge_type: ``MergeEnum`` to determine how to merge the result.
+            :param yield_partials: Yield unmatched values if ``MergeEnum`` given as merge type.
+            :returns: A new ``FTuple`` instance.
+            :raises ValueError: If given an unknown merge enumeration.
 
         """
         return FTuple(

pythonic_fp/containers/immutable_list.py

@@ -12,8 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - Immutable guaranteed hashable lists."""
-
 from collections.abc import Callable, Iterable, Iterator, Hashable
 from typing import cast, Never, overload
 from pythonic_fp.iterables.folding import accumulate
@@ -24,7 +22,7 @@ __all__ = ['IList']
 
 class IList[D](Hashable):
     """
-    .. admonition:: Immutable List like data structure.
+    .. admonition:: immutable list like data structure
 
         - hashability should be enforced by LSP tooling
         - hashability will be enforced at runtime
@@ -39,16 +37,18 @@ class IList[D](Hashable):
     __slots__ = ('_ds', '_len', '_hash')
     __match_args__ = ('_ds', '_len')
 
-    def __init__(self, *dss: Iterable[D]) -> None:
+    def __init__(self, *ds: Iterable[D]) -> None:
         """
-        :param dss: 0 or 1 iterables
+        .. admonition:: init
+
+            :param ds: One optional iterable.
 
         """
-        if (size := len(dss)) > 1:
+        if (size := len(ds)) > 1:
             msg = f'IList expects at most 1 iterable argument, got {size}'
             raise ValueError(msg)
         else:
-            self._ds: tuple[D, ...] = tuple(dss[0]) if size == 1 else tuple()
+            self._ds: tuple[D, ...] = tuple(ds[0]) if size == 1 else tuple()
             self._len = len(self._ds)
             try:
                 self._hash = hash((self._len, 42) + self._ds)
@@ -57,26 +57,55 @@ class IList[D](Hashable):
                 raise TypeError(msg)
 
     def __hash__(self) -> int:
+        """
+        .. admonition:: hash
+
+            Hashability enforced at runtime by initializer.
+
+            :returns: Hash value.
+
+        """
         return self._hash
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: iterate
+
+            Forward iterate, left to right.
+
+            :yields: The contained values.
+
+        """
         return iter(self._ds)
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: iterate
+
+            Reverse iterate, left to right.
+
+            :yields: The contained values in reverse order.
+
+        """
         return reversed(self._ds)
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: bool
+
+            :returns: ``True`` if not empty, ``False`` if empty.
+
+        """
         return bool(self._ds)
 
     def __len__(self) -> int:
-        return len(self._ds)
-
-    def __repr__(self) -> str:
-        return 'immutable_list(' + ', '.join(map(repr, self)) + ')'
+        """
+        .. admonition:: len
 
-    def __str__(self) -> str:
-        return '((' + ', '.join(map(repr, self)) + '))'
+            :returns: The number of items in the ``Ilist``.
 
+        """
+        return len(self._ds)
     def __eq__(self, other: object, /) -> bool:
         if not isinstance(other, IList):
             return NotImplemented  # magic object
@@ -92,10 +121,37 @@ class IList[D](Hashable):
     def __getitem__(self, idx: slice, /) -> 'IList[D]': ...
 
     def __getitem__(self, idx: slice | int, /) -> 'IList[D] | D':
+        """
+        .. admonition:: getitem
+
+            Indexable and sliceable but otherwise immutable.
+
+            :param idx: Either a ``slice`` or and ``index``.
+            :returns: A slice or the value.
+
+        """
         if isinstance(idx, slice):
             return IList(self._ds[idx])
         return self._ds[idx]
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            :returns: A string to reproduce the value.
+
+        """
+        return 'immutable_list(' + ', '.join(map(repr, self)) + ')'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            :returns: A string meaningful to an end user.
+
+        """
+        return '((' + ', '.join(map(repr, self)) + '))'
+
     def foldl[L](
         self,
         f: Callable[[L, D], L],
@@ -103,13 +159,16 @@ class IList[D](Hashable):
         start: L | None = None,
         default: L | None = None,
     ) -> L | None:
-        """Fold Left.
+        """
+        .. admonition:: fold left
 
-        :param f: Folding function, first argument is for the accumulated value.
-        :param start: Optional starting value.
-        :param default: Optional default value if fold does not exist.
-        :returns: Folded value.
-        :raises ValueError: When empty and a start value not given.
+            :param f: Folding function, first argument is for
+                      the accumulated value.
+            :param start: Optional starting value.
+            :param default: Optional default value if fold does not exist.
+            :returns: Left folded value.
+            :raises ValueError: When empty and neither a start value or
+                                default value not given.
 
         """
         it = iter(self._ds)
@@ -135,13 +194,16 @@ class IList[D](Hashable):
         start: R | None = None,
         default: R | None = None,
     ) -> R | None:
-        """Fold Right.
+        """
+        .. admonition:: fold right
 
-        :param f: Folding function, second argument is for the accumulated value.
-        :param start: Optional starting value.
-        :param default: Optional default value if fold does not exist.
-        :returns: Folded value.
-        :raises ValueError: When empty and a start value not given.
+            :param f: Folding function, second argument is for
+                    the accumulated value.
+            :param start: Optional starting value.
+            :param default: Optional default value if fold does not exist.
+            :returns: Right folded value.
+            :raises ValueError: When empty and neither a start value or
+                                default value not given.
 
         """
         it = reversed(self._ds)
@@ -161,6 +223,18 @@ class IList[D](Hashable):
         return acc
 
     def __add__(self, other: 'IList[D]', /) -> 'IList[D]':
+        """
+        .. admonition:: add by concatenation
+
+            :param other: The ``other`` same typed ``IList``.
+            :returns: New ``IList`` instance with concatenated values.
+            :raises ValueError: When ``other`` is not an ``IList``.
+
+            .. admonition:: TODO
+
+                Return ``NotImplemented`` if appropriate?
+
+        """
         if not isinstance(other, IList):
             msg = 'IList being added to something not an IList'
             raise ValueError(msg)
@@ -168,22 +242,45 @@ class IList[D](Hashable):
         return IList(concat(self, other))
 
     def __mul__(self, num: int, /) -> 'IList[D]':
+        """
+        .. admonition:: add by concatenation
+
+            :param other: The ``other`` same typed ``IList``.
+            :returns: New ``IList`` instance with concatenated values.
+            :raises ValueError: When ``other`` is not an ``IList``.
+
+            .. admonition:: TODO
+
+                Consider returning ``NotImplemented`` if appropriate?
+                Maybe define a "column vector" version?
+
+        """
         return IList(self._ds.__mul__(num if num > 0 else 0))
 
     def __rmul__(self, num: int, /) -> 'IList[D]':
+        """
+        .. admonition:: concatenation with itself
+
+            :param num: Number of times to concatenate ``IList``
+                        with itself.
+            :returns: A new ``IList`` instance with concatenated values.
+            :raises ValueError: When ``other`` is not an ``IList``.
+
+        """
         return IList(self._ds.__mul__(num if num > 0 else 0))
 
     def accummulate[L](
         self, f: Callable[[L, D], L], s: L | None = None, /
     ) -> 'IList[L]':
-        """Accumulate partial folds.
+        """
+        .. admonition:: accumulate partial folds
 
-        Accumulate partial fold with an optional starting value,
-        results in an ``IList``.
+            Accumulate partial fold with an optional starting value,
+            results in an ``IList``.
 
-        :param f: Folding function used to produce partial folds.
-        :param s: Optional starting value.
-        :returns: New ``FTuple`` of the partial folds.
+            :param f: Folding function used to produce partial folds.
+            :param s: Optional starting value.
+            :returns: New ``IList`` of the partial folds.
 
         """
         if s is None:
@@ -191,6 +288,13 @@ class IList[D](Hashable):
         return IList(accumulate(self, f, s))
 
     def map[U](self, f: Callable[[D], U], /) -> 'IList[U]':
+        """
+        .. admonition:: map
+
+            :parameter f: Function to map over the ``IList``.
+            :returns: A new ``IList`` instance with the mapped values.
+
+        """
         return IList(map(f, self))
 
     def bind[U](
@@ -199,13 +303,17 @@ class IList[D](Hashable):
         merge_enum: MergeEnum = MergeEnum.Concat,
         yield_partials: bool = False,
     ) -> 'IList[U] | Never':
-        """Bind function ``f`` to the ``IList``.
-
-        :param f: Function ``D -> IList[U]``
-        :param merge_type: ``MergeEnum`` to determine how to merge the result. 
-        :param yield_partials: Yield unmatched values if ``MergeEnum`` given as merge type.
-        :return: Resulting ``IList``.
-        :raises ValueError: If given an unknown merge enumeration.
+        """
+        .. admonition:: bind
+
+            :param f: Function ``D -> IList[U]`` to bind with different
+                      merge strategies.
+            :param merge_type: ``MergeEnum`` to determine how to merge
+                               the result.
+            :param yield_partials: Yield unmatched values if ``MergeEnum``
+                                   given as merge type.
+            :return: New ``IList`` instance.
+            :raises ValueError: If given an unknown merge enumeration.
 
         """
         return IList(

pythonic_fp/containers/immutable_list.pyi

@@ -7,7 +7,7 @@ __all__ = ['IList']
 
 class IList[D](Hashable):
     __match_args__: Incomplete
-    def __init__(self, *dss: Iterable[D]) -> None: ...
+    def __init__(self, *ds: Iterable[D]) -> None: ...
     def __hash__(self) -> int: ...
     def __iter__(self) -> Iterator[D]: ...
     def __reversed__(self) -> Iterator[D]: ...

{pythonic_fp_containers-4.0.1.dist-info → pythonic_fp_containers-4.1.0.dist-info}/METADATA

@@ -1,26 +1,26 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-containers
-Version: 4.0.1
-Summary: Container with FP interfaces
+Version: 4.1.0
+Summary: Containers with FP interfaces
 Keywords: functional_containers,functional_tuple,immutable_list
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Description-Content-Type: text/x-rst
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-circulararray>=6.0.1
+Requires-Dist: pythonic-fp-circulararray>=6.0.4
 Requires-Dist: pythonic-fp-fptools>=5.2.0
 Requires-Dist: pythonic-fp-iterables>=5.1.3
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-containers/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/containers/development/build/html/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/projects/containers.html
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-containers
 Provides-Extra: test
 
@@ -28,8 +28,8 @@ Pythonic FP - Containers
 ========================
 
 PyPI project
-`pythonic-fp.containers
-<https://pypi.org/project/pythonic-fp.containers>`_.
+`pythonic-fp-containers
+<https://pypi.org/project/pythonic-fp-containers>`_.
 
 Python package of container like data structures with functional
 programming inspired tweaks.
@@ -44,19 +44,19 @@ programming inspired tweaks.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
-Documentation for this project is hosted on
+Documentation and other links for this project are hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/containers>`_.
+<https://grscheller.github.io/pythonic-fp/projects/containers.html>`_.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.
 

pythonic_fp_containers-4.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pythonic_fp/containers/__init__.py,sha256=J1UvKHza0iDCR1GrVSUeps5LHsPc56xISvkbnGXOJtA,1034
+pythonic_fp/containers/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/containers/functional_tuple.py,sha256=3Vdg3Fri5wGDdWv4bomS7xqWLy0B_eMQuXojZhgvKYM,7498
+pythonic_fp/containers/functional_tuple.pyi,sha256=g8IvlIhPxecEsetEexZ7WmN9Ifdh-vAeK0z9SwLiCGE,1182
+pythonic_fp/containers/immutable_list.py,sha256=9qtSF5R7O2f-Dzji2G11CneC0BTrk3WA5EV3z2sdnms,9796
+pythonic_fp/containers/immutable_list.pyi,sha256=1p7w7FP-OpCHvCBJIlztoP_uUoZIoj9uI_XGKEib-kU,1371
+pythonic_fp/containers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_containers-4.1.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_containers-4.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_containers-4.1.0.dist-info/METADATA,sha256=I5j_6Nc6ykHEfx6ThA1S9x3ifqyHyYxdktbMw5wNr_w,2387
+pythonic_fp_containers-4.1.0.dist-info/RECORD,,

pythonic_fp_containers-4.0.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-pythonic_fp/containers/__init__.py,sha256=NVk-lAQNKGHTS0I_jEYrKTzfekisfgAoEOtwchgjemw,1346
-pythonic_fp/containers/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/containers/functional_tuple.py,sha256=re4ICQo-ZOyvlgUsC37_4eIk02l3dWRcX-Emfh9Us8A,6490
-pythonic_fp/containers/functional_tuple.pyi,sha256=g8IvlIhPxecEsetEexZ7WmN9Ifdh-vAeK0z9SwLiCGE,1182
-pythonic_fp/containers/immutable_list.py,sha256=iBFCUdIbROg4Ch2PoL8VZQl7gkZLwTGj54_cOQkhf4w,6920
-pythonic_fp/containers/immutable_list.pyi,sha256=HRm0Updbx9UJpl5RI0prOwimSHDUJtM-3t2hEmYz6kw,1372
-pythonic_fp/containers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp_containers-4.0.1.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
-pythonic_fp_containers-4.0.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_containers-4.0.1.dist-info/METADATA,sha256=2uAe6WJXCAyaEycqhowf5zZK6e8s02NIBDy1pFhKzuY,2384
-pythonic_fp_containers-4.0.1.dist-info/RECORD,,