pythonic-fp.containers 2.0.0__py3-none-any.whl

pythonic_fp/containers/__init__.py

@@ -0,0 +1,19 @@
+# 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.
+
+"""Developer Tools - Container-like data structures"""
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'

pythonic_fp/containers/box.py

@@ -0,0 +1,159 @@
+# 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.
+
+"""Stateful container holds at most one item of a given type."""
+
+from __future__ import annotations
+
+__all__ = ['Box']
+
+from collections.abc import Callable, Iterator
+from typing import cast, Final, Never, overload, TypeVar
+from pythonic_fp.fptools.singletons import Sentinel
+
+D = TypeVar('D')
+
+_sentinel: Final[Sentinel] = Sentinel('Box')
+
+class Box[D]:
+    """Container holding at most one item of a given type
+
+    - where ``Box(item)`` contains at most one item of type ``~D``
+
+      - ``Box()`` creates an empty container
+      - can store any item of any type, including ``None``
+    """
+
+    __slots__ = ('_item',)
+    __match_args__ = ('_item',)
+
+    T = TypeVar('T')
+
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, value: D) -> None: ...
+
+    def __init__(self, value: D | Sentinel = Sentinel('Box')) -> None:
+        """Initialize Box with an "optional" initial value.
+
+           :param value: "optional" initial value
+           :type value: ~D
+        """
+        self._item: D | Sentinel = value
+
+    def __bool__(self) -> bool:
+        return self._item is not Sentinel('Box')
+
+    def __iter__(self) -> Iterator[D]:
+        if self:
+            yield cast(D, self._item)
+
+    def __repr__(self) -> str:
+        if self:
+            return 'Box(' + repr(self._item) + ')'
+        return 'Box()'
+
+    def __len__(self) -> int:
+        return 1 if self else 0
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, type(self)):
+            return False
+
+        if self._item is other._item:
+            return True
+        if self._item == other._item:
+            return True
+        return False
+
+    @overload
+    def get(self) -> D | Never: ...
+    @overload
+    def get(self, alt: D) -> D: ...
+    @overload
+    def get(self, alt: Sentinel) -> D | Never: ...
+
+    def get(self, alt: D | Sentinel = Sentinel('Box')) -> D | Never:
+        """Return the contained value if it exists, otherwise an alternate value.
+
+        :rtype: ~D 
+        :raises ValueError: when an alternate value is not provided but needed
+        """
+        if self._item is not _sentinel:
+            return cast(D, self._item)
+        if alt is _sentinel:
+            msg = 'Box: get from empty Box with no alt return value provided'
+            raise ValueError(msg)
+        return cast(D, alt)
+
+    def pop(self) -> D | Never:
+        """Pop the value if Box is not empty.
+
+        :rtype: ~D
+        :raises ValueError: if box is empty
+        """
+        if self._item is _sentinel:
+            msg = 'Box: Trying to pop an item from an empty Box'
+            raise ValueError(msg)
+        popped = cast(D, self._item)
+        self._item = _sentinel
+        return popped
+
+    def push(self, item: D) -> None | Never:
+        """Push an item in an empty Box.
+
+        :raises ValueError: if box is not empty
+        """
+        if self._item is Sentinel('Box'):
+            self._item = item
+        else:
+            msg = 'Box: Trying to push an item in an empty Box'
+            raise ValueError(msg)
+        return None
+
+    def put(self, item: D) -> None:
+        """Put an item in the Box. Discard any previous contents."""
+        self._item = item
+
+    def exchange(self, new_item: D) -> D | Never:
+        """Exchange an item with what is in the Box.
+
+        :rtype: ~D
+        :raises ValueError: if box is empty
+        """
+        if self._item is _sentinel:
+            msg = 'Box: Trying to exchange items using an empty Box'
+            raise ValueError(msg)
+        popped = cast(D, self._item)
+        self._item = new_item
+        return popped
+
+    def map[T](self, f: Callable[[D], T]) -> Box[T]:
+        """Map function ``f`` over contents.
+
+        :return: a new instance
+        """
+        if self._item is Sentinel('Box'):
+            return Box()
+        return Box(f(cast(D, self._item)))
+
+    def bind[T](self, f: Callable[[D], Box[T]]) -> Box[T]:
+        """Flatmap ``Box`` with function ``f``.
+
+        :return: a new instance
+        """
+        if self._item is _sentinel:
+            return Box()
+        return f(cast(D, self._item))

pythonic_fp/containers/functional_tuple.py

@@ -0,0 +1,189 @@
+# 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.
+
+"""Pythonic FP - Functional Tuple"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import cast, Never, overload
+from pythonic_fp.iterables import FM, accumulate, concat, exhaust, merge
+
+__all__ = ['FunctionalTuple', 'functional_tuple']
+
+class FunctionalTuple[D](tuple[D, ...]):
+    """Functional Tuple suitable for inheritance
+
+    - Supports both indexing and slicing
+    - FunctionalTuple addition and int multiplication supported
+
+      - addition concatenates results, resulting in a Union type
+      - both left and right int multiplication supported
+      - homogeneous in its data type
+      - supports being further inherited from
+      - unslotted
+    """
+
+    def __reversed__(self) -> Iterator[D]:
+        for ii in range(len(self) - 1, -1, -1):
+            yield (self[ii])
+
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}(' + ', '.join(map(repr, self)) + ')'
+
+    def __eq__(self, other: object, /) -> bool:
+        if not isinstance(other, self.__class__):
+            return False
+        if (length := len(self)) != len(other):
+            return False
+        if self is other:
+            return True
+        for ii in range(length):
+            if self[ii] != other[ii]:
+                return False
+        return True
+
+    @overload    # type:ignore
+    def __getitem__(self, x: int) -> D: ...
+    @overload
+    def __getitem__(self, x: slice) -> tuple[D, ...]: ...
+
+    def __getitem__(self, idx: int | slice, /) -> tuple[D, ...] | D:
+        def newtup(tup: tuple[D, ...]) -> tuple[D, ...]:
+            return tup[0:-1] + tup[-1:]
+
+        if isinstance(idx, slice):
+            return self.__class__(newtup(super().__getitem__(idx)))
+        else:
+            return super().__getitem__(idx)
+
+    def foldl[L](
+        self,
+        f: Callable[[L, D], L],
+        /,
+        start: L | None = None,
+        default: L | None = None,
+    ) -> L | None:
+        """Fold Left
+
+        - fold left with an optional starting value
+        - first argument of function f is for the accumulated value
+
+        :raises ValueError: when FunctionalTuple empty and a start value not given
+        """
+        it = iter(self)
+        if start is not None:
+            acc = start
+        elif self:
+            acc = cast(L, next(it))
+        else:
+            if default is None:
+                msg = 'Both start and default cannot be None for an empty FunctionalTuple'
+                raise ValueError('FunctionalTuple.foldl - ' + msg)
+            acc = default
+        for v in it:
+            acc = f(acc, v)
+        return acc
+
+    def foldr[R](
+        self,
+        f: Callable[[D, R], R],
+        /,
+        start: R | None = None,
+        default: R | None = None,
+    ) -> R | None:
+        """Fold Right
+
+        - fold right with an optional starting value
+        - second argument of function f is for the accumulated value
+
+        :raises ValueError: when FunctionalTuple empty and a start value not given
+        """
+        it = reversed(self)
+        if start is not None:
+            acc = start
+        elif self:
+            acc = cast(R, next(it))
+        else:
+            if default is None:
+                msg = 'Both start and default cannot be None for an empty FunctionalTuple'
+                raise ValueError('FunctionalTuple.foldR - ' + msg)
+            acc = default
+        for v in it:
+            acc = f(v, acc)
+        return acc
+
+    def copy(self) -> FunctionalTuple[D]:
+        """Return a shallow copy of ``FunctionalTuple`` in O(1) time & space complexity."""
+        return self.__class__(self)
+
+    def __add__(self, other: object, /) -> tuple[D, ...]:
+        if not isinstance(other, FunctionalTuple):
+            msg = 'FunctionalTuple being added to something not an FunctionalTuple'
+            raise ValueError(msg)
+        return self.__class__(concat(self, other))
+
+    def __mul__(self, num: int, /) -> tuple[D, ...]:
+        return self.__class__(super().__mul__(num))
+
+    def __rmul__(self, num: int, /) -> tuple[D]:
+        return self.__class__(super().__rmul__(num))
+
+    def accummulate[L](
+        self, f: Callable[[L, D], L], s: L | None = None, /
+    ) -> FunctionalTuple[L]:
+        """Accumulate partial folds
+
+        Accumulate partial fold results in an ``FunctionalTuple`` with an optional
+        starting value.
+        """
+        if s is None:
+            return FunctionalTuple(accumulate(self, f))
+        return FunctionalTuple(accumulate(self, f, s))
+
+    def map[U](self, f: Callable[[D], U], /) -> FunctionalTuple[U]:
+        return FunctionalTuple(map(f, self))
+
+    def bind[U](
+        self, f: Callable[[D], FunctionalTuple[U]], type: FM = FM.CONCAT, /
+    ) -> FunctionalTuple[U] | Never:
+        """Bind function ``f`` to the ``FunctionalTuple``.
+
+        - FM Enum types
+
+          - CONCAT: sequentially concatenate iterables one after the other
+          - MERGE: round-robin merge iterables until one is exhausted
+          - EXHAUST: round-robin merge iterables until all are exhausted
+
+        :param ds: values to instantiate FunctionalTuple
+        :return: resulting FunctionalTuple
+        """
+        match type:
+            case FM.CONCAT:
+                return FunctionalTuple(concat(*map(f, self)))
+            case FM.MERGE:
+                return FunctionalTuple(merge(*map(f, self)))
+            case FM.EXHAUST:
+                return FunctionalTuple(exhaust(*map(f, self)))
+
+        raise ValueError('Unknown FM type')
+
+
+def functional_tuple[D](*ds: D):
+    """Construct a ``FunctionalTuple`` from arguments.
+
+    :param ds: values to instantiate FunctionalTuple
+    :return: resulting FunctionalTuple
+    """
+    return FunctionalTuple(ds)

pythonic_fp/containers/immutable_list.py

@@ -0,0 +1,222 @@
+# 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.
+
+"""Pythonic FP - Immutable guaranteed hashable lists
+
+- hashable if elements are hashable
+- declared covariant in its generic datatype
+  - hashability should be enforced by LSP tooling
+  - hashability will be enforced at runtime
+  - ImmutableList addition supported via concatenation
+  - ImmutableList integer multiplication supported
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator, Hashable
+from typing import cast, Never, overload, TypeVar
+from pythonic_fp.iterables import FM, accumulate, concat, exhaust, merge
+
+__all__ = ['ImmutableList', 'immutable_list']
+
+D = TypeVar('D', covariant=True)
+T = TypeVar('T')
+
+class ImmutableList[D](Hashable):
+    """Immutable List like data structure.
+
+    - its method type parameters are also covariant
+    - hashability will be enforced by LSP tooling
+    - supports both indexing and slicing
+    - addition concatenates results, resulting type a Union type
+    - both left and right int multiplication supported
+    """
+
+    __slots__ = ('_ds', '_len', '_hash')
+    __match_args__ = ('_ds', '_len')
+
+    L = TypeVar('L')
+    R = TypeVar('R')
+    U = TypeVar('U')
+
+    def __init__(self, *dss: Iterable[D]) -> None:
+        if (size := len(dss)) > 1:
+            msg = f'ImmutableList expects at most 1 iterable argument, got {size}'
+            raise ValueError(msg)
+        else:
+            self._ds: tuple[D, ...] = tuple(dss[0]) if size == 1 else tuple()
+            self._len = len(self._ds)
+            try:
+                self._hash = hash((self._len, 42) + self._ds)
+            except TypeError as exc:
+                msg = f'ImmutableList: {exc}'
+                raise TypeError(msg)
+
+    def __hash__(self) -> int:
+        return self._hash
+
+    def __iter__(self) -> Iterator[D]:
+        return iter(self._ds)
+
+    def __reversed__(self) -> Iterator[D]:
+        return reversed(self._ds)
+
+    def __bool__(self) -> bool:
+        return bool(self._ds)
+
+    def __len__(self) -> int:
+        return len(self._ds)
+
+    def __repr__(self) -> str:
+        return 'immutable_list(' + ', '.join(map(repr, self)) + ')'
+
+    def __str__(self) -> str:
+        return '((' + ', '.join(map(repr, self)) + '))'
+
+    def __eq__(self, other: object, /) -> bool:
+        if not isinstance(other, ImmutableList):
+            return NotImplemented  # magic object
+        if self._len != other._len:
+            return False
+        if self._ds is other._ds:
+            return True
+        return self._ds == other._ds
+
+    @overload
+    def __getitem__(self, idx: int, /) -> D: ...
+    @overload
+    def __getitem__(self, idx: slice, /) -> ImmutableList[D]: ...
+
+    def __getitem__(self, idx: slice | int, /) -> ImmutableList[D] | D:
+        if isinstance(idx, slice):
+            return ImmutableList(self._ds[idx])
+        return self._ds[idx]
+
+    def foldl[L](
+        self,
+        f: Callable[[L, D], L],
+        /,
+        start: L | None = None,
+        default: L | None = None,
+    ) -> L | None:
+        """Fold Left
+
+        - fold left with an optional starting value
+        - first argument of function ``f`` is for the accumulated value
+        
+        "raises ValueError: when empty and a start value not given
+        """
+        it = iter(self._ds)
+        if start is not None:
+            acc = start
+        elif self:
+            acc = cast(L, next(it))  # L_co = D_co in this case
+        else:
+            if default is None:
+                msg0 = 'ImmutableList: foldl method requires '
+                msg1 = 'either start or default to be defined for '
+                msg2 = 'an empty ImmutableList'
+                raise ValueError(msg0 + msg1 + msg2)
+            acc = default
+        for v in it:
+            acc = f(acc, v)
+        return acc
+
+    def foldr[R](
+        self,
+        f: Callable[[D, R], R],
+        /,
+        start: R | None = None,
+        default: R | None = None,
+    ) -> R | None:
+        """Fold Right
+
+        - fold right with an optional starting value
+        - second argument of function ``f`` is for the accumulated value
+
+        "raises ValueError: when empty and a start value not given
+        """
+        it = reversed(self._ds)
+        if start is not None:
+            acc = start
+        elif self:
+            acc = cast(R, next(it))
+        else:
+            if default is None:
+                msg0 = 'ImmutableList: foldr method requires '
+                msg1 = 'either start or default to be defined for '
+                msg2 = 'an empty ImmutableList'
+                raise ValueError(msg0 + msg1 + msg2)
+            acc = default
+        for v in it:
+            acc = f(v, acc)
+        return acc
+
+    def __add__(self, other: ImmutableList[D], /) -> ImmutableList[D]:
+        if not isinstance(other, ImmutableList):
+            msg = 'ImmutableList being added to something not a ImmutableList'
+            raise ValueError(msg)
+
+        return ImmutableList(concat(self, other))
+
+    def __mul__(self, num: int, /) -> ImmutableList[D]:
+        return ImmutableList(self._ds.__mul__(num if num > 0 else 0))
+
+    def __rmul__(self, num: int, /) -> ImmutableList[D]:
+        return ImmutableList(self._ds.__mul__(num if num > 0 else 0))
+
+    def accummulate[L](
+        self, f: Callable[[L, D], L], s: L | None = None, /
+    ) -> ImmutableList[L]:
+        """Accumulate partial folds
+
+        Accumulate partial fold results in an ImmutableList with
+        an optional starting value.
+        """
+        if s is None:
+            return ImmutableList(accumulate(self, f))
+        return ImmutableList(accumulate(self, f, s))
+
+    def map[U](self, f: Callable[[D], U], /) -> ImmutableList[U]:
+        return ImmutableList(map(f, self))
+
+    def bind[U](
+        self, f: Callable[[D], ImmutableList[U]], type: FM = FM.CONCAT, /
+    ) -> ImmutableList[U] | Never:
+        """Bind function `f` to the `ImmutableList`.
+
+        - FM Enum types
+
+          - CONCAT: sequentially concatenate iterables one after the other
+          - MERGE: round-robin merge iterables until one is exhausted
+          - EXHAUST: round-robin merge iterables until all are exhausted
+        """
+        match type:
+            case FM.CONCAT:
+                return ImmutableList(concat(*map(f, self)))
+            case FM.MERGE:
+                return ImmutableList(merge(*map(f, self)))
+            case FM.EXHAUST:
+                return ImmutableList(exhaust(*map(f, self)))
+
+        raise ValueError(f'ImmutableList: Unknown FM type: {type}')
+
+
+def immutable_list[T](*ts: T) -> ImmutableList[TabError]:
+    """Function to produce an ``ImmutableList`` from a variable number of arguments.
+
+    :param ds: initial values to push onto a new ImmutableList from right to left
+    """
+    return ImmutableList(ts)