pythonic-fp-booleans 4.3.0__tar.gz → 5.0.0__tar.gz

{pythonic_fp_booleans-4.3.0 → pythonic_fp_booleans-5.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-booleans
-Version: 4.3.0
-Summary: True Booleans which are subtypable.
+Version: 5.0.0
+Summary: Boolean like classes.
 Keywords: booleans,subtypable
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.14
@@ -23,7 +23,7 @@ Project-URL: Source, https://github.com/grscheller/pythonic-fp-booleans
 
 # Pythonic FP - Booleans
 
-Subtypable Boolean like classes.
+Boolean like classes.
 
 PyPI project
 [pythonic-fp-booleans](https://pypi.org/project/pythonic-fp-booleans).

{pythonic_fp_booleans-4.3.0 → pythonic_fp_booleans-5.0.0}/README.md

@@ -1,6 +1,6 @@
 # Pythonic FP - Booleans
 
-Subtypable Boolean like classes.
+Boolean like classes.
 
 PyPI project
 [pythonic-fp-booleans](https://pypi.org/project/pythonic-fp-booleans).

{pythonic_fp_booleans-4.3.0 → pythonic_fp_booleans-5.0.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "pythonic-fp-booleans"
-version = "4.3.0"
-description = "True Booleans which are subtypable."
+version = "5.0.0"
+description = "Boolean like classes."
 readme = "README.md"
-requires-python = ">=3.14"  # floor: PEP 649/749 deferred annotations — class-level self-reference (SBool in its own ClassVar annotation) NameErrors on <3.14
+requires-python = ">=3.14"  # floor: PEP 649/749 deferred annotations — class-level self-reference NameErrors on <3.14
 authors = [
   { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
 ]
@@ -51,6 +51,11 @@ name = "pythonic_fp.booleans"
 exclude = [
   "docs/",
   "tests/",
+  "**/.mypy_cache/",
+  "**/.ruff_cache/",
+  "**/.pytest_cache/",
+  "**/__pycache__/",
+  "**/.dmypy.json",
 ]
 
 [tool.pytest]

{pythonic_fp_booleans-4.3.0 → pythonic_fp_booleans-5.0.0}/src/pythonic_fp/booleans/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# 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.
@@ -26,5 +26,5 @@ Booleans
 """
 
 __author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2025-2026 Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2026 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'

{pythonic_fp_booleans-4.3.0 → pythonic_fp_booleans-5.0.0}/src/pythonic_fp/booleans/flavored.py

@@ -86,6 +86,18 @@ class FBool(SBool):
             self._flavor = flavor
 
     def __and__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise and operator
+
+            Overloading ``&`` to perform Boolean "and" if ``other`` is
+            another FBool of the same flavor.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "and" if other is an FBool of the same
+                      flavor, otherwise returns bitwise "and".
+            :raises: ValueError if other is an FBool of a different flavor.
+
+        """
         if type(other) is type(self):
             if other.flavor() != self._flavor:
                 msg = 'Error: diffent flavored booleans compared with & operator'
@@ -97,6 +109,18 @@ class FBool(SBool):
         return super().__and__(other)
 
     def __or__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise or operator
+
+            Overloading ``|`` to perform Boolean "or" if ``other`` is
+            another FBool of the same flavor.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "or" if other is an FBool of the same
+                      flavor, otherwise returns bitwise "or".
+            :raises: ValueError if other is an FBool of a different flavor.
+
+        """
         if type(other) is type(self):
             if other.flavor() != self.flavor():
                 msg = 'Error: diffent flavored booleans compared with | operator'
@@ -108,6 +132,18 @@ class FBool(SBool):
         return super().__or__(other)
 
     def __xor__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise xor operator
+
+            Overloading ``^`` to perform Boolean "xor" if ``other`` is
+            another FBool of the same flavor.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "xor" if other is an FBool of the same
+                      flavor, otherwise returns bitwise "or".
+            :raises: ValueError if other is an FBool of a different flavor.
+
+        """
         if type(other) is type(self):
             if other.flavor() != self._flavor:
                 msg = 'Error: diffent flavored booleans compared with ^ operator'
@@ -160,7 +196,7 @@ class FBool(SBool):
 
             Get the flavor of the ``FBool``, a hashable value.
 
-            :returns: The flavor.
+            :returns: The flavor of the FBool.
 
         """
         return self._flavor

{pythonic_fp_booleans-4.3.0 → pythonic_fp_booleans-5.0.0}/src/pythonic_fp/booleans/subtypable.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# 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.
@@ -91,7 +91,7 @@ class SBool(int):
         .. admonition:: new
 
             :param witness: Determines truthiness of the ``SBool``.
-            :param flavor: Ignored
+            :param flavor: Ignored, here for Liskov  substitution principle
             :returns: The truthy or falsy ``SBool`` class instance.
 
         """
@@ -128,11 +128,32 @@ class SBool(int):
         self._flavor: Hashable | NoValue = NoValue()
 
     def __invert__(self) -> int:
+        """
+        .. admonition:: bitwise invert operator
+
+            Inverts the value of an SBool.
+
+            :returns: The inverted value of the SBool.
+
+        """
         if self:
             return type(self)(False, self._flavor)
         return type(self)(True, self._flavor)
 
     def __and__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise and operator
+
+            Overloading ``&`` to perform Boolean "and" if ``other``
+            is another ``SBool``.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "and" if other is an SBool
+                      otherwise returns bitwise "and".
+            :rtype: First common ancestor of the types of self and other
+                    if both of type SBool, otherwise int.
+
+        """
         base_class = fca(type(self), type(other))
 
         if issubclass(base_class, SBool):
@@ -148,6 +169,19 @@ class SBool(int):
             return int(self) & int(other)
 
     def __or__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise or operator
+
+            Overloading ``|`` to perform Boolean "or" if ``other``
+            is another ``SBool``.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "and" if other is an SBool
+                      otherwise returns bitwise "and".
+            :rtype: First common ancestor of the types of self and other
+                    if both of type SBool, otherwise int.
+
+        """
         base_class = fca(type(self), type(other))
         if issubclass(base_class, SBool):
             if self._flavor == cast(SBool, other)._flavor:
@@ -162,6 +196,19 @@ class SBool(int):
             return int(self) | int(other)
 
     def __xor__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise xor operator
+
+            Overloading ``^`` to perform Boolean "xor" if ``other``
+            is another ``SBool``.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "and" if other is an SBool
+                      otherwise returns bitwise "and".
+            :rtype: First common ancestor of the types of self and other
+                    if both of type SBool, otherwise int.
+
+        """
         base_class = fca(type(self), type(other))
 
         if issubclass(base_class, SBool):
@@ -181,10 +228,9 @@ class SBool(int):
         """
         .. admonition:: repr string
 
-            - 'SBool(True)' if truthy
-            - 'SBool(False)' if falsy
+            A string to reproduce the ``SBool``.
 
-            :returns: A string to reproduce the ``SBool``.
+            :returns: 'SBool(True)' if truthy, 'SBool(False)' if falsy.
 
         """
         if self:
@@ -196,10 +242,9 @@ class SBool(int):
         """
         .. admonition:: user string
 
-            - 'TRUTH' if truthy
-            - 'LIE' if falsy
+            A string meaningful to an end user.
 
-            :returns: A string meaningful to an end user.
+            :returns: 'TRUTH' if truthy, 'LIE' if falsy.
 
         """
         if self:

pythonic_fp_booleans-5.0.0/src/pythonic_fp/booleans/truthy_falsy.py

@@ -0,0 +1,285 @@
+# 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, Final, Self, cast, final
+
+from .subtypable import SBool
+
+__all__ = [
+    'TF_Bool',
+    'T_Bool',
+    'F_Bool',
+    'ALWAYS',
+    'NEVER',
+]
+
+
+class TF_Bool(SBool):
+    """
+    .. admonition:: Truthy-Falsy Booleans
+
+        A Boolean implementation whose distinct truthy and falsy
+        values are distinct singleton subclasses, not just
+        distinct singleton values.
+
+        .. important::
+
+            Do not subclass ``TF_Bool`` itself. Subclassing it is
+            designed to fail at runtime.
+
+        .. tip::
+
+            Logically combine these using Python's bitwise operators.
+
+        .. warning::
+
+            Although these datastructures are completely compatible
+            with Python shortcut evaluation, care needs to be taken
+            when using them with the ``and``, ``or``, and ``not`` builtins.
+
+            For example:
+
+            - ``~ALWAYS is NEVER``
+            - ``not ALWAYS is False``
+            - ``(ALWAYS and False) is False``
+            - ``(ALWAYS or False) is ALWAYS``
+
+    """
+
+    def __new__(cls, witness: object, flavor: Hashable = None) -> Self:
+        """
+        .. admonition:: new
+
+            :param witness: Determines which subtype,
+                            ``T_Bool`` or ``F_Bool``,
+                            of ``TF_Bool`` to return.
+            :param flavor: Ignored parameter, only two flavors,
+                           one truthy and one falsy.
+            :returns: The singleton truthy or singleton falsy instance.
+
+        """
+        if witness:
+            return cast(Self, T_Bool())
+        return cast(Self, F_Bool())
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if TF_Bool in cls.__bases__ and cls.__module__ != TF_Bool.__module__:
+            msg = 'TF_Bool is sealed'
+            raise TypeError(msg)
+
+    def __invert__(self) -> TF_Bool:
+        """
+        .. admonition:: bitwise invert operator
+
+            Inverts the value of an TF_Bool.
+
+            :returns: The inverted value of the SBool.
+
+        """
+        if self:
+            return F_Bool()
+        return T_Bool()
+
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            A string to reproduce the TF_Bool.
+
+            :returns: 'T_Bool()' if truthy, otherwise `F_Bool()`
+
+        """
+        if self:
+            return 'T_Bool()'
+        return 'F_Bool()'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            A string meaningful to an end user.
+
+            :returns: 'ALWAYS' if truthy, otherwise 'NEVER'
+
+        """
+        if self:
+            return 'ALWAYS'
+        return 'NEVER'
+
+
+@final
+class T_Bool(TF_Bool):
+    """
+    .. admonition:: Truthy TF_Bool subclass
+
+         Type of the truthy singleton TF_Bool instance.
+         A distinct type from F_Bool.
+
+    """
+
+    _lock: ClassVar[Lock] = Lock()
+
+    def __new__(cls, witness: object = None, flavor: Hashable = None) -> Self:
+        """
+        .. admonition:: new
+
+            :param witness: Ignored parameter, a T_Bool or T_Bool subtype is always truthy.
+            :param flavor: Ignored parameter, only one truthy "flavor" for each T_Bool subtype.
+            :returns: The truthy T_Bool or T_Bool subtype singleton instance.
+
+        """
+        inst = cls.__dict__.get('_truthy')
+        if inst is None:
+            with T_Bool._lock:
+                inst = cls.__dict__.get('_truthy')
+                if inst is None:
+                    inst = super(SBool, cls).__new__(cls, 1)
+                    cls._truthy = inst
+        return cast(Self, inst)
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if T_Bool in cls.__bases__ and cls.__module__ != T_Bool.__module__:
+            msg = 'T_Bool is final'
+            raise TypeError(msg)
+
+    def __and__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise and operator
+
+            Overloading ``&`` to perform Boolean "and" if ``other``
+            is another ``TF_Bool``.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "and" if other is an SBool
+                      otherwise returns bitwise "and".
+            :rtype: First common ancestor of the types of self and other
+                    if both of type SBool, otherwise int.
+
+        """
+        if isinstance(other, TF_Bool):
+            return other
+        return super().__and__(other)
+
+    def __or__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise or operator
+
+            Overloading ``|`` to perform Boolean "or" if ``other``
+            is another ``TF_Bool``.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "or" if other is an SBool
+                      otherwise returns bitwise "or".
+            :rtype: First common ancestor of the types of self and other
+                    if both of type SBool, otherwise int.
+
+        """
+        if isinstance(other, TF_Bool):
+            return self
+        return super().__or__(other)
+
+    def __xor__(self, other: int) -> int:
+        """
+        .. admonition:: bitwise xor operator
+
+            Overloading ``^`` to perform Boolean "xor" if ``other``
+            is another ``TF_Bool``.
+
+            :param other: Any object derived from int.
+            :returns: Boolean "xor" if other is an SBool
+                      otherwise returns bitwise "xor".
+            :rtype: First common ancestor of the types of self and other
+                    if both of type SBool, otherwise int.
+
+        """
+        if isinstance(other, TF_Bool):
+            if other:
+                return ~self
+            return self
+        return super().__xor__(other)
+
+
+@final
+class F_Bool(TF_Bool):
+    """
+    .. admonition:: Falsy TF_Bool subclass
+
+         Type of the falsy singleton TF_Bool instance.
+         A distinct type from T_Bool.
+
+    """
+
+    _lock: ClassVar[Lock] = Lock()
+
+    def __new__(cls, witness: object = None, flavor: Hashable = None) -> Self:
+        """
+        .. admonition:: new
+
+            :param witness: Ignored parameter, an F_Bool or F_Bool subtype is always truthy.
+            :param flavor: Ignored parameter, only one truthy "flavor" for each F_Bool subtype.
+            :returns: The truthy F_Bool or F_Bool subtype singleton instance.
+
+        """
+        inst = cls.__dict__.get('_falsy')
+        if inst is None:
+            with T_Bool._lock:
+                inst = cls.__dict__.get('_falsy')
+                if inst is None:
+                    inst = super(SBool, cls).__new__(cls, 0)
+                    cls._falsy = inst
+        return cast(Self, inst)
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if F_Bool in cls.__bases__ and cls.__module__ != F_Bool.__module__:
+            msg = 'F_Bool is final'
+            raise TypeError(msg)
+
+    def __and__(self, other: int) -> int:
+        if issubclass(type(other), TF_Bool):
+            return self
+        return super().__and__(other)
+
+    def __or__(self, other: int) -> int:
+        if issubclass(type(other), TF_Bool):
+            return other
+        return super().__or__(other)
+
+    def __xor__(self, other: int) -> int:
+        if issubclass(type(other), TF_Bool):
+            if other:
+                return other
+            return self
+        return super().__xor__(other)
+
+
+ALWAYS: Final[TF_Bool] = T_Bool()
+"""
+.. admonition:: ALWAYS
+
+    :var ALWAYS: The truthy singleton TF_Bool subtyped instance.
+
+"""
+
+NEVER: Final[TF_Bool] = F_Bool()
+"""
+.. admonition:: NEVER
+
+    :var NEVER: The falsy singleton TF_Bool subtyped instance.
+
+"""

pythonic_fp_booleans-4.3.0/src/pythonic_fp/booleans/truthy_falsy.py

@@ -1,229 +0,0 @@
-# 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, Final, Self, cast
-
-from pythonic_fp.gadgets.sentinels.novalue import NoValue
-
-from .subtypable import SBool
-
-__all__ = [
-    'TF_Bool',
-    'T_Bool',
-    'F_Bool',
-    'ALWAYS',
-    'NEVER',
-]
-
-
-class TF_Bool(SBool):
-    """
-    .. admonition:: Truthy-Falsy Booleans
-
-        A Boolean implementation whose distinct truthy and falsy
-        values are distinct singleton subclasses, not just
-        distinct singleton values.
-
-        A subtype of SBool.
-
-        .. tip::
-
-            Logically combine these using Python's bitwise operators.
-
-        .. warning::
-
-            Although these datastructures are completely compatible
-            with Python shortcut evaluation, care needs to be taken when
-            using them with the "and", "or", and "not" builtins.
-
-            For example, ``~ALWAYS is NEVER`` but ``not ALWAYS is False``
-            because ``ALWAYS`` is truthy.
-
-            Similarly, ``(ALWAYS and False) is False`` while
-            ``(ALWAYS or False) is ALWAYS``.
-
-    """
-
-    no_value = NoValue()
-
-    def __new__(
-        cls,
-        witness: object,
-        flavor: Hashable = no_value,
-    ) -> Self:
-        """
-        .. admonition:: new
-
-            :param witness: Determines which subtype, T_Bool or F_Bool to return.
-            :param flavor: Ignored parameter, only two flavors, one truthy and one falsy.
-            :returns: The singleton truthy or singleton falsy instances.
-
-        """
-        if witness:
-            return cast(Self, T_Bool())
-        return cast(Self, F_Bool())
-
-    def __invert__(self) -> TF_Bool:
-        if self:
-            return F_Bool()
-        return T_Bool()
-
-    def __repr__(self) -> str:
-        """
-        .. admonition:: repr string
-
-            - if truthy return 'TF_Bool(True)'
-            - if falsy return 'TF_Bool(False)'
-
-            :returns: A string to reproduce the TF_Bool.
-
-        """
-        if self:
-            return 'TF_Bool(True)'
-        return 'TF_Bool(False)'
-
-    def __str__(self) -> str:
-        """
-        .. admonition:: user string
-
-            - if truthy return 'ALWAYS'
-            - if falsy return 'NEVER'
-
-            :returns: A string meaningful to an end user.
-
-        """
-        if self:
-            return 'ALWAYS'
-        return 'NEVER'
-
-
-class T_Bool(TF_Bool):
-    """
-    .. admonition:: Truthy TF_Bool subclass
-
-         Type of the truthy singleton TS_Bool instance.
-         A distinct type from F_Bool.
-
-    """
-
-    no_value = NoValue()
-
-    _truthy: ClassVar[T_Bool | NoValue] = no_value
-    _lock: ClassVar[Lock] = Lock()
-
-    def __new__(
-        cls,
-        witness: object = no_value,
-        flavor: Hashable | NoValue = no_value,
-    ) -> Self:
-        """
-        .. admonition:: new
-
-            :param witness: Ignored parameter, a T_Bool is always truthy.
-            :param flavor: Ignored parameter, only one truthy "flavor".
-            :returns: The truthy T_Bool singleton instance.
-
-        """
-        if cls._truthy is (no_value := NoValue()):
-            with cls._lock:
-                if cls._truthy is no_value:
-                    cls._truthy = super(SBool, cls).__new__(cls, 1)
-        return cast(Self, cls._truthy)
-
-    def __and__(self, other: int) -> int:
-        if isinstance(other, TF_Bool):
-            return other
-        return super().__and__(other)
-
-    def __or__(self, other: int) -> int:
-        if isinstance(other, TF_Bool):
-            return self
-        return super().__or__(other)
-
-    def __xor__(self, other: int) -> int:
-        if isinstance(other, TF_Bool):
-            if other:
-                return ~self
-            return self
-        return super().__xor__(other)
-
-
-class F_Bool(TF_Bool):
-    """
-    .. admonition:: Falsy TF_Bool subclass
-
-         Type of the falsy singleton TS_Bool instance.
-         A distinct type from T_Bool.
-
-    """
-
-    no_value = NoValue()
-
-    _falsy: ClassVar[F_Bool | NoValue] = no_value
-    _lock: ClassVar[Lock] = Lock()
-
-    def __new__(
-        cls,
-        witness: object = NoValue(),
-        flavor: Hashable | NoValue = no_value,
-    ) -> Self:
-        """
-        .. admonition:: new
-
-            :param witness: Parameter ignored, an F_Bool is always falsy.
-            :param flavor: Parameter ignored, only one falsy "flavor".
-            :returns: The falsy F_Bool singleton instance.
-
-        """
-        if cls._falsy is (no_value := NoValue()):
-            with cls._lock:
-                if cls._falsy is no_value:
-                    cls._falsy = super(SBool, cls).__new__(cls, 0)
-        return cast(Self, cls._falsy)
-
-    def __and__(self, other: int) -> int:
-        if issubclass(type(other), TF_Bool):
-            return self
-        return super().__and__(other)
-
-    def __or__(self, other: int) -> int:
-        if issubclass(type(other), TF_Bool):
-            return other
-        return super().__or__(other)
-
-    def __xor__(self, other: int) -> int:
-        if issubclass(type(other), TF_Bool):
-            if other:
-                return other
-            return self
-        return super().__xor__(other)
-
-
-ALWAYS: Final[TF_Bool] = T_Bool()
-"""
-.. admonition:: ALWAYS
-
-    :var ALWAYS: The truthy singleton TF_Bool subtyped instance.
-
-"""
-
-NEVER: Final[TF_Bool] = F_Bool()
-"""
-.. admonition:: Never
-
-    :var NEVER: The falsy singleton TF_Bool subtyped instance.
-
-"""