pythonic-fp-fptools 5.3.0__tar.gz → 5.4.0__tar.gz

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/.github/workflows/static.yml

@@ -6,8 +6,8 @@ on:
   workflow_dispatch:
 
 env:
-  RELEASE: '5.2.0'
-  DEVEL: '6.0.0'
+  RELEASE: '5.4.0'
+  DEVEL: '5.4.1'
   PYTHON: '3.14'
 
 permissions:

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/CHANGELOG.rst

@@ -17,11 +17,20 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
+PyPI 5.4.0 - 2026-05-16
+~~~~~~~~~~~~~~~~~~~~~~~
+
+EitherFlag changes.
+
+- bugfix: fixed ``__repr__`` method to properly work with ``eval()``
+- API addition: added a ``__str__`` method 
+
+Documentation now in maintenance mode.
+
 PyPI 5.3.0 - 2026-05-09
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-First PyPI release in over a year with actual substative code
-changes.
+First PyPI release in over a year with substantive code changes.
 
 - Finally happy with the Sphinx/Furo based documentation.
 - Fixed errors with MayBe and Either hashing.

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-fptools
-Version: 5.3.0
-Summary: Functional Programming Tools
+Version: 5.4.0
+Summary: .. admonition:: Functional programming tools for Python
 Keywords: either,fp,functional,functional programming,lazy,maybe,monad,non-strict
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/docs/Makefile

@@ -5,8 +5,8 @@
 #  - later needs to agree with pyproject.toml
 PROJECT_NAME = FP Tools Array
 PYPI_NAME = fptools
-RELEASE_VERSION = 5.3.0
-DEVEL_VERSION = 5.3.0
+RELEASE_VERSION = 5.4.0
+DEVEL_VERSION = 5.4.1
 CUSTOM_VERSION = 0.0.0
 
 SPHINXOPTS ?=

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/docs/gen_conf.py

@@ -101,6 +101,7 @@ html_theme_options = {{
 }}
 html_theme = 'furo'
 html_static_path = ['_static']
+html_css_files = ['custom.css']
 
 rst_epilog = """
 .. |RELEASE_STRING| replace:: {release_string}

pythonic_fp_fptools-5.4.0/docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    text-transform: none !important;
+}

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/docs/source/releases.rst

@@ -8,7 +8,9 @@ PyPI releases
 +=====================================================================================+==============+
 | `development <https://grscheller.github.io/pythonic-fp-fptools/development/html/>`_ |              |
 +-------------------------------------------------------------------------------------+--------------+
-| `v5.3.0 <https://grscheller.github.io/pythonic-fp-fptools/release/html/>`_          | 2026-05-09   |
+| `v5.4.0 <https://grscheller.github.io/pythonic-fp-fptools/release/html/>`_          | 2026-05-16   |
++-------------------------------------------------------------------------------------+--------------+
+| v5.3.0                                                                              | 2026-05-09   |
 +-------------------------------------------------------------------------------------+--------------+
 | v5.2.0                                                                              | 2026-01-13   |
 +-------------------------------------------------------------------------------------+--------------+

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "pythonic-fp-fptools"
-version = "5.3.0"
+version = "5.4.0"
 readme = "README.rst"
 requires-python = ">=3.13"
 authors = [

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/src/pythonic_fp/fptools/__init__.py

@@ -13,10 +13,7 @@
 # limitations under the License.
 
 """
-Functional Programming Tools
-============================
-
-.. admonition:: Functional programming tools for Python.
+.. admonition:: Functional programming tools for Python
 
     Functions as first class objects, Lazy (non-strict) function evaluation,
     and classical Functional Programming data structures.

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/src/pythonic_fp/fptools/either.py

@@ -20,8 +20,9 @@
 
     - Module implements a left biased either monad
 
-      - left value is intended for the "expected" result
-      - right value gives information on something "exceptional"
+      - Left values is intended for "expected" results.
+      - Right value gives information on the "unexpected"
+        perhaps "exceptional" result.
 
     - left and right values can be the same or different types
     - in a boolean context
@@ -39,7 +40,8 @@
 
     .. tip::
 
-        Right ``Either`` instances can be used as sentinel values.
+        Right Either instances, as well as LEFT and RIGHT EitherFlag,
+        can be used as hidden sentinel values.
 
 """
 
@@ -54,19 +56,44 @@ from .maybe import MayBe
 @final
 class EitherFlag(SBool):
     """
-    .. admonition:: Type for ``LEFT`` and ``RIGHT`` singleton flags
+    .. admonition:: LEFT and RIGHT singleton flags
 
-        Boolean-like type for signaling the ``Either`` initializer
-        to make a left or right ``Either`` instance.
+        Boolean-like type which can
+
+        - signal the Either initializer to create either
+          a left or right Either instance
+        - be combined like Booleans with Python bitwise operators
 
     """
 
     def __repr__(self) -> str:
         """
-        .. admonition:: string representation
+        .. admonition:: repr string
+
+            Construct one of two  strings:
+
+            - 'EitherFlag{True)' for the LEFT EitherFlag
+            - 'EitherFlag{False)' for the RIGHT EitherFlag
+
+            :returns: A string to construct the appropriate
+                      EitherFlag singleton.
+
+        """
+        if self:
+            return 'EitherFlag(True)'
+        return 'EitherFlag(False)'
+
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
 
-            Two values 'LEFT' or 'RIGHT' for the truthy and falsy
-            singletons respectfully. Also the default user strings.
+            Construct one of two strings:
+
+                - 'LEFT' for a ``LEFT`` EitherFlag
+                - 'RIGHT' for a ``RIGHT`` EitherFlag
+
+            :returns: A string meaningful to an end user.
 
         """
         if self:
@@ -76,17 +103,17 @@ class EitherFlag(SBool):
 
 LEFT: Final[EitherFlag] = EitherFlag(True)
 """
-.. admonition:: truthy Either flag
+.. admonition:: The truthy EitherFlag
 
-    Used by ``Either`` initializer to make a right ``Either``.
+    Used by the Either initializer to make a left Either.
 
 """
 
 RIGHT: Final[EitherFlag] = EitherFlag(False)
 """
-.. admonition:: falsy Either flag
+.. admonition:: The falsy EitherFlag
 
-    Used by ``Either`` initializer to make a right ``Either``.
+    Used by the Either initializer to make a right Either.
 
 """
 
@@ -94,17 +121,14 @@ RIGHT: Final[EitherFlag] = EitherFlag(False)
 @final
 class Either[L, R]:
     """
-    .. admonition:: Either monad
+    .. admonition:: either monad
 
         Left biased Either monad.
 
         - immutable semantics
         - contains either a "left" or a "right" item, but not both
         - hashable
-
-        .. important::
-
-            An ``Either`` is immutable once initialized.
+        - immutable
 
     """
 
@@ -120,13 +144,14 @@ class Either[L, R]:
 
     def __init__(self, value: L | R, side: EitherFlag = LEFT) -> None:
         """
-        .. admonition:: initializer
+        .. admonition:: init
 
-            Initialize ``Either`` instance as a "left" or a "right".
+            Initialize Either instance as a left or a right Either.
 
             :param value: The value contained in the ``Either``.
             :param side: Determines whether to produce
-                     a left or right ``Either``.
+                         a "left" or a "right" ``Either``.
+            :type side: EitherFlag
 
         """
         self._value: L | R
@@ -141,14 +166,15 @@ class Either[L, R]:
 
     def __hash__(self) -> int:
         """
-        .. admonition:: hashability
+        .. admonition:: hash
 
             If contained value hashable, use its hash value in
-            the hash calculation, otherwise use item's identity.
+            the hash calculation, otherwise use the value's identity.
 
-            - should be safe, the ``Either`` holds a reference to the value
-            - lazily calculates hash value, then caches it
-            - hash also depends if ``Either`` is a left or right
+            - Should be safe, the ``Either`` holds
+              a reference to the value.
+            - Lazily calculates hash value, then caches it.
+            - The hash also depends if the Either is a left or right.
 
         """
         if self._hash is None:
@@ -162,8 +188,11 @@ class Either[L, R]:
         """
         .. admonition:: bool
 
-            - left ``Either`` is truthy
-            - right ``Either`` is falsy
+            - left Eithers are truthy
+            - right Eithers are falsy
+
+            :returns: ``True`` if ``Either`` is a left,
+                      ``False`` if a right.
 
         """
         return self._side is LEFT
@@ -172,7 +201,9 @@ class Either[L, R]:
         """
         .. admonition:: len
 
-            Either always contains just one value.
+            An Either always contains just one value.
+
+            :returns: 1
 
         """
         return 1
@@ -181,9 +212,13 @@ class Either[L, R]:
         """
         .. admonition:: equality comparison
 
-            Compare ``Either`` to another object. Compare first
+            Compare Either to another object. Compare first
             by identity, then value.
 
+            :param other: The object to be compared.
+            :returns: True only if other is a Either of the same side
+                      containing objects which compare as equal.
+
         """
         if not isinstance(other, type(self)):
             return False
@@ -200,9 +235,11 @@ class Either[L, R]:
 
     def __iter__(self) -> Iterator[L]:
         """
-        .. admonition:: iterate
+        .. admonition:: iter
+
+            Yield the contained value if Either is a left.
 
-            Iterate ``value`` if a left ``Either``.
+            :yields: The contained value if a left.
 
         """
         if self:
@@ -219,6 +256,8 @@ class Either[L, R]:
 
             Where ``repr_value = repr(value)``.
 
+            :returns: A string to reproduce the ``Either``.
+
         """
         if self:
             return 'Either(' + repr(self._value) + ', LEFT)'
@@ -235,6 +274,8 @@ class Either[L, R]:
 
             Where ``str_value = str(value)``.
 
+            :returns: A string meaningful to an end user.
+
         """
         if self:
             return '< ' + str(self._value) + ' | >'
@@ -251,12 +292,12 @@ class Either[L, R]:
 
             .. warning::
 
-                Unsafe method ``get``. Will raise ``ValueError`` if ``Either``
+                Unsafe method get. Will raise ValueError if the Either
                 is a right.
 
                 .. tip::
 
-                    Best practice is to first check the ``Either`` in
+                    Best practice is to first check the Either in
                     a boolean context.
 
         """
@@ -271,7 +312,8 @@ class Either[L, R]:
 
             Get the value if a left.
 
-            :returns: ``MayBe[L]``
+            :returns: MayBe wrapping a left value.
+            :rtype: MayBe[L]
 
         """
         if self._side == LEFT:
@@ -284,7 +326,8 @@ class Either[L, R]:
 
             Get the value if a right.
 
-            :returns: ``MayBe[R]``
+            :returns: MayBe wrapping a right value.
+            :rtype: MayBe[R]
 
         """
         if self._side == RIGHT:
@@ -295,10 +338,11 @@ class Either[L, R]:
         """
         .. admonition:: map right
 
-            Map function ``f`` over the contents of a right ``Either``.
+            Map the function f over the contents of a right Either.
 
-            :param f: function to map a right value
-            :returns: A new ``Either`` if a right, otherwise ``self``.
+            :param f: A function to map a right value.
+            :returns: A new Either instance if a right,
+                      otherwise itself.
 
         """
         if self._side == LEFT:
@@ -309,10 +353,11 @@ class Either[L, R]:
         """
         .. admonition:: map
 
-            Map function ``f`` over left ``Either``.
+            Map the function f over a left Either.
 
-            :param f: Function used to map left values.
-            :returns: A new ``Either`` if a left, otherwise ``self``.
+            :param f: A function used to map a left value.
+            :returns: A new Either if a left,
+                      otherwise itself.
 
         """
         if self._side == RIGHT:
@@ -323,7 +368,8 @@ class Either[L, R]:
         """
         .. admonition:: map except
 
-            Map ``f`` over left ``Either`` with a right fallback upon exception.
+            Map function f over left Either with a right fallback
+            upon exception.
 
             :param f: Function used to map left values.
             :param fallback_right: Fallback value if exception thrown.
@@ -362,8 +408,7 @@ class Either[L, R]:
         """
         .. admonition:: bind
 
-            Flatmap function ``f`` over a left value. Propagate right
-            values.
+            Flatmap function f over a left value. Propagate right values.
 
             :param f: Function to bind.
             :returns: A new Either if a left, otherwise itself.
@@ -379,13 +424,13 @@ class Either[L, R]:
         """
         .. admonition:: bind except
 
-            Flatmap function ``f`` over ``Either``, with fallback upon
+            Flatmap function f over the Either, with fallback upon
             exception. Propagate right values.
 
             :param f: Function to bind over values.
             :param fallback_right: Fallback value if exception thrown.
             :returns: A successfully bound left, a propagated right,
-                    or a right with a fallback value.
+                      or a right with a fallback value.
 
             .. warning::
 
@@ -423,12 +468,11 @@ class Either[L, R]:
         """
         .. admonition:: sequence
 
-            ``Sequence[Either[U, V]]`` -> ``Either[Sequence[U], V]``
+            Sequence[Either[U, V]] -> Either[Sequence[U], V]
 
-            If all ``Either`` are lefts, then return an ``Either``
-            of the ``Sequence`` of contained left values. Otherwise
-            return a right ``Either`` containing the first right
-            encountered.
+            If all Either are lefts, then return an Either of the
+            Sequence of contained left values. Otherwise return
+            a right Either containing the first right encountered.
 
         """
         sequenced_list: list[U] = []

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/src/pythonic_fp/fptools/function.py

@@ -40,7 +40,7 @@ def swap[U, V, R](f: Callable[[U, V], R]) -> Callable[[V, U], R]:
         Swap arguments of a two argument function.
 
         :param f: Two argument function.
-        :returns: A version of ``f`` with its arguments swapped.
+        :returns: A version of f with its arguments swapped.
 
     """
     return lambda v, u: f(u, v)
@@ -52,8 +52,8 @@ def compose[D, T, R](f: Callable[[D], T], g: Callable[[T], R]) -> Callable[[D],
 
         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``.
+        :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))``
 
     """
@@ -66,7 +66,7 @@ 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
+        :param f: A function ``f`` which returns a bool
         :returns: the function ``not f``
 
     """
@@ -85,7 +85,7 @@ def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
 
         :param f: Function with just positional parameters
         :returns: An equivalent function taking a tuple of
-                  the arguments to ``f``.
+                  the arguments to f.
 
     """
     def ff(tupled_args: tuple[Any]) -> R:
@@ -102,7 +102,7 @@ def partial[**P, R](f: Callable[P, R], *args: Any) -> Callable[..., R]:
         arguments left to right.
 
         :param f: Function with just positional arguments.
-        :param args: Arguments to partially apply to ``f``.
+        :param args: Arguments to partially apply to f.
 
         .. warning::
 

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/src/pythonic_fp/fptools/lazy.py

@@ -19,7 +19,7 @@
 
     - *class* **Lazy** - Delay evaluation of single argument functions
     - *function* **lazy** - Delay evaluation of functions taking any number of arguments
-    - *function* **real_lazy** - Caching version of ``lazy``.
+    - *function* **real_lazy** - Caching version of lazy.
 
 """
 
@@ -40,8 +40,8 @@ class Lazy[D, R]:
 
         .. tip::
 
-            Make a function "non-strict" by passing some of
-            its arguments wrapped in Lazy instances.
+            Make functions "non-strict" by passing some of
+            their arguments wrapped in Lazy instances.
 
     """
 
@@ -54,9 +54,9 @@ class Lazy[D, R]:
             Delayed evaluation of a single argument function.
 
             :param f: Single argument function.
-            :param d: Argument to be passed to ``f``.
-            :param pure: If true, cache the result for future ``eval`` method calls.
-            :returns: A Lazy instance which can evaluate ``f(d)`` at a later time.
+            :param d: Argument to be passed to f.
+            :param pure: If true, cache the result for future eval method calls.
+            :returns: A Lazy instance which can evaluate f(d) at a later time.
 
         """
         self._f: Final[Callable[[D], R]] = f
@@ -72,8 +72,8 @@ class Lazy[D, R]:
 
             A Lazy becomes truthy when evaluated.
 
-            :returns: ``True`` when evaluated.
-            :returns: ``False`` when not evaluated.
+            :returns: True when evaluated.
+            :returns: False when not evaluated.
 
         """
         return self._evaluated
@@ -84,8 +84,8 @@ class Lazy[D, R]:
 
             Evaluate function with its argument.
 
-            - cache result or exception if ``pure is True``
-            - reevaluate if ``pure is False``
+            - Cache result or exception if pure is True.
+            - Reevaluate if pure is False.
 
         """
         if not (self._pure and self._evaluated):
@@ -110,9 +110,9 @@ class Lazy[D, R]:
 
             Check if a valid result was obtained.
 
-            :returns: ``MayBe()`` if not yet evaluated.
-            :returns: ``MayBe(True)`` if a result was gotten.
-            :returns: ``MayBe(False)`` if an exception was thrown.
+            :returns: MayBe() if not yet evaluated.
+            :returns: MayBe(True) if a result was gotten.
+            :returns: MayBe(False)` if an exception was thrown.
 
         """
         return self._exceptional.bind(lambda x: MayBe(not x))
@@ -123,9 +123,9 @@ class Lazy[D, R]:
 
             Check if exception thrown.
 
-            :returns: ``MayBe()`` if not yet evaluated.
-            :returns: ``MayBe(True)`` if an exception was thrown.
-            :returns: ``MayBe(False)`` if exception not thrown.
+            :returns: MayBe() if not yet evaluated.
+            :returns: MayBe(True) if an exception was thrown.
+            :returns: MayBe(False) if exception not thrown.
 
         """
         return self._exceptional
@@ -137,12 +137,12 @@ class Lazy[D, R]:
             Get result only if evaluated and no exceptions occurred,
             otherwise return an alternate value.
 
-            :param alt: Optional alternate value to return if ``Lazy``
+            :param alt: Optional alternate value to return if Lazy
                         is not evaluated or exceptional.
             :returns: The successfully evaluated result
-                      or `alt` if given.
-            :raises ValueError: if ``Lazy`` not evaluated,
-                                or exceptional and ``alt`` not given.
+                      or an alternate value if given.
+            :raises ValueError: If Lazy not evaluated or exceptional,
+                                and an alternate value not given.
 
         """
         if self._evaluated and self._result:
@@ -185,13 +185,13 @@ def lazy[**P, R](
     """
     .. 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``.
+        :param args: Positional arguments to be passed to f.
         :param kwargs: Any kwargs given are ignored.
-        :returns: a ``Lazy`` object wrapping the evaluation of ``f``
+        :returns: A Lazy instance wrapping the evaluation of f.
 
     """
     return Lazy(sequenced(f), args, pure=False)
@@ -203,13 +203,14 @@ def real_lazy[**P, R](
     """
     .. 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. The evaluation
+        is cached.
 
         :param f: Function whose evaluation is to be delayed.
-        :param args: Positional arguments to be passed to ``f``.
+        :param args: Positional arguments to be passed to f.
         :param kwargs: Any kwargs given are ignored.
-        :returns: a ``Lazy`` object wrapping the evaluation of ``f``
+        :returns: A Lazy instance wrapping the evaluation of f.
 
     """
     return Lazy(sequenced(f), args)

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/src/pythonic_fp/fptools/maybe.py

@@ -44,11 +44,11 @@ class MayBe[D]:
 
     def __init__(self, item: D | _Sentinel = _sentinel) -> None:
         """
-        .. admonition:: initialize
+        .. admonition:: init
 
-            Initialize ``MayBe`` with 1 or 0 items.
+            Initialize MayBe with 1 or 0 items.
 
-            :param item: Optional item for the ``MayBe``.
+            :param item: Optional item for the MayBe instance.
 
             .. important::
 
@@ -61,13 +61,13 @@ class MayBe[D]:
 
     def __hash__(self) -> int:
         """
-        .. admonition:: hashability
+        .. admonition:: hash
 
             If contained item hashable, use its hash value in
             the hash calculation, otherwise use item's identity.
 
-            - should be safe, the ``MayBe`` holds a reference to the item
-            - lazily calculates hash value, then caches it
+            - should be safe, the MayBe holds a reference to the item.
+            - Lazily calculates hash value, then caches it.
 
         """
         if self._hash is None:
@@ -84,6 +84,8 @@ class MayBe[D]:
 
             Truthy when not empty.
 
+            :returns: True if not empty, False if empty.
+
         """
         return self._item is not _sentinel
 
@@ -100,9 +102,11 @@ class MayBe[D]:
         """
         .. admonition:: equality comparison
 
-            Compare ``MayBe`` to another object. Compare first
+            Compare MayBe instance to another object. Compare first
             by identity, then value.
 
+            :returns: True only if other object is a MayBe with
+                      a corresponding item, or both empty.
         """
         if not isinstance(other, type(self)):
             return False
@@ -116,7 +120,7 @@ class MayBe[D]:
         """
         .. admonition:: iterate
 
-           :yields: The contained ``item`` if non-empty.
+           :yields: The contained item if non-empty.
 
         """
         if self:
@@ -124,13 +128,16 @@ class MayBe[D]:
 
     def __repr__(self) -> str:
         """
-        .. admonition:: representation string
+        .. admonition:: repr string
 
             Return the strings
 
-            :returns: 'MayBe()' if empty
-            :returns: 'MayBe(repr_item)' if not empty
-                      where ``repr_item = repr(item)``.
+            - 'MayBe()' if empty
+            - 'MayBe(repr_item)' if not empty
+
+            Where ``repr_item = repr(item)``.
+
+            :returns: A string to reproduce the MayBe.
 
         """
         if self:
@@ -148,6 +155,8 @@ class MayBe[D]:
 
             Where ``str_item = str(item)``.
 
+            :returns: A string meaningful to an end user.
+
         """
         if self:
             return 'MayBe(' + str(self._item) + ')'
@@ -165,19 +174,18 @@ class MayBe[D]:
             Return the item if it exists, otherwise an optional
             alternate item.
 
-            :param alt: Optional alternative item to return if``MayBe`` empty.
+            :param alt: Optional alternative item to return if MayBe empty.
             :returns: The item if it exists.
             :raises ValueError: When an alternate item is not provided but needed.
 
-
             .. warning::
 
-                Unsafe method ``get`` will raise ``ValueError`` if the
-                ``MayBe`` is empty and an ``alt`` return item not provided.
+                Unsafe method get will raise ValueError if the MayBe
+                is empty and an alternate return item not provided.
 
                 .. tip::
 
-                    Best practice is to first check the ``MayBe`` in
+                    Best practice is to first check the MayBe in
                     a boolean context.
 
         """
@@ -193,10 +201,11 @@ class MayBe[D]:
         """
         .. admonition:: Map
 
-            Map function ``f`` over the ``MayBe``.
+            Map function f over the MayBe.
 
             :param f: Function used for the map.
-            :returns: A new ``MayBe`` if not empty, otherwise ``self``.
+            :returns: A new MayBe instance if not empty,
+                      otherwise itself.
 
         """
         if self:
@@ -207,10 +216,11 @@ class MayBe[D]:
         """
         .. admonition:: Bind
 
-            Flatmap function ``f`` over the contained item, if it exists.
+            Flatmap function f over the MayBe.
 
             :param f: Function to bind.
-            :returns: A new ``MayBe`` if not empty, otherwise ``self``.
+            :returns: A new MayBe instance if not empty,
+                      otherwise itself.
 
         """
         return f(cast(D, self._item)) if self else cast(MayBe[U], self)

{pythonic_fp_fptools-5.3.0 → pythonic_fp_fptools-5.4.0}/src/pythonic_fp/fptools/state.py

@@ -30,16 +30,18 @@ class State[S, A]:
         .. note::
 
             A monad is a value in a context. The State monad wraps neither
-            a state nor a (value, state) pair. It wraps a transformation
-            ``old_state -> (value, new_state)`` called a "state action".
+            a state nor a ``(value, state)`` pair.
+
+            It wraps a transformation ``old_state -> (value, new_state)``
+            called a "state action".
 
             .. admonition:: Class State
 
                 Instance members:
 
-                - Property ``run`` is the **state action**
-                - Method ``bind`` performs state action composition
-                - Method ``eval`` is the **run action**
+                - Property *run* is the **state action**
+                - Method *bind* performs state action composition
+                - Method *eval* performs the **run action**
 
                   - the **run action** evaluates the **state action** by
 
@@ -48,17 +50,17 @@ class State[S, A]:
 
                 Static members:
 
-                - Method ``unit`` creates a ``State`` whose
-                  run action returns a given constant value.
-                - Method ``get`` creates a ``State`` whose
+                - Method unit creates a State instance whose
+                  run action returns the supplied constant value.
+                - Method get creates a State instance whose
                   run action returns the current state.
-                - Method ``set`` creates a ``State`` which
-                  ignores the old state and swaps in a new one.
-                - Method ``modify`` creates a ``State`` which
+                - Method set creates a State which ignores
+                  the old state and swaps in a new one.
+                - Method modify creates a State instance which
                   modifies the previous state via a function.
-                - Method ``sequence`` combine a list of ``States``
-                  into a ``State`` whose run action returns the
-                  list of generated values.
+                - Method sequence combine a list of State instances
+                  into a State whose run action returns the list
+                  of generated values.
 
     """
 
@@ -66,9 +68,11 @@ class State[S, A]:
 
     def __init__(self, run: Callable[[S], tuple[A, S]]) -> None:
         """
-        .. admonition:: initialize
+        .. admonition:: init
 
             :param run: State action.
+            :type run: ``S -> (A, S)`` where A is the type of the
+                       generated value and S is the type of a state.
 
         """
         self.run = run
@@ -108,13 +112,13 @@ class State[S, A]:
         """
         .. admonition:: map
 
-            Map function ``f`` over the resulting value of a
+            Map function f over the resulting value of a
             state action propagating the current state.
 
             :param f: Function to map.
-            :returns: A `State` whose run action produces ``f(a)``
-                      where ``a`` is the value produced by
-                      the run action of ``self``.
+            :returns: A new State instance whose run action produces f(a)
+                      where a is the value produced by the current State
+                      instance and just propagates the current state.
 
         """
         return self.bind(lambda a: State.unit(f(a)))
@@ -123,15 +127,14 @@ class State[S, A]:
         """
         .. admonition:: map2
 
-            Combine two state monads, ``self`` and ``sb``, with
-            a function. Resulting run action just propagates
-            the current state.
+            Combine two state monads, self and sb, with a function.
+            Resulting run action just propagates the current state.
 
-            :param sb: ``State`` to combine with ``self``.
+            :param sb: State instance to combine with the current instance.
             :param f: Function used by the resulting run action
                       on the values produced by the run actions
-                      of ``self`` and ``sb`` from the same initial
-                      state.
+                      of the current State instance and ``sb`` using
+                      the same initial state.
 
         """
         return self.bind(lambda a: sb.map(lambda b: f(a, b)))
@@ -140,11 +143,10 @@ class State[S, A]:
         """
         .. admonition:: both
 
-            Return a ``State`` whose run action returns a tuple
-            from from the run actions from .
+            Return a State instance whose run action returns a tuple
+            from from the run actions of the current State and sb.
 
-            :param sb: ``State`` to combine with ``self`` for the
-                       second element of tuple produced by run action.
+            :param sb: A State instance to be combined with the current one.
 
         """
         return self.map2(rb, lambda a, b: (a, b))
@@ -155,10 +157,10 @@ class State[S, A]:
         .. admonition:: unit
 
             Create a State whose run action returns the given
-            constant ``b``  and propagate the present state.
+            constant b  and propagate the present state.
 
             :param b: Value the new State's run action will return.
-            :returns: A new ``State[ST, B]`` from a value ``b: B``.
+            :returns: A new State[ST, B] from a value b: B.
 
         """
         return State(lambda s: (b, s))
@@ -197,6 +199,8 @@ class State[S, A]:
             :param s: The state to swap in for current state
             :returns: State monad wrapping a state action which ignores
                       any initial state passed in when evaluated.
+            :rtype: State[ST, tuple[()]]
+
         """
         return State(lambda _: ((), s))
 
@@ -206,16 +210,18 @@ class State[S, A]:
         .. admonition:: modify
 
             Modify previous state with a function. Like put, but modify
-            previous state via ``f``.
+            previous state via f.
 
             :param f: Function to modify the current state.
             :returns: A State monad with a modified state.
+            :rtype: State[ST, tuple[()]]
 
             .. note::
 
                 Will need type annotation. Static type checkers like
                 mypy have no *a priori* knowledge of what ``ST``
                 could be.
+
         """
         return State.get().bind(lambda a: State.put(f(a)))  # type: ignore
 
@@ -229,7 +235,10 @@ class State[S, A]:
             run action from the original list.
 
             :param sas: A list of state monads all of type ``State[ST, AA]``.
-            :returns: A state monad of type ``State[ST, list[AA]]``.
+            :returns: A state monad whose run action produces a list of
+                      the values produced by the list of State actions
+                      provided to the method.
+            :rtype: State[ST, list[AA]]
  
             .. note::