pythonic-fp-booleans 3.0.2__tar.gz → 4.1.0__tar.gz

{pythonic_fp_booleans-3.0.2 → pythonic_fp_booleans-4.1.0}/PKG-INFO

@@ -1,53 +1,48 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pythonic-fp-booleans
-Version: 3.0.2
-Summary: Subtypable Boolean Class Hierarchy
+Version: 4.1.0
+Summary: True Booleans which are subtypable.
 Keywords: booleans,subtypable
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13
-Description-Content-Type: text/x-rst
+Description-Content-Type: text/markdown
 Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: pythonic-fp-gadgets>=4.0.2
-Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-booleans/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-booleans/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/html/
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-booleans/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-booleans/release/html/
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-booleans
-Provides-Extra: test
+Import-Name: pythonic_fp.booleans
+Import-Namespace: pythonic_fp
 
-Pythonic FP - Booleans
-======================
-
-PyPI project
-`pythonic-fp-booleans
-<https://pypi.org/project/pythonic-fp-booleans>`_.
+# Pythonic FP - Booleans
 
 Subtypable Boolean like classes.
 
-While still compatible with Python shortcut logic, these singleton classes
-can be non-shortcut logically composed with Python’s bitwise operators.
-
+PyPI project
+[pythonic-fp-booleans](https://pypi.org/project/pythonic-fp-booleans).
 Part of the
-`pythonic-fp
-<https://grscheller.github.io/pythonic-fp>`_
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
 PyPI projects.
 
-Documentation
--------------
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/booleans.html).
 
-Documentation for this project is hosted on
-`GitHub Pages
-<https://grscheller.github.io/pythonic-fp-booleans>`_.
+While still compatible with Python shortcut logic, these singleton
+classes can be non-shortcut logically composed with Python’s bitwise
+operators. Unlike Python booleans which bitwise compose as integers,
+these compose as true Booleans in a contravariant way.
 
-Copyright and License
----------------------
+## Copyright and License
 
 Copyright (c) 2025-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

pythonic_fp_booleans-4.1.0/README.md

@@ -0,0 +1,24 @@
+# Pythonic FP - Booleans
+
+Subtypable Boolean like classes.
+
+PyPI project
+[pythonic-fp-booleans](https://pypi.org/project/pythonic-fp-booleans).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
+
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/booleans.html).
+
+While still compatible with Python shortcut logic, these singleton
+classes can be non-shortcut logically composed with Python’s bitwise
+operators. Unlike Python booleans which bitwise compose as integers,
+these compose as true Booleans in a contravariant way.
+
+## Copyright and License
+
+Copyright (c) 2025-2026 Geoffrey R. Scheller. Licensed under the Apache
+License, Version 2.0. See the LICENSE file for details.

{pythonic_fp_booleans-3.0.2 → pythonic_fp_booleans-4.1.0}/pyproject.toml

@@ -1,10 +1,15 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
 [project]
 name = "pythonic-fp-booleans"
-version = "3.0.2"
-readme = "README.rst"
+version = "4.1.0"
+readme = "README.md"
 requires-python = ">=3.13"
-license = { file = "LICENSE" }
-authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
+authors = [
+  { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
+]
 keywords = [
   "booleans",
   "subtypable",
@@ -15,32 +20,41 @@ classifiers = [
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
 dependencies = [
   "pythonic-fp-gadgets>=4.0.2",
 ]
-dynamic = ["description"]
+description = "True Booleans which are subtypable."
 
 [project.urls]
-Changelog = "https://github.com/grscheller/pythonic-fp-booleans/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp-booleans/"
-Homepage = "https://grscheller.github.io/pythonic-fp/homepage/html/"
+Changelog = "https://github.com/grscheller/pythonic-fp-booleans/blob/main/CHANGELOG.md"
+Documentation ="https://grscheller.github.io/pythonic-fp-booleans/release/html/"
+Homepage = "https://grscheller.github.io/pythonic-fp/"
 Source = "https://github.com/grscheller/pythonic-fp-booleans"
 
-[project.optional-dependencies]
+[dependency-groups]
+docs = [
+  "furo>=2025.12.19",
+  "sphinx>=9.1",
+]
+pub = [
+  "flit",
+]
 test = [
   "pytest>=8.4.1",
 ]
 
-[build-system]
-requires = ["flit_core>=3.12,<4"]
-build-backend = "flit_core.buildapi"
-
 [tool.flit.module]
 name = "pythonic_fp.booleans"
 
+[tool.flit.sdist]
+exclude = [
+  "docs/",
+  "tests/",
+]
+
 [tool.mypy]
 explicit_package_bases = true
 local_partial_types = true
@@ -49,20 +63,16 @@ warn_redundant_casts = true
 warn_return_any = true
 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"
+[tool.pytest]
+addopts = ["-ra"]
 consider_namespace_packages = true
 testpaths = ["tests/"]
 
 [tool.ruff]
-target-version = "py313"
+target-version = "py314"
+
+[tool.ruff.lint]
+ignore = ["RUF022", "E741"]
 
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
@@ -72,7 +82,6 @@ docstring-quotes = "double"
   "E731",
   "C901",
 ]
-"**/*.py" = ["E741"]
 
 [tool.ruff.format]
 quote-style = "single"

{pythonic_fp_booleans-3.0.2 → pythonic_fp_booleans-4.1.0}/src/pythonic_fp/booleans/__init__.py

@@ -13,28 +13,15 @@
 # limitations under the License.
 
 """
-Subtypable Boolean Class Hierarchy
-----------------------------------
+Booleans
+========
 
-.. graphviz::
+.. admonition:: Subtypable/subtyped Boolean like classes
 
-    digraph Booleans {
-        bgcolor="#957fb8";
-        node [style=filled, fillcolor="#181616", fontcolor="#dcd7ba"];
-        edge [color="#181616", fontcolor="#dcd7ba"];
-        int -> bool;
-        int -> SBool;
-        SBool -> "FBool(h1)";
-        SBool -> "FBool(h2)";
-        SBool -> "FBool(h3)";
-        SBool -> TF_Bool;
-        TF_Bool -> T_Bool;
-        TF_Bool -> F_Bool;
-    }
-
-While still compatible with Python shortcut logic, ``SBool`` and its
-subclasses can be non-shortcut logically composed with Python's bitwise
-operators.
+    - Like Python's builtin  ``bool``, ``SBool`` and its subclasses
+      are threadsafe singletons.
+    - While still compatible with Python shortcut logic, these can be
+      non-shortcut logically composed with Python's bitwise operators.
 
 """
 

pythonic_fp_booleans-4.1.0/src/pythonic_fp/booleans/flavored.py

@@ -0,0 +1,194 @@
+# Copyright 2023-2026 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.
+
+from collections.abc import Hashable
+from threading import Lock
+from typing import ClassVar, Self, final
+
+from .subtypable import SBool
+
+__all__ = ['FBool', 'truthy', 'falsy']
+
+
+@final
+class FBool(SBool):
+    """
+    .. admonition:: Favored Booleans
+
+        When different flavors of the truth matter. Each ``FBool`` is
+        an ``SBool`` subtype corresponding to a hashable flavor.
+
+        .. warning::
+
+            Combining FBool instances of different flavors with
+            bitwise operators will result in a runtime ValueError
+            exception.
+
+    """
+
+    _falsy_dict: ClassVar[dict[Hashable, FBool]] = {}
+    _falsy_dict_lock: ClassVar[Lock] = Lock()
+
+    _truthy_dict: ClassVar[dict[Hashable, FBool]] = {}
+    _truthy_dict_lock: ClassVar[Lock] = Lock()
+
+    def __new__(cls, witness: object, flavor: Hashable) -> Self:
+        """
+        .. admonition:: new
+
+            Traditional singleton pattern but with a ClassVar dict
+            to store the for truthy or falsy singleton for each
+            hashable flavor.
+
+            :param witness: Determines truthiness of the FBool instance returned.
+            :param flavor: The flavor of FBool to created.
+            :returns: The truthy or falsy FBool instance of a particular flavor.
+
+        """
+        if witness:
+            if flavor not in cls._truthy_dict:
+                with cls._truthy_dict_lock:
+                    if flavor not in cls._truthy_dict:
+                        cls._truthy_dict[flavor] = super(SBool, cls).__new__(cls, 1)
+            return cls._truthy_dict[flavor]
+        else:
+            if flavor not in cls._falsy_dict:
+                with cls._falsy_dict_lock:
+                    if flavor not in cls._falsy_dict:
+                        cls._falsy_dict[flavor] = super(SBool, cls).__new__(cls, 0)
+            return cls._falsy_dict[flavor]
+
+    def __init__(self, witness: object, flavor: Hashable) -> None:
+        """
+        .. admonition:: initialize
+
+            Let the flavored boolean know its flavor.
+
+            :param witness: Determines truthiness of the FBool instance returned.
+            :param flavor: The flavor of FBool to created.
+            :type flavor: H: Hashable
+            :returns: The truthy or falsy FBool instance of a particular flavor.
+            :raises ValueError: If different flavors compared with bitwise operators.
+
+        """
+        if not hasattr(self, '_flavor'):
+            self._flavor = flavor
+
+    def __and__(self, other: int) -> int:
+        if type(other) is type(self):
+            if other.flavor() != self._flavor:
+                msg = 'Error: diffent flavored booleans compared with & operator'
+                raise ValueError(msg)
+            if self and other:
+                return FBool(1, self._flavor)
+            else:
+                return FBool(0, self._flavor)
+        return super().__and__(other)
+
+    def __or__(self, other: int) -> int:
+        if type(other) is type(self):
+            if other.flavor() != self.flavor():
+                msg = 'Error: diffent flavored booleans compared with | operator'
+                raise ValueError(msg)
+            if self or other:
+                return FBool(1, self._flavor)
+            else:
+                return FBool(0, self._flavor)
+        return super().__or__(other)
+
+    def __xor__(self, other: int) -> int:
+        if type(other) is type(self):
+            if other.flavor() != self._flavor:
+                msg = 'Error: diffent flavored booleans compared with ^ operator'
+                raise ValueError(msg)
+            if (self or other) and not (self and other):
+                return FBool(1, self._flavor)
+            else:
+                return FBool(0, self._flavor)
+        return super().__xor__(other)
+
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            Create strings of the form
+
+            - ``FBool(True, repr_flavor)``
+            - ``FBool(False, repr_flavor)``
+
+            Where ``repr_flavor = repr(self.flavor())``
+
+            :returns: A String to reproduce the flavored boolean.
+
+        """
+        if self:
+            return f'FBool(True, {self._flavor!r})'
+        return f'FBool(False, {self._flavor!r})'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Create strings of the form
+
+            - ``FBool(True, str_flavor)``
+            - ``FBool(False, str_flavor)``
+
+            Where ``str_flavor = str(self.flavor())``
+
+            :returns: A String meaningful to an end user.
+
+        """
+        if self:
+            return f'FBool(True, {self._flavor!s})'
+        return f'FBool(False, {self._flavor!s})'
+
+    def flavor(self) -> Hashable:
+        """
+        .. admonition:: flavor
+
+            Get the flavor of the ``FBool``, a hashable value.
+
+            :returns: The flavor.
+
+        """
+        return self._flavor
+
+
+def truthy(flavor: Hashable) -> FBool:
+    """
+    .. admonition:: function truthy
+
+        Returns the truthy singleton ``FBool`` of a particular flavor.
+
+        :param flavor: Hashable value to determine which
+                       singleton flavor to return.
+        :returns: The truthy singleton of a particular flavor.
+
+    """
+    return FBool(True, flavor)
+
+
+def falsy(flavor: Hashable) -> FBool:
+    """
+    .. admonition:: Function falsy
+
+        Returns the falsy singleton ``FBool`` of a particular flavor.
+
+        :param flavor: Hashable value to determine which
+                       singleton flavor to return.
+        :returns: The falsy singleton of a particular flavor.
+
+    """
+    return FBool(False, flavor)

pythonic_fp_booleans-4.1.0/src/pythonic_fp/booleans/subtypable.py

@@ -0,0 +1,246 @@
+# 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.
+
+from collections.abc import Hashable
+from threading import Lock
+from typing import ClassVar, Final, Self, cast, overload
+
+from pythonic_fp.gadgets import first_common_ancestor as fca
+from pythonic_fp.gadgets.sentinels.novalue import NoValue
+
+__all__ = ['SBool', 'TRUTH', 'LIE']
+
+no_value = NoValue()
+
+class SBool(int):
+    """
+    .. admonition:: Subtypable Boolean
+
+        Like Python's built in ``bool``, class ``SBool`` is a singleton
+        subclass of ``int``. Unlike ``bool``, it can be further subclassed.
+
+        ``SBool`` and its subtypes can also do (non-shortcut) Boolean logic
+        using Python bitwise operators.
+
+        +-------------------+--------+----------------+
+        | Boolean operation | symbol | dunder         |
+        +===================+========+================+
+        |       not         | ``~``  | ``__invert__`` |
+        +-------------------+--------+----------------+
+        |       and         | ``&``  | ``__and__``    |
+        +-------------------+--------+----------------+
+        |       or          | ``|``  | ``__or__``     |
+        +-------------------+--------+----------------+
+        |       xor         | ``^``  | ``__xor__``    |
+        +-------------------+--------+----------------+
+
+        While compatible with Python  short-cut logic, , the not
+        operator unfortunately always returns a bool.
+
+        .. tip::
+
+            Use the bitwise ~ operator to return an opposite SBool
+            instance or subclass instance.
+
+        .. note::
+
+            These operators are contravariant, that is they will return
+            the instance of the latest common ancestor of their
+            arguments. More specifically, the instance returned will
+            have the type of the least upper bound in the inheritance
+            graph of the classes of the two arguments.
+
+            .. warning::
+
+                The "bitwise" operators can raise TypeError
+                exceptions when applied against an SBool and
+                objects not descended from int.
+
+    """
+
+    _falsy: ClassVar[SBool | NoValue] = NoValue()
+    _falsy_lock: ClassVar[Lock] = Lock()
+
+    _truthy: ClassVar[SBool | NoValue] = NoValue()
+    _truthy_lock: ClassVar[Lock] = Lock()
+
+    @overload
+    def __new__(cls, witness: object) -> Self: ...
+    @overload
+    def __new__(
+        cls, witness: object, flavor: Hashable | NoValue = no_value
+    ) -> Self: ...
+
+    def __new__(
+        cls,
+        witness: object,
+        flavor: Hashable | NoValue = no_value,
+    ) -> Self:
+        """
+        .. admonition:: new
+
+            :param witness: Determines truthiness of the ``SBool``.
+            :param flavor: Ignored
+            :returns: The truthy or falsy ``SBool`` class instance.
+
+        """
+        if witness:
+            if cls._truthy is NoValue():
+                with cls._truthy_lock:
+                    if cls._truthy is NoValue():
+                        cls._truthy = super().__new__(cls, 1)
+            return cast(Self, cls._truthy)
+        else:
+            if cls._falsy is NoValue():
+                with cls._falsy_lock:
+                    if cls._falsy is NoValue():
+                        cls._falsy = super().__new__(cls, 0)
+            return cast(Self, cls._falsy)
+
+    @overload
+    def __init__(self, witness: object) -> None: ...
+    @overload
+    def __init__(self, witness: object, flavor: Hashable) -> None: ...
+
+    def __init__(
+        self,
+        witness: object = False,
+        flavor: Hashable | NoValue = no_value,
+    ) -> None:
+        """
+        .. admonition:: init
+
+            :param witness: Determines the truthiness of the ``SBool``.
+            :param flavor: Ignored by ``SBool``, here only to support
+                           the Liskov Substitution Principle.
+        """
+        self._flavor: Hashable | NoValue = NoValue()
+
+    def __invert__(self) -> int:
+        if self:
+            return type(self)(False, self._flavor)
+        return type(self)(True, self._flavor)
+
+    def __and__(self, other: int) -> int:
+        try:
+            base_class = fca(type(self), type(other))
+        except TypeError:
+            if type(other) is bool:
+                base_class = int
+            else:
+                msg = f"unsupported operand type(s) for &: '{type(self)}' and '{type(other)}'"
+                raise TypeError(msg)
+
+        if issubclass(base_class, SBool):
+            if self._flavor == cast(SBool, other)._flavor:
+                flavor = self._flavor
+            else:
+                flavor = NoValue()
+
+            if self and other:
+                return base_class(True, flavor)
+            return base_class(False, flavor)
+        else:
+            return int(self) & int(other)
+
+    def __or__(self, other: int) -> int:
+        try:
+            base_class = fca(type(self), type(other))
+        except TypeError:
+            if type(other) is bool:
+                base_class = int
+            else:
+                msg = f"unsupported operand type(s) for |: '{type(self)}' and '{type(other)}'"
+                raise TypeError(msg)
+
+        if issubclass(base_class, SBool):
+            if self._flavor == cast(SBool, other)._flavor:
+                flavor = self._flavor
+            else:
+                flavor = NoValue()
+
+            if self or other:
+                return base_class(True, flavor)
+            return base_class(False, flavor)
+        else:
+            return int(self) | int(other)
+
+    def __xor__(self, other: int) -> int:
+        try:
+            base_class = fca(type(self), type(other))
+        except TypeError:
+            if type(other) is bool:
+                base_class = int
+            else:
+                msg = f"unsupported operand type(s) for ^: '{type(self)}' and '{type(other)}'"
+                raise TypeError(msg)
+
+        if issubclass(base_class, SBool):
+            if self._flavor == cast(SBool, other)._flavor:
+                flavor = self._flavor
+            else:
+                flavor = NoValue()
+
+            if self and not other or other and not self:
+                return base_class(True, flavor)
+            return base_class(False, flavor)
+        else:
+            return int(self) ^ int(other)
+
+    # override in derived classes
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            - 'SBool(True)' if truthy
+            - 'SBool(False)' if falsy
+
+            :returns: A string to reproduce the ``SBool``.
+
+        """
+        if self:
+            return 'SBool(True)'
+        return 'SBool(False)'
+
+    # override in derived classes
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            - 'TRUTH' if truthy
+            - 'LIE' if falsy
+
+            :returns: A string meaningful to an end user.
+
+        """
+        if self:
+            return 'TRUTH'
+        return 'LIE'
+
+
+TRUTH: Final[SBool] = SBool(True)
+"""
+.. admonition:: TRUTH
+
+    :var TRUTH: The truthy singleton of type ``SBool``.
+
+"""
+
+LIE: Final[SBool] = SBool(False)
+"""
+.. admonition:: LIE
+
+    :var LIE: The falsy singleton of type SBool.
+
+"""