dtools.fp 1.3.0__py3-none-any.whl

dtools/fp/singletons.py

@@ -0,0 +1,238 @@
+# Copyright 2023-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""### Module fp.singletons - collection of singleton classes
+
+Classes permitting at most only one instantiation. Safer, but not as performant,
+than a non-exported module level global. Difficult, but not impossible, for
+a typical end-user to exploit. Different versions tailored for different use
+cases.
+
+#### Singleton types:
+
+* **class NoValue:** singleton instance representing the absence of a value
+* **Class Sentinel:** singleton instances used as a "hidden" sentinel value
+* **class Nada:** singleton instance representing & propagating failure
+
+##### `NoValue` was designed as a None replacement
+
+While `None` represents "returned no values," `NoValue()` represents the absence
+of a value. Non-existing values should not be comparable to anything, even
+themselves. End-users may use both `None` and `()` as sentinel values which
+colliding with using either to represent "nothingness." 
+
+---
+
+##### `Sentinel` values used as hidden implementation details
+
+* Here is another implementation for Sentinel:``
+  * on GitHub: [taleinat/python-stdlib-sentinels](https://github.com/taleinat/python-stdlib-sentinels)
+  * on PyPI: [Project: Sentinels](https://pypi.org/project/sentinels/)
+  * see: [PEP 661](https://peps.python.org/pep-0661/)
+
+Initially this one was somewhat close to mine and also enabled pickling.
+Subsequently it was "enhanced" to allow sentinel values to be subclassed. My
+implementation is substantially more simple, python implementation independent,
+less Gang-of-Four OOP, and more Pythonic.
+
+---
+
+##### `Nada` propagates failure
+
+Nada is a singleton representing & propagating failure. Failure just blissfully
+propagates down "the happy path." For almost everything you do with it, it just
+returns itself. The maintainer has not used this construct enough yet to
+determine if it is a brilliant idea or a horrible blunder.
+"""
+from __future__ import annotations
+
+__all__ = [ 'NoValue', 'Sentinel', 'Nada' ]
+
+from collections.abc import Callable, Iterator
+from typing import Any, Final, final
+
+class NoValue():
+    """Singleton class representing a missing value.
+
+    * similar to `None` but
+      * while `None` represents "returned no values"
+      * `NoValue()` represents the absence of a value
+    * usage
+      * `import NoValue from dtools.fp.err_handling` and then
+        * either use `NoValue()` directly
+        * or define `_noValue: Final[NoValue] = NoValue()` don't export it
+      * compare using `is` and `is not`
+        * not `==` or `!=`
+        * `None` means returned no values, so `None == None` makes sense
+        * if one or both values are missing, then what is there to compare?
+
+    """
+    __slots__ = ()
+    _instance: NoValue|None = None
+
+    def __new__(cls) -> NoValue:
+        if cls._instance is None:
+            cls._instance = super(NoValue, cls).__new__(cls)
+        return cls._instance
+
+    def __init__(self) -> None:
+        return
+
+    def __repr__(self) -> str:
+        return 'NoValue()'
+
+    def __eq__(self, other: object) -> bool:
+        return False
+
+@final
+class Sentinel():
+    """Singleton classes representing a sentinel values.
+
+    * intended for library code, not to be exported/shared between modules
+      * otherwise some of its intended typing guarantees may be lost
+    * useful substitute for `None` as a hidden sentinel value
+      * allows `None` to be stored in data structures
+      * allows end users to choose to use `None` or `()` as sentinel values
+      * always equals itself (unlike `noValue`)
+    * usage
+      * import Sentinel and then either
+        * define `_my_sentinel: Final[Sentinel] = Sentinel('my_sentinel')`
+        * or use `Sentinel('my_sentinel')` directly
+      * compare using either
+        * `is` and `is not` or `==` and `!=`
+        * the `Sentinel()` value always equals itself
+        * and never equals anything else, especially other sentinel values
+
+    """
+    __slots__ = '_sentinel_name',
+    _instances: dict[str, Sentinel] = {}
+
+    def __new__(cls, sentinel_name: str) -> Sentinel:
+        if sentinel_name not in cls._instances:
+            cls._instances[sentinel_name] = super(Sentinel, cls).__new__(cls)
+        return cls._instances[sentinel_name]
+
+    def __init__(self, sentinel_name: str) -> None:
+        self._sentinel_name = sentinel_name
+        return
+
+    def __repr__(self) -> str:
+        return "Sentinel('" + self._sentinel_name + "')"
+
+@final
+class Nada():
+    """Singleton class representing & propagating failure.
+
+    * singleton `_nada: nada = Nada()` represents a non-existent value
+    * returns itself for arbitrary method calls
+    * returns itself if called as a Callable with arbitrary arguments
+    * interpreted as an empty container by standard Python functions
+    * warning: non-standard equality semantics
+      * comparison compares true only when 2 non-missing values compare true
+      * thus `a == b` means two non-missing values compare as equal
+    * usage
+      * import `Nada` and then
+        * either use `Nada()` directly
+        * or define `_nada: Final[Nada] = Nada()` don't export it
+      * start propagating failure by setting a propagating value to Nada()
+        * works best when working with expression
+        * failure may fail to propagate
+          * for a function/method with just side effects
+          * engineer Nada() to fail to trigger side effects
+      * test for failure by comparing a result to `Nada()` itself using
+        * `is` and `is not`
+      * propagate failure through a calculation using
+        * `==` and `!=`
+        * the `Nada()` value never equals itself
+        * and never equals anything else
+
+    """
+    __slots__ = ()
+    _instance: Nada|None = None
+    _hash: int = 0
+
+    sentinel: Final[Sentinel] = Sentinel('Nada')
+
+    def __new__(cls) -> Nada:
+        if cls._instance is None:
+            cls._instance = super(Nada, cls).__new__(cls)
+            cls._hash = hash((cls._instance, (cls._instance,)))
+        return cls._instance
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(())
+
+    def __hash__(self) -> int:
+        return self._hash
+
+    def __repr__(self) -> str:
+        return 'Nada()'
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __len__(self) -> int:
+        return 0
+
+    def __add__(self, right: Any) -> Nada:
+        return Nada()
+
+    def __radd__(self, left: Any) -> Nada:
+        return Nada()
+
+    def __mul__(self, right: Any) -> Nada:
+        return Nada()
+
+    def __rmul__(self, left: Any) -> Nada:
+        return Nada()
+
+    def __eq__(self, right: Any) -> bool:
+        return False
+
+    def __ne__(self, right: Any) -> bool:
+        return True
+
+    def __ge__(self, right: Any) -> bool:
+        return False
+
+    def __gt__(self, right: Any) -> bool:
+        return False
+
+    def __le__(self, right: Any) -> bool:
+        return False
+
+    def __lt__(self, right: Any) -> bool:
+        return False
+
+    def __getitem__(self, index: int|slice) -> Any:
+        return Nada()
+
+    def __setitem__(self, index: int|slice, item: Any) -> None:
+        return
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return Nada()
+
+    def __getattr__(self, name: str) -> Callable[..., Any]:
+        def method(*args: tuple[Any], **kwargs: dict[str, Any]) -> Any:
+            return Nada()
+        return method
+
+    def nada_get(self, alt: Any=sentinel) -> Any:
+        """Get an alternate value, defaults to `Nada()`."""
+        if alt == Sentinel('Nada'):
+            return Nada()
+        else:
+            return alt
+

dtools/fp/state.py

@@ -0,0 +1,107 @@
+# Copyright 2024-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""### Module fp.state - state monad
+
+Handling state functionally.
+
+#### Pure FP State handling type:
+
+* class **State**: A pure FP immutable implementation for the State Monad
+  * translated to Python from the book "Functional Programming in Scala"
+    * authors Chiusana & Bjarnason
+  * using `bind` instead of `flatmap`
+    * I feel `flatmap` is misleading for non-container-like monads
+    * flatmap name too long
+      * without do-notation code tends to march to the right
+      * `bind` for state monad is part of the user API
+        * shorter to type
+        * less of just an implementation detail
+
+"""
+from __future__ import annotations
+
+__all__ = [ 'State' ]
+
+from collections.abc import Callable
+from typing import Any, Never
+
+class State[S, A]():
+    """Data structure generating values while propagating changes of state.
+
+    * class `State` represents neither a state nor (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
+      * `bind` is sometimes called "flatmap"
+
+    """
+    __slots__ = 'run'
+
+    def __init__(self, run: Callable[[S], tuple[A, S]]) -> None:
+        self.run = run
+
+    def bind[B](self, g: Callable[[A], State[S, B]]) -> State[S, B]:
+        def compose(s: S) -> tuple[B, S]:
+            a, s1 = self.run(s)
+            return g(a).run(s1)
+        return State(lambda s: compose(s))
+
+    def map[B](self, f: Callable[[A], B]) -> State[S, B]:
+        return self.bind(lambda a: State.unit(f(a)))
+
+    def map2[B, C](self, sb: State[S, B], f: Callable[[A, B], C]) -> State[S, C]:
+        return self.bind(lambda a: sb.map(lambda b: f(a, b)))
+
+    def both[B](self, rb: State[S, B]) -> State[S, tuple[A, B]]:
+        return self.map2(rb, lambda a, b: (a, b))
+
+    @staticmethod
+    def unit[S1, B](b: B) -> State[S1, B]:
+        """Create a State action from a value."""
+        return State(lambda s: (b, s))
+
+    @staticmethod
+    def getState[S1]() -> State[S1, S1]:
+        """Set run action to return the current state
+
+        * the current state is propagated unchanged
+        * current value now set to current state
+
+        """
+        return State[S1, S1](lambda s: (s, s))
+
+    @staticmethod
+    def setState[S1](s: S1) -> State[S1, tuple[()]]:
+        """Manually set a state.
+
+        * the run action
+          * ignores previous state and swaps in a new state
+          * assigns a canonically meaningless value to current value
+
+        """
+        return State(lambda _: ((), s))
+
+    @staticmethod
+    def modifyState[S1](f: Callable[[S1], S1]) -> State[S1, tuple[()]]:
+        return State.getState().bind(lambda a: State.setState(f(a)))  #type: ignore
+
+ #   @staticmethod
+ #   def sequence[S1, A1](sas: list[State[S1, A1]])
+ #       """Combine a list of state actions into a state action of a list.
+
+ #       * all state actions must be of the same type
+
+ #       """
+

dtools_fp-1.3.0.dist-info/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

dtools_fp-1.3.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: dtools.fp
+Version: 1.3.0
+Summary: ### Package dtools.fp - Pythonic Functional Programming
+Keywords: functional,functional programming,fp,monad,iterators,maybe,either,lazy,non-strict
+Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+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: Typing :: Typed
+Requires-Dist: pytest >=8.3 ; extra == "test"
+Requires-Dist: dtools.circular-array >=3.9.0, < 3.10 ; extra == "test"
+Requires-Dist: dtools.datastructures >=0.25.0, < 0.26 ; extra == "test"
+Project-URL: Changelog, https://github.com/grscheller/dtools-fp/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/dtools-docs/fp
+Project-URL: Source, https://github.com/grscheller/dtools-fp
+Provides-Extra: test
+
+# Python Functional Programming (FP)
+
+Functional programming tools which endeavor to be Pythonic.
+
+* **Repositories**
+  * [dtools.fp][1] project on *PyPI*
+  * [Source code][2] on *GitHub*
+* Detailed documentation for dtools.fp
+  * [Detailed API documentation][3] on *GH-Pages*
+
+### Modules
+
+* grscheller.fp.iterables
+  * iteration tools implemented in Python
+* grscheller.fp.nothingness
+  * singleton classes representing either a
+    * missing value
+    * sentinel value
+    * failed calculation
+* grscheller.fp.err\_handling
+  * monadic tools for handling missing values & unexpected events
+
+### Benefits of FP
+
+* improved composability
+* avoid exception driven code paths
+* data sharing becomes trivial due to immutability
+
+---
+
+[1]: https://pypi.org/project/dtools.fp/
+[2]: https://github.com/grscheller/dtools-fp/
+[3]: https://grscheller.github.io/dtools-docs/fp/
+
+

dtools_fp-1.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+dtools/fp/__init__.py,sha256=OGd-av_1MLBt40mkyoGzxgIYCb7bxqTdqfRAqiUzV9g,1299
+dtools/fp/err_handling.py,sha256=PdqWTh9coHKzgK7jJ07OlXQfaDa0z9yu_-gJaZBO4mY,13660
+dtools/fp/function.py,sha256=TMz8tTy77C7KRVZv12ouumQdJK0dhYUnTYqqgb-hQxw,2455
+dtools/fp/iterables.py,sha256=gmqjUTrIylyEPzRhI3hOYaMvg5uISIEWHGaCedca38Q,13193
+dtools/fp/lazy.py,sha256=_DIU3qmwOwCU9m9RfJ4SbLeDSa4XRj2_FbW-MsT-o7E,4358
+dtools/fp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dtools/fp/singletons.py,sha256=bVp42bME7ym2S9kkC5140rJ5fOqBmTJIVYjQ1cPfsYA,8105
+dtools/fp/state.py,sha256=E88AJ5ixtjYAYRzzMwU5bZhAwH_l7zmdKPcDOEf9ib4,3570
+dtools_fp-1.3.0.dist-info/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+dtools_fp-1.3.0.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
+dtools_fp-1.3.0.dist-info/METADATA,sha256=Cgf9symLBGZ1rfGKKUzSlrYSqDRaPi0B-b8HOEfHjlQ,1958
+dtools_fp-1.3.0.dist-info/RECORD,,

dtools_fp-1.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.10.1
+Root-Is-Purelib: true
+Tag: py3-none-any