pythonic-fp-fptools 5.1.2__tar.gz → 5.2.0__tar.gz

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/CHANGELOG.rst

@@ -17,6 +17,16 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
+PyPI 5.2.0 - 2026-01-13
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Added function.compose back on 2025-12-04. Docstring updates for Sphinx.
+
+PyPI 5.1.2 - 2025-09-28
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Patch bump for pythonic-fp PyPI coordinated release 3.3.3.
+
 PyPI 5.1.1 - 2025-09-09
 ~~~~~~~~~~~~~~~~~~~~~~~
 

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-fptools
-Version: 5.1.2
+Version: 5.2.0
 Summary: Pythonic FP - Functional Programming Tools
 Keywords: either,fp,functional,functional programming,lazy,maybe,monad,non-strict
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
@@ -14,13 +14,13 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-booleans>=2.0.0
-Requires-Dist: pythonic-fp-circulararray>=6.0.0
-Requires-Dist: pythonic-fp-gadgets>=3.1.0
+Requires-Dist: pythonic-fp-booleans>=2.1.1
+Requires-Dist: pythonic-fp-circulararray>=6.0.1
+Requires-Dist: pythonic-fp-gadgets>=4.0.2
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Requires-Dist: pythonic-fp-containers>=4.0.0 ; extra == "test"
-Requires-Dist: pythonic-fp-iterables>=5.1.2 ; extra == "test"
-Requires-Dist: pythonic-fp-queues>=4.1.0 ; extra == "test"
+Requires-Dist: pythonic-fp-containers>=4.0.1 ; extra == "test"
+Requires-Dist: pythonic-fp-iterables>=5.1.3 ; extra == "test"
+Requires-Dist: pythonic-fp-queues>=5.1.1 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-fptools/blob/main/CHANGELOG.rst
 Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/fptools/development/build/html/
 Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
@@ -53,7 +53,7 @@ endeavoring to be Pythonic.
 
 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
@@ -61,7 +61,7 @@ Documentation
 
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/fptools/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp/fptools>`_.
 
 Copyright and License
 ---------------------

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/README.rst

@@ -24,7 +24,7 @@ endeavoring to be Pythonic.
 
 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
@@ -32,7 +32,7 @@ Documentation
 
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/fptools/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp/fptools>`_.
 
 Copyright and License
 ---------------------

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythonic-fp-fptools"
-version = "5.1.2"
+version = "5.2.0"
 readme = "README.rst"
 requires-python = ">=3.12"
 license = { file = "LICENSE" }
@@ -25,9 +25,9 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "pythonic-fp-booleans>=2.0.0",
-  "pythonic-fp-circulararray>=6.0.0",
-  "pythonic-fp-gadgets>=3.1.0",
+  "pythonic-fp-booleans>=2.1.1",
+  "pythonic-fp-circulararray>=6.0.1",
+  "pythonic-fp-gadgets>=4.0.2",
 ]
 dynamic = ["description"]
 
@@ -40,9 +40,9 @@ Source = "https://github.com/grscheller/pythonic-fp-fptools"
 [project.optional-dependencies]
 test = [
   "pytest>=8.4.1",
-  "pythonic-fp-containers>=4.0.0",
-  "pythonic-fp-iterables>=5.1.2",
-  "pythonic-fp-queues>=4.1.0",
+  "pythonic-fp-containers>=4.0.1",
+  "pythonic-fp-iterables>=5.1.3",
+  "pythonic-fp-queues>=5.1.1",
 ]
 
 [build-system]

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/either.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__all__ = ['Either', 'LEFT', 'RIGHT']
+__all__ = ['Either', 'EitherBool', 'LEFT', 'RIGHT']
 
 from collections.abc import Callable, Iterator, Sequence
 from typing import cast, overload
@@ -21,6 +21,12 @@ from .maybe import MayBe
 
 
 class EitherBool(SBool):
+    """Boolean-like type used by Either constructor.
+
+    - A "truthy" value passed to constructor produces the unique ``LEFT`` value.
+    - A "falsy" value passed to constructor produces the unique ``RIGHT`` value.
+
+    """
     def __repr__(self) -> str:
         if self:
             return 'LEFT'
@@ -28,36 +34,38 @@ class EitherBool(SBool):
 
 
 LEFT = EitherBool(True)
+"""Singleton value signaling ``Either`` constructor to produce a ``LEFT`` Either, the default."""
+
 RIGHT = EitherBool(False)
+"""Singleton value signaling ``Either`` constructor to produce a ``RIGHT`` Either."""
 
 
 class Either[L, R]:
     """
-    Either Monad
-    ------------
+    .. admonition:: Either Monad
 
-    Data structure semantically containing either a left
-    or a right value, but not both.
+        Data structure semantically containing either a left
+        or a right value, but not both.
 
-    Implements a left biased Either Monad.
+        Implements a left biased Either Monad.
 
-    - ``Either(value: +L, LEFT)`` produces a left ``Either``
-    - ``Either(value: +L, RIGHT)`` produces a right ``Either``
+        - ``Either(value: +L, LEFT)`` produces a left ``Either``
+        - ``Either(value: +L, RIGHT)`` produces a right ``Either``
 
-    In a Boolean context
+        In a Boolean context
 
-    - A left ``Either`` is "truthy"
-    - A right ``Either`` is "falsy"
+        - A left ``Either`` is "truthy"
+        - A right ``Either`` is "falsy"
 
-    Two ``Either`` objects compare as equal when
+        Two ``Either`` objects compare as equal when
 
-    - both are left values or both are right values whose values
+        - both are left values or both are right values whose values
 
-      - are the same object
-      - compare as equal
+        - are the same object
+        - compare as equal
 
-    Immutable, an ``Either`` does not change after being created.
-    Therefore ``map`` & ``bind`` return new instances.
+        Immutable, an ``Either`` does not change after being created.
+        Therefore ``map`` & ``bind`` return new instances.
 
     .. warning::
 

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/either.pyi

@@ -4,7 +4,7 @@ from collections.abc import Callable, Iterator, Sequence
 from pythonic_fp.booleans.subtypable import SBool
 from typing import overload
 
-__all__ = ['Either', 'LEFT', 'RIGHT']
+__all__ = ['Either', 'EitherBool', 'LEFT', 'RIGHT']
 
 class EitherBool(SBool): ...
 

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/function.py

@@ -13,32 +13,28 @@
 # limitations under the License.
 
 """
-FP tools for functions
-======================
+.. admonition:: FP tools for functions
 
-FP utilities to manipulate and partially apply functions
+    FP utilities to manipulate and partially apply functions.
 
-- *function* **swap** - Swap the arguments of a 2 argument function
-- *function* **sequenced** - Convert function to take a sequence of its arguments
-- *function* **negate** - Transforms a predicate to its negation
-- *function* **partial** - Returns a partially applied function
+    - *function* **swap** - Swap the arguments of a 2 argument function
+    - *function* **compose** - Function composition
+    - *function* **negate** - Transforms a predicate to its negation
+    - *function* **sequenced** - Convert function to take a sequence of its arguments
+    - *function* **partial** - Returns a partially applied function
 
 """
 
 from collections.abc import Callable
 from typing import Any, ParamSpec
 
-__all__ = ['swap', 'sequenced', 'partial', 'negate']
+__all__ = ['swap', 'compose', 'negate', 'sequenced', 'partial']
 
 P = ParamSpec('P')
 
 
 def swap[U, V, R](f: Callable[[U, V], R]) -> Callable[[V, U], R]:
-    """
-    Swap args
-    ---------
-
-    Swap arguments of a two argument function.
+    """Swap arguments of a two argument function.
 
     :param f: Two argument function.
     :returns: A version of ``f`` with its arguments swapped.
@@ -47,17 +43,23 @@ def swap[U, V, R](f: Callable[[U, V], R]) -> Callable[[V, U], R]:
     return lambda v, u: f(u, v)
 
 
-def negate[**P](f: Callable[P, bool]) -> Callable[P, bool]:
+def compose[D, T, R](f: Callable[[D], T], g: Callable[[T], R]) -> Callable[[D], R]:
+    """Function Composition
+
+    :param f: Function called first with domain D and range T.
+    :param g: Function called on result with domain T and range R.
+    :returns: The composite function g∘f(d) = g(f(d))
+
     """
-    Negate predicate
-    ----------------
+    return lambda d: g(f(d))
+
 
-    Take a predicate and return its negation.
+def negate[**P](f: Callable[P, bool]) -> Callable[P, bool]:
+    """Take a predicate and return its negation.
 
     :param f: a function ``f`` which returns a bool
     :returns: the function ``not f``
     """
-
     def ff(*args: P.args, **kwargs: P.kwargs) -> bool:
         return not f(*args, **kwargs)
 
@@ -65,9 +67,7 @@ def negate[**P](f: Callable[P, bool]) -> Callable[P, bool]:
 
 
 def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
-    """
-    Multi-to-single valued
-    ----------------------
+    """Convert a function from multi-to-single valued.
 
     Convert a function with arbitrary positional arguments to one taking
     a tuple of the original arguments.
@@ -80,7 +80,6 @@ def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
     TODO: Look into replacing this function with a Callable class?
 
     """
-
     def ff(tupled_args: tuple[Any]) -> R:
         return f(*tupled_args)
 
@@ -88,9 +87,7 @@ def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
 
 
 def partial[**P, R](f: Callable[P, R], *args: Any) -> Callable[..., R]:
-    """
-    Partial application
-    -------------------
+    """Partial function application.
 
     Partially apply arguments to a function, left to right.
 
@@ -98,7 +95,6 @@ def partial[**P, R](f: Callable[P, R], *args: Any) -> Callable[..., R]:
     - best practice is to cast the result immediately
 
     """
-
     def finish(*rest: Any) -> R:
         return sequenced(f)(args + rest)
 

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/function.pyi

@@ -1,11 +1,12 @@
 from collections.abc import Callable
 from typing import Any, ParamSpec
 
-__all__ = ['swap', 'sequenced', 'partial', 'negate']
+__all__ = ['swap', 'compose', 'negate', 'sequenced', 'partial']
 
 P = ParamSpec('P')
 
 def swap[U, V, R](f: Callable[[U, V], R]) -> Callable[[V, U], R]: ...
+def compose[D, T, R](f: Callable[[D], T], g: Callable[[T], R]) -> Callable[[D], R]: ...
 def negate[**P](f: Callable[P, bool]) -> Callable[P, bool]: ...
 def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]: ...
 def partial[**P, R](f: Callable[P, R], *args: Any) -> Callable[..., R]: ...

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/lazy.py

@@ -13,17 +13,16 @@
 # limitations under the License.
 
 """
-Lazy function evaluation
-========================
+.. admonition:: Lazy function evaluation
 
-Delayed function evaluations. FP tools for "non-strict" function evaluations.
-Useful to delay a function's evaluation until some inner scope.
+    Delayed function evaluations. FP tools for "non-strict" function evaluations.
+    Useful to delay a function's evaluation until some inner scope.
 
-Non-strict delayed function evaluation.
+    Non-strict delayed function evaluation.
 
-- *class* **Lazy** - Delay evaluation of functions taking & returning single values
-- *function* **lazy** - Delay evaluation of functions taking any number of values
-- *function* **real_lazy** - Version of ``lazy`` which caches its result
+    - *class* **Lazy** - Delay evaluation of functions taking & returning single values
+    - *function* **lazy** - Delay evaluation of functions taking any number of values
+    - *function* **real_lazy** - Version of ``lazy`` which caches its result
 
 """
 
@@ -38,14 +37,13 @@ __all__ = ['Lazy', 'lazy', 'real_lazy']
 
 class Lazy[D, R]:
     """
-    Non-strict function evaluation
-    ------------------------------
+    .. admonition:: Non-strict function evaluation
 
-    Delayed evaluation of a singled valued function.
+        Delayed evaluation of a singled valued function.
 
-    Class instance delays the executable of a function where ``Lazy(f, arg)``
-    constructs an object that can evaluate the Callable ``f`` with its argument
-    at a later time.
+        Class instance delays the executable of a function where ``Lazy(f, arg)``
+        constructs an object that can evaluate the Callable ``f`` with its argument
+        at a later time.
 
     .. note::
 
@@ -153,11 +151,10 @@ def lazy[**P, R](
     f: Callable[P, R], *args: P.args, **kwargs: P.kwargs
 ) -> Lazy[tuple[Any, ...], R]:
     """
-    Delayed evaluations
-    -------------------
+    .. admonition:: Delayed evaluations
 
-    Function returning a delayed evaluation of a function of an arbitrary number
-    of positional arguments.
+        Function returning a delayed evaluation of a function of an arbitrary number
+        of positional arguments.
 
     :param f: Function whose evaluation is to be delayed.
     :param args: Positional arguments to be passed to ``f``.
@@ -172,11 +169,10 @@ def real_lazy[**P, R](
     f: Callable[P, R], *args: P.args, **kwargs: P.kwargs
 ) -> Lazy[tuple[Any, ...], R]:
     """
-    Cached Delayed evaluations
-    --------------------------
+    .. admonition:: Cached Delayed evaluations
 
-    Function returning a delayed evaluation of a function of an arbitrary number
-    of positional arguments. Evaluation is cached.
+        Function returning a delayed evaluation of a function of an
+        arbitrary number of positional arguments. Evaluation is cached.
 
     :param f: Function whose evaluation is to be delayed.
     :param args: Positional arguments to be passed to ``f``.

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/maybe.py

@@ -23,18 +23,17 @@ from pythonic_fp.gadgets.sentinels.flavored import Sentinel
 
 class MayBe[D]:
     """
-    Maybe Monad
-    -----------
+    .. admonition:: Maybe Monad
 
-    Data structure wrapping a potentially missing item.
+        Data structure wrapping a potentially missing item.
 
-    Immutable semantics
+        Immutable semantics
 
-    - can store any item of any type, including ``None``
+        - can store any item of any type, including ``None``
 
-      - with one hidden implementation dependent exception
+        - with one hidden implementation dependent exception
 
-    - immutable semantics, therefore covariant
+        - immutable semantics
 
     .. warning::
 

{pythonic_fp_fptools-5.1.2 → pythonic_fp_fptools-5.2.0}/src/pythonic_fp/fptools/state.py

@@ -20,17 +20,16 @@ from pythonic_fp.circulararray.auto import CA
 
 class State[S, A]:
     """
-    State Monad
-    -----------
+    .. admonition:: State Monad
 
-    Data structure generating values while propagating changes of state.
-    A pure FP implementation for the State Monad
+        Data structure generating values while propagating changes of state.
+        A pure FP implementation for the State Monad
 
-    - class ``State`` represents neither a state nor (value, state) pair
+        - class ``State`` represents neither a state nor a (value, state) pair
 
-      - it wraps a transformation old_state -> (value, new_state)
-      - the ``run`` method is this wrapped transformation
-      - ``bind`` is just state propagating function composition
+        - it wraps a transformation old_state -> (value, new_state)
+        - the ``run`` method is this wrapped transformation
+        - ``bind`` is just state propagating function composition
 
     """