pythonic-fp-fptools 5.0.0__tar.gz → 5.1.0__tar.gz

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/.gitignore

@@ -1,6 +1,7 @@
 # Minimal version - only add to when necessary
 **/__pycache__/
 dist/
+**/.dmypy.json
 **/.mypy_cache/
 **/.pytest_cache/
 **/.ruff_cache

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/CHANGELOG.rst

@@ -17,7 +17,14 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
-5.0.0 - TBD
+5.1.0 - TBD
+~~~~~~~~~~~
+
+Updated docstrings for new Sphinx docs structure. Probably just a PATCH release,
+made it a MINOR release due to introducing .pyi files.
+
+
+5.0.0 - 2025-08-02
 ~~~~~~~~~~~~~~~~~~
 
 Coordinated entire project pythonic-fp PyPI deployment.

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-fptools
-Version: 5.0.0
+Version: 5.1.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>
 Requires-Python: >=3.12
 Description-Content-Type: text/x-rst
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -14,10 +14,11 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-circulararray>=5.3.0
-Requires-Dist: pythonic-fp-singletons>=1.0.0
+Requires-Dist: pythonic-fp-booleans>=1.1.2
+Requires-Dist: pythonic-fp-circulararray>=5.3.3
+Requires-Dist: pythonic-fp-sentinels>=2.1.1
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Requires-Dist: pythonic-fp-containers>=3.0.0 ; extra == "test"
+Requires-Dist: pythonic-fp-containers>=3.0.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/releases.html
 Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
@@ -31,13 +32,16 @@ PyPI project
 `pythonic-fp.fptools
 <https://pypi.org/project/pythonic-fp.fptools>`_.
 
-Tools to aid with functional programming in Python yet still endeavoring to
-remain Pythonic.
+Tools to aid with functional programming in Python while still
+endeavoring to be Pythonic.
 
 - Functions as first class objects
 - Lazy (non-strict) function evaluation
 - Maybe monad - representing a possible missing value
-- Either monad - left bias either monad representing either a LEFT or RIGHT value
+- Either monad - representing either a LEFT or RIGHT value, not both
+
+  - left biased
+
 - State monad implementation
 
   - pure FP handling of state (the state monad)
@@ -45,13 +49,10 @@ remain Pythonic.
 
     - the monad encapsulates a state transformation, not a "state"
 
-This PyPI project is part of of the grscheller
+This PyPI project is part of the
 `pythonic-fp namespace projects
 <https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
 
-**Warning:** The maintainer intends to break out the first, forth and
-fifth modules to their own repos sometime in the near future.
-
 Documentation
 -------------
 

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/README.rst

@@ -5,13 +5,16 @@ PyPI project
 `pythonic-fp.fptools
 <https://pypi.org/project/pythonic-fp.fptools>`_.
 
-Tools to aid with functional programming in Python yet still endeavoring to
-remain Pythonic.
+Tools to aid with functional programming in Python while still
+endeavoring to be Pythonic.
 
 - Functions as first class objects
 - Lazy (non-strict) function evaluation
 - Maybe monad - representing a possible missing value
-- Either monad - left bias either monad representing either a LEFT or RIGHT value
+- Either monad - representing either a LEFT or RIGHT value, not both
+
+  - left biased
+
 - State monad implementation
 
   - pure FP handling of state (the state monad)
@@ -19,13 +22,10 @@ remain Pythonic.
 
     - the monad encapsulates a state transformation, not a "state"
 
-This PyPI project is part of of the grscheller
+This PyPI project is part of the
 `pythonic-fp namespace projects
 <https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
 
-**Warning:** The maintainer intends to break out the first, forth and
-fifth modules to their own repos sometime in the near future.
-
 Documentation
 -------------
 

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/pyproject.toml

@@ -1,10 +1,6 @@
-[build-system]
-requires = ["flit_core>=3.12,<4"]
-build-backend = "flit_core.buildapi"
-
 [project]
 name = "pythonic-fp-fptools"
-version = "5.0.0"
+version = "5.1.0"
 readme = "README.rst"
 requires-python = ">=3.12"
 license = { file = "LICENSE" }
@@ -20,7 +16,7 @@ keywords = [
   "non-strict",
 ]
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 3 - Alpha",
   "Framework :: Pytest",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
@@ -29,30 +25,37 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "pythonic-fp-circulararray>=5.3.0",
-  "pythonic-fp-singletons>=1.0.0",
+  "pythonic-fp-booleans>=1.1.2",
+  "pythonic-fp-circulararray>=5.3.3",
+  "pythonic-fp-sentinels>=2.1.1",
 ]
 dynamic = ["description"]
 
-[project.optional-dependencies]
-test = [
-  "pytest>=8.4.1",
-  "pythonic-fp-containers>=3.0.0",
-]
-
 [project.urls]
 Changelog = "https://github.com/grscheller/pythonic-fp-fptools/blob/main/CHANGELOG.rst"
 Documentation = "https://grscheller.github.io/pythonic-fp/fptools/development/build/html/releases.html"
 Homepage = "https://github.com/grscheller/pythonic-fp/blob/main/README.md"
 Source = "https://github.com/grscheller/pythonic-fp-fptools"
 
+[project.optional-dependencies]
+test = [
+  "pytest>=8.4.1",
+  "pythonic-fp-containers>=3.0.1",
+]
+
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
 [tool.flit.module]
 name = "pythonic_fp.fptools"
 
 [tool.mypy]
-enable_incomplete_feature = ["NewGenericSyntax"]
+enable_incomplete_feature = "NewGenericSyntax"
+explicit_package_bases = true
 implicit_reexport = false
 local_partial_types = true
+namespace_packages = true
 warn_redundant_casts = true
 warn_return_any = true
 warn_unused_configs = true
@@ -60,21 +63,25 @@ warn_unused_configs = true
 [tool.pylsp-mypy]
 enabled = true
 live-mode = true
+dmypy = false
 strict = true
 report_progress = true
 
 [tool.pytest.ini_options]
+addopts = "-ra"
 consider_namespace_packages = true
 testpaths = ["tests/"]
-addopts = "-ra"
 
 [tool.ruff]
 target-version = "py313"
-ignore = ["E741"]
 
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
 
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["C901"]
+"**/*.py" = ["E741"]
+
 [tool.ruff.format]
 quote-style = "single"
 docstring-code-line-length = 72

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/src/pythonic_fp/fptools/__init__.py

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - Functional Programming Tools
+"""
+Pythonic FP - Functional Programming Tools
+==========================================
 
 Functions as first class objects, Lazy (non-strict) function evaluation,
 and classical Functional Programming data structures.

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/src/pythonic_fp/fptools/either.py

@@ -12,46 +12,52 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import annotations
-
 __all__ = ['Either', 'LEFT', 'RIGHT']
 
 from collections.abc import Callable, Iterator, Sequence
-from typing import cast, Never, overload, TypeVar
-from pythonic_fp.singletons.sbool import SBool, Truth as Left, Lie as Right
-from pythonic_fp.singletons.sentinel import Sentinel as _Sentinel
+from typing import cast, overload
+from pythonic_fp.booleans.subtypable import SBool
 from .maybe import MayBe
 
-L = TypeVar('L', covariant=True)
-R = TypeVar('R', covariant=True)
 
-LEFT = Left('LEFT')
-RIGHT = Right('RIGHT')
+class EitherBool(SBool):
+    def __repr__(self) -> str:
+        if self:
+            return 'LEFT'
+        return 'RIGHT'
+
+
+LEFT = EitherBool(True)
+RIGHT = EitherBool(False)
 
 
 class Either[L, R]:
-    """Either monad, data structure semantically containing either a left
+    """
+    Either Monad
+    ------------
+
+    Data structure semantically containing either a left
     or a right value, but not both.
 
     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
 
-    - `True` if a left `Either`
-    - `False` if a right `Either`
+    - 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
 
       - 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::
 
@@ -60,31 +66,36 @@ class Either[L, R]:
 
     .. note::
 
-        ``Either(value: +L, side: Left): Either[+L, +R] -> left: Either[+L, +R]``
-        ``Either(value: +R, side: Right): Either[+L, +R] -> right: Either[+L, +R]``
+        ``Either(value: +L, side: Left): Either[L, R] -> left: Either[L, R]``
+        ``Either(value: +R, side: Right): Either[L, R] -> right: Either[L, R]``
 
     """
+
     __slots__ = '_value', '_side'
     __match_args__ = ('_value', '_side')
 
-    U = TypeVar('U', covariant=True)
-    V = TypeVar('V', covariant=True)
-    T = TypeVar('T')
-
     @overload
-    def __init__(self, value: L, side: Left) -> None: ...
+    def __init__(self, value: L) -> None: ...
     @overload
-    def __init__(self, value: R, side: Right) -> None: ...
-
-    def __init__(self, value: L | R, side: SBool = LEFT) -> None:
-        self._value = value
-        self._side = side
+    def __init__(self, value: L, side: EitherBool) -> None: ...
+    @overload
+    def __init__(self, value: R, side: EitherBool) -> None: ...
+
+    def __init__(self, value: L | R, side: EitherBool = LEFT) -> None:
+        self._value: L | R
+        self._side: EitherBool
+        if side:
+            self._value = value
+            self._side = LEFT
+        else:
+            self._value = value
+            self._side = RIGHT
 
     def __hash__(self) -> int:
-        return hash((_Sentinel('XOR'), self._value, self._side))
+        return hash((self, self._value, self._side))
 
     def __bool__(self) -> bool:
-        return self._side == LEFT
+        return self._side is LEFT
 
     def __iter__(self) -> Iterator[L]:
         if self:
@@ -118,7 +129,7 @@ class Either[L, R]:
 
         return False
 
-    def get(self) -> L | Never:
+    def get(self) -> L:
         """Get value if a left.
 
         .. warning::
@@ -127,8 +138,7 @@ class Either[L, R]:
             is a right. Best practice is to first check the ``Either`` in
             a boolean context.
 
-        :return: its value if a Left
-        :rtype: +L
+        :returns: its value if a Left
         :raises ValueError: if not a left
 
         """
@@ -138,10 +148,9 @@ class Either[L, R]:
         return cast(L, self._value)
 
     def get_left(self) -> MayBe[L]:
-        """Get value of `Either` if a left. Safer version of `get` method.
+        """Get value of ``Either`` if a left. Safer version of ``get`` method.
 
-        - if `Either` contains a left value, return it wrapped in a MayBe
-        - if `Either` contains a right value, return MayBe()
+        :returns: MayBe[L]
 
         """
         if self._side == LEFT:
@@ -149,47 +158,65 @@ class Either[L, R]:
         return MayBe()
 
     def get_right(self) -> MayBe[R]:
-        """Get value of `Either` if a right
+        """Get value of ``Either`` if a right.
 
-        - if `Either` contains a right value, return it wrapped in a MayBe
-        - if `Either` contains a left value, return MayBe()
+        :returns: MayBe[R]
 
         """
         if self._side == RIGHT:
             return MayBe(cast(R, self._value))
         return MayBe()
 
-    def map_right[V](self, f: Callable[[R], V]) -> Either[L, V]:
-        """Construct new Either with a different right."""
+    def map_right[V](self, f: Callable[[R], V]) -> 'Either[L, V]':
+        """Construct new Either with a different right.
+
+        :param f: function to map a right value
+        :returns: a new Either if a right, otherwise itself
+
+        """
         if self._side == LEFT:
             return cast(Either[L, V], self)
         return Either[L, V](f(cast(R, self._value)), RIGHT)
 
-    def map[U](self, f: Callable[[L], U]) -> Either[U, R]:
-        """Map over if a left value. Return new instance."""
+    def map[U](self, f: Callable[[L], U]) -> 'Either[U, R]':
+        """Map over if a left value. Return new instance.
+
+        :param f: function to map a left value
+        :returns: a new Either if a left, otherwise itself
+
+        """
         if self._side == RIGHT:
             return cast(Either[U, R], self)
         return Either(f(cast(L, self._value)), LEFT)
 
-    def bind[U](self, f: Callable[[L], Either[U, R]]) -> Either[U, R]:
-        """Flatmap over the left value, propagate right values."""
+    def bind[U](self, f: 'Callable[[L], Either[U, R]]') -> 'Either[U, R]':
+        """Flatmap over the left value, propagate right values.
+
+        :param f: function to flatmap a left value
+        :returns: a new Either if a left, otherwise itself
+
+        """
         if self:
             return f(cast(L, self._value))
         return cast(Either[U, R], self)
 
-    def map_except[U](self, f: Callable[[L], U], fallback_right: R) -> Either[U, R]:
+    def map_except[U](self, f: Callable[[L], U], fallback_right: R) -> 'Either[U, R]':
         """Map over if a left value - with fallback upon exception.
 
-        - if `Either` is a left then map `f` over its value
+        - if ``Either`` is a left then map ``f`` over its value
+
+          - if ``f`` returns normally, then return a left ``Either[U, R]``
+          - if ``f`` raises an exception, return right ``Either[U, R]``
 
-          - if `f` successful return a left `Either[+U, +R]`
-          - if `f` unsuccessful return right `Either[+U, +R]`
+        - if ``Either`` is a right
 
-            - swallows many exceptions `f` may throw at run time
+          - return new ``Either(right=self._right): Either[+U, +R]``
 
-        - if `Either` is a right
+        .. warning::
+            Swallows exceptions.
 
-          - return new `Either(right=self._right): Either[+U, +R]`
+        .. note
+            The fallback type must be the same type as the ``Either``
 
         """
         if self._side == RIGHT:
@@ -216,14 +243,19 @@ class Either[L, R]:
         return applied.get()
 
     def bind_except[U](
-        self, f: Callable[[L], Either[U, R]], fallback_right: R
-    ) -> Either[U, R]:
-        """Flatmap `Either` with function `f` with fallback right
+        self, f: 'Callable[[L], Either[U, R]]', fallback_right: R
+    ) -> 'Either[U, R]':
+        """Flatmap ``Either`` with function ``f`` with a fallback right
+        if exception is thrown.
 
         .. warning::
             Swallows exceptions.
 
+        .. note
+            The fallback type must be the same type as the ``Either``.
+
         :param fallback_right: fallback value if exception thrown
+        :returns: a successfully mapped left, a propagated right, or a right with fallback value
 
         """
         if self._side == RIGHT:
@@ -252,12 +284,12 @@ class Either[L, R]:
 
     @staticmethod
     def sequence[U, V](
-        sequence_xor_uv: Sequence[Either[U, V]],
-    ) -> Either[Sequence[U], V]:
-        """Sequence an indexable of type `Either[~U, ~V]`
+        sequence_xor_uv: 'Sequence[Either[U, V]]',
+    ) -> 'Either[Sequence[U], V]':
+        """Sequence a sequence subtype of Sequence[Either[U, V]]``
 
-        If the iterated `Either` values are all lefts, then return an `Either` of
-        an iterable of the left values. Otherwise return a right Either containing
+        If the iterated ``Either`` values are all lefts, then return an ``Either`` of
+        an iterable of the left values. Otherwise return a right ``Either`` containing
         the first right encountered.
 
         """

pythonic_fp_fptools-5.1.0/src/pythonic_fp/fptools/either.pyi

@@ -0,0 +1,36 @@
+from .maybe import MayBe
+from _typeshed import Incomplete
+from collections.abc import Callable, Iterator, Sequence
+from pythonic_fp.booleans.subtypable import SBool
+from typing import overload
+
+__all__ = ['Either', 'LEFT', 'RIGHT']
+
+class EitherBool(SBool): ...
+
+LEFT: Incomplete
+RIGHT: Incomplete
+
+class Either[L, R]:
+    __match_args__: Incomplete
+    @overload
+    def __init__(self, value: L) -> None: ...
+    @overload
+    def __init__(self, value: L, side: EitherBool) -> None: ...
+    @overload
+    def __init__(self, value: R, side: EitherBool) -> None: ...
+    def __hash__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[L]: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def get(self) -> L: ...
+    def get_left(self) -> MayBe[L]: ...
+    def get_right(self) -> MayBe[R]: ...
+    def map_right[V](self, f: Callable[[R], V]) -> Either[L, V]: ...
+    def map[U](self, f: Callable[[L], U]) -> Either[U, R]: ...
+    def bind[U](self, f: Callable[[L], Either[U, R]]) -> Either[U, R]: ...
+    def map_except[U](self, f: Callable[[L], U], fallback_right: R) -> Either[U, R]: ...
+    def bind_except[U](self, f: Callable[[L], Either[U, R]], fallback_right: R) -> Either[U, R]: ...
+    @staticmethod
+    def sequence[U, V](sequence_xor_uv: Sequence[Either[U, V]]) -> Either[Sequence[U], V]: ...

{pythonic_fp_fptools-5.0.0 → pythonic_fp_fptools-5.1.0}/src/pythonic_fp/fptools/function.py

@@ -12,11 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - FP tools for functions
-
-Not a replacement for the std library's `functools` which is more about
-modifying function behavior through decorators than functional composition
-and application.
+"""
+FP tools for functions
+======================
 
 FP utilities to manipulate and partially apply functions
 
@@ -27,7 +25,6 @@ FP utilities to manipulate and partially apply functions
 
 """
 
-from __future__ import annotations
 from collections.abc import Callable
 from typing import Any, ParamSpec
 
@@ -37,12 +34,29 @@ P = ParamSpec('P')
 
 
 def swap[U, V, R](f: Callable[[U, V], R]) -> Callable[[V, U], R]:
-    """Swap arguments of a two argument function."""
+    """
+    Swap args
+    ---------
+
+    Swap arguments of a two argument function.
+
+    :param f: Two argument function.
+    :returns: A version of ``f`` with its arguments swapped.
+
+    """
     return lambda v, u: f(u, v)
 
 
 def negate[**P](f: Callable[P, bool]) -> Callable[P, bool]:
-    """Take a predicate and return its negation."""
+    """
+    Negate predicate
+    ----------------
+
+    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)
@@ -51,7 +65,11 @@ def negate[**P](f: Callable[P, bool]) -> Callable[P, bool]:
 
 
 def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
-    """Convert a function with arbitrary positional arguments to one taking
+    """
+    Multi-to-single valued
+    ----------------------
+
+    Convert a function with arbitrary positional arguments to one taking
     a tuple of the original arguments.
 
     - was awaiting typing and mypy "improvements" to ParamSpec
@@ -59,11 +77,10 @@ def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
       - return type: Callable[tuple[P.args], R]   ???
       - return type: Callable[[tuple[P.args]], R] ???
 
-    - not going to happen, `see <https://github.com/python/mypy/pull/18278>`_
-
     TODO: Look into replacing this function with a Callable class?
 
     """
+
     def ff(tupled_args: tuple[Any]) -> R:
         return f(*tupled_args)
 
@@ -71,12 +88,17 @@ def sequenced[R](f: Callable[..., R]) -> Callable[[tuple[Any]], R]:
 
 
 def partial[**P, R](f: Callable[P, R], *args: Any) -> Callable[..., R]:
-    """Partially apply arguments to a function, left to right.
+    """
+    Partial application
+    -------------------
+
+    Partially apply arguments to a function, left to right.
 
     - type-wise the only thing guaranteed is the return type
     - best practice is to cast the result immediately
 
     """
+
     def finish(*rest: Any) -> R:
         return sequenced(f)(args + rest)
 

pythonic_fp_fptools-5.1.0/src/pythonic_fp/fptools/function.pyi

@@ -0,0 +1,11 @@
+from collections.abc import Callable
+from typing import Any, ParamSpec
+
+__all__ = ['swap', 'sequenced', 'partial', 'negate']
+
+P = ParamSpec('P')
+
+def swap[U, V, R](f: Callable[[U, V], R]) -> Callable[[V, U], 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]: ...