functorial 0.1.1__py3-none-any.whl

functorial/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2024-present Christopher R. Genovese <genovese@cmu.edu>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.1.1"

functorial/__init__.py

@@ -0,0 +1,29 @@
+__all__ = [
+    'applicative',
+    'bicofunctor',
+    'bifunctor',
+    'bitraversable',
+    'cofunctor',
+    'const',
+    'dict',
+    'either',
+    'foldable',
+    'functor',
+    'identity',
+    'list',
+    'maybe',
+    'monad',
+    'monoids',
+    'ntuple',
+    'pair',
+    'profunctor',
+    'reader',
+    'set',
+    'state',
+    'traversable',
+    'trees',
+    'functions',
+    'ops',
+    'optics',
+    'utils',
+]

functorial/all.py

@@ -0,0 +1,54 @@
+#
+# Helper module to load all the names into the namespace
+#
+# Do 'from FP.all import *' to load all the needed objects.
+#
+# ruff: noqa: F401, F403, F405
+
+from __future__ import annotations
+
+from . import monoids
+from . import optics
+
+from .alternative import *
+from .applicative import *
+from .bicofunctor import *
+from .bifunctor   import *
+from .cofunctor   import *
+from .foldable    import *
+from .functor     import *
+from .monad       import *
+from .profunctor  import *
+from .traversable import *
+
+from .const       import *
+from .either      import *
+from .identity    import *
+from .list        import *
+from .maybe       import *
+from .ntuple      import *
+from .pair        import *
+
+from .dict        import *
+from .monoids     import Monoid, munit, mcombine
+from .reader      import *
+from .set         import *
+from .state       import *
+from .trees       import *
+from .writer      import *
+
+from .functions   import *
+from .io          import *
+from .ops         import *
+from .utils       import *
+from .wrappers    import *
+
+from .pair        import pair  # More powerful version over .functions.pair
+
+from .optics.all  import *
+
+#
+# Conveniences
+#
+
+c = compose

functorial/alternative.py

@@ -0,0 +1,36 @@
+# trait Applicative f => Alternative (f : Type -> Type) where
+#     empty : f a
+#     alt   : f a -> f a -> f a
+
+from __future__   import annotations
+
+from abc          import abstractmethod
+from typing       import Protocol
+
+from .applicative import Applicative
+
+__all__ = ['Alternative', 'alt', 'guard']
+
+
+#
+# Alternative as a mixin
+#
+
+# ATTN: Should this have a type parameter or be handled like Applicative?
+
+class Alternative[A](Applicative, Protocol):
+    @classmethod
+    def empty(cls) -> Alternative[A]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def alt(self, fb: Alternative[A]) -> Alternative[A]:
+        ...
+
+def alt[A](fa: Alternative[A], fb: Alternative[A]) -> Alternative[A]:
+    return fa.alt(fb)
+
+def guard(f: type[Alternative], condition: bool) -> Alternative[tuple[()]]:  # ATTN: type Unit = tuple[()]
+    return f.unit() if condition else f.empty()
+
+# ATTN: Include some and many?  Can we implement them?

functorial/applicative.py

@@ -0,0 +1,168 @@
+# trait Functor f => Applicative (f : Type -> Type) where
+#     pure : a -> f a
+#     map2 : (a -> b -> c) -> f a -> f b -> f c    -- lift2 := map2 h
+#     ap   : f (a -> b) -> f a -> f b
+#
+#     unit : f Unit                                -- Unit equiv ()
+#     combine : f a -> f b -> f (a, b)
+
+from __future__ import annotations
+
+from abc             import abstractmethod
+from collections.abc import Callable
+from typing          import Protocol, runtime_checkable
+
+from .functor        import Functor, map                   # pylint: disable=redefined-builtin
+from .functions      import compose, const, curry, identity, pair, fn_eval, eval_with
+
+__all__ = [
+    'Applicative', 'map2', 'combine', 'pure',
+    'ap', 'lift2', 'ap_first', 'ap_second', 'rev_ap',
+    'when', 'unless',  # ATTN: needed?
+    'IdentityA',
+]
+
+
+#
+# Applicative as a mixin
+#
+
+@runtime_checkable
+class Applicative(Functor, Protocol):
+    @classmethod
+    def pure(cls, a):
+        raise NotImplementedError
+
+    @abstractmethod
+    def map2(self, g, fb):
+        ...
+
+    @classmethod
+    def unit(cls):
+        return cls.pure( () )
+
+    def combine(self, fb):
+        return self.map2(pair, fb)
+
+    def ap(self, fb):
+        return self.map2(fn_eval, fb)
+
+
+def map2(g, fa, fb):
+    return fa.map2(g, fb)
+
+def combine(fa, fb):
+    return fa.combine(fb)
+
+def pure(fa, a):
+    return fa.pure(a)
+
+def ap(fa_to_b: Applicative | Callable, fa: Applicative, *fs: Applicative, auto_curry=True) -> Applicative:
+    if not isinstance(fa_to_b, Applicative):
+        if auto_curry:
+            fa_to_b = fa.pure(curry(fa_to_b))
+        else:
+            fa_to_b = fa.pure(fa_to_b)
+    # elif auto_curry:
+    #     fa_to_b = fa_to_b.map(curry)  # ATTN: PROVISIONAL
+
+    fb = fa_to_b.ap(fa)      # type: ignore
+    for fx in fs:
+        fb = fb.ap(fx)
+    return fb
+
+# ATTN: by our emerging convention, this should be called map2_, though this name is good too
+def lift2[A, B, C](f: Callable[[A, B], C]):
+    """Lifts a two-argument function to a mapping of Applicatives.
+
+    This is just the partial application map2(f, _, __).
+    The applicatives should be the same type (technically
+    one should be a subclass of the other).
+
+    """
+    def liftA2(fa: Applicative, fb: Applicative) -> Applicative:
+        if not issubclass(fa.__class__, fb.__class__) and not issubclass(fb.__class__, fa.__class__):
+            raise TypeError('lift2(f) should be applied to compatible applicatives.')
+        return fa.map2(f, fb)
+
+    return liftA2
+
+map2_ = lift2   # Alias for lift2 that matches our naming convention
+
+def rev_ap(fa: Applicative, fa_to_b: Applicative | Callable, auto_curry=True) -> Applicative:
+    """A variant of ap with the arguments reversed and effects resolved in the order given.
+
+    Note that rev_ap differs from flip(ap) in the order in which effects
+    are resolved. The latter would just remap the argument order into ap,
+    but this resolves fa then fa_to_b.
+
+    Unlike ap, this only takes two arguments, but it does do automatic currying
+    if auto_curry is True, which is the default.
+
+    Returns the resulting applicative.
+
+    """
+    if not isinstance(fa_to_b, Applicative):
+        if auto_curry:
+            fa_to_b = fa.pure(curry(fa_to_b))
+        else:
+            fa_to_b = fa.pure(fa_to_b)
+
+    return fa.map2(eval_with, fa_to_b)
+
+# (<*) : f a -> f b -> f a
+def ap_first(fa: Applicative, fb: Applicative) -> Applicative:
+    "Sequence actions, disgarding the value of the second argument."
+    return fa.map2(lambda a, b: a, fb)
+
+# (*>) : f a -> f b -> f b
+def ap_second(fa: Applicative, fb: Applicative) -> Applicative:
+    "Sequence actions, disgarding the value of the first argument."
+    return ap(map(compose(identity, const), fa), fb)
+
+# ATTN: implement when and unless here? Are they useful at all for us, as we don't need it for??
+# when : Applicative f => Bool -> f () -> f ()
+def when(f: type[Applicative], condition: bool, true_case: Applicative) -> Applicative:
+    return map(const(()), true_case) if condition else f.pure(())
+
+# unless : Applicative f => Bool -> f () -> f ()
+def unless(f: type[Applicative], condition: bool, false_case: Applicative) -> Applicative:
+    return f.pure(()) if condition else map(const(()), false_case)
+
+# A copy of the Identity Functor that is only an Applicative
+# This is useful as a default applicative in infrastructure
+# modules that would lead to circularity if loading Identity
+# module. See also IdentityM in case a default Monad is needed.
+
+class IdentityA[A](Applicative):
+    """A default Applicative that mimics Identity without Monad or Traversable.
+
+    This is useful in defaults only infrastructure modules in this package,
+    like Monad and Traversable, that Identity actually loads. Users should
+    not use this explicitly.
+
+    """
+    __match_args__ = ('_value',)
+
+    def __init__(self, x: A):
+        self._value = x
+
+    def __str__(self):
+        return f'IdentityA {self._value}'
+
+    def __repr__(self):
+        return f'IdentityA({self._value})'
+
+    @classmethod
+    def run(cls, fa: IdentityA[A]) -> A:
+        return fa._value
+
+    def map[B](self, g: Callable[[A], B]) -> IdentityA[B]:
+        return IdentityA(g(self._value))
+
+    @classmethod
+    def pure(cls, x: A) -> IdentityA[A]:
+        return IdentityA(x)
+
+    def map2[B, C](self, g: Callable[[A, B], C], fb: IdentityA[B]) -> IdentityA[C]:
+        return IdentityA(g(self._value, fb._value))

functorial/backwards.py

@@ -0,0 +1,18 @@
+
+# Incomplete but working
+
+from .applicative import Applicative
+from .functions   import flip
+
+def Backwards(f: type[Applicative]):
+    class Backward_f(f):
+        "A Backward version of the Applicative f."
+
+        @classmethod
+        def pure(cls, a):
+            return cls(f.pure(a))
+
+        def map2(self, g, fb):
+            return Backward_f(f(fb).map2(flip(g), f(self)))
+
+    return Backward_f

functorial/bicofunctor.py

@@ -0,0 +1,48 @@
+#
+# trait Bicofunctor (p : Type -> Type -> Type) where
+#     bicomap : (b -> a) -> (d -> c) -> p a c -> p b d
+#     bicomap f g = cofirst f . cosecond g
+#
+#     cofirst : (b -> a) -> p a c -> p b c
+#     cofirst f = bicomap f identity
+#
+#     cosecond : (d -> c) -> p a c -> p a d
+#     cosecond g : bicomap identity g
+#
+
+from __future__      import annotations
+
+from collections.abc import Callable
+from typing          import Protocol
+
+from .functions      import identity
+
+__all__ = ['Bicofunctor', 'bicomap', 'cofirst', 'cosecond']
+
+
+class Bicofunctor[A, C](Protocol):
+    # Subclasses MUST override at least ONE of these methods
+    def bicomap[B, D](self, f: Callable[[B], A], g: Callable[[C], D]) -> Bicofunctor[B, D]:
+        x = self.cosecond(g)
+        return x.cofirst(f)
+
+    def cofirst[B](self, f: Callable[[B], A]) -> Bicofunctor[B, C]:
+        return self.bicomap(f, identity)
+
+    def cosecond[D](self, g: Callable[[C], D]) -> Bicofunctor[A, D]:
+        return self.bicomap(identity, g)
+
+def bicomap[A, B, C, D](f: Callable[[B], A], g: Callable[[C], D], x: Bicofunctor[A, C]) -> Bicofunctor[B, D]:
+    return x.bicomap(f, g)
+
+def bicomap_[A, B, C, D](f: Callable[[B], A], g: Callable[[C], D]) -> Callable[[Bicofunctor[A, C]], Bicofunctor[B, D]]:
+    def do_bicomap_(x: Bicofunctor[A, C]) -> Bicofunctor[B, D]:
+        return x.bicomap(f, g)
+
+    return do_bicomap_
+
+def cofirst[A, B, C](f: Callable[[B], A], x: Bicofunctor[A, C]) -> Bicofunctor[B, C]:
+    return x.cofirst(f)
+
+def cosecond[A, C, D](g: Callable[[C], D], x: Bicofunctor[A, C]) -> Bicofunctor[A, D]:
+    return x.cosecond(g)

functorial/bifunctor.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from abc             import abstractmethod
+from collections.abc import Callable
+
+from .functor   import Functor
+from .functions import identity
+
+__all__ = ['Bifunctor', 'bimap', 'bilift', 'map_first', 'map_second',]
+
+
+#
+# Functor as a mixin
+#
+
+class Bifunctor(Functor):
+    @abstractmethod
+    def bimap[A, B, C, D](self, f: Callable[[A], C], g: Callable[[B], D]):
+        ...
+
+    def map_first[A, C](self, f: Callable[[A], C]) -> Bifunctor:
+        return self.bimap(f, identity)
+
+    def map_second[B, D](self, g: Callable[[B], D]) -> Bifunctor:
+        return self.bimap(identity, g)
+
+    def map[B, D](self, g: Callable[[B], D]):
+        return self.map_second(g)
+
+
+def bimap[A, B, C, D](f: Callable[[A], C], g: Callable[[B], D], bf: Bifunctor) -> Bifunctor:
+    "Maps functions over both components of a bifunctor, returning a transformed bifunctor."
+    return bf.bimap(f, g)
+
+def bilift[A, B, C, D](f: Callable[[A], C], g: Callable[[B], D]):
+    """Lifts functions on components to a mapping on bifunctors.
+
+    This is just the partial application bimap(f, g, __).
+
+    """
+    def lift_fg(bf: Bifunctor):
+        return bf.bimap(f, g)
+
+    return lift_fg
+
+def map_first[A, C](f: Callable[[A], C], bf: Bifunctor) -> Bifunctor:
+    "Maps a function over the first component of a bifunctor."
+    return bf.bimap(f, identity)
+
+def map_second[B, D](g: Callable[[B], D], bf: Bifunctor) -> Bifunctor:
+    "Maps a function over the second component of a bifunctor."
+    return bf.bimap(identity, g)

functorial/bitraversable.py

@@ -0,0 +1,41 @@
+#
+# Bifunctors that can be traversed in order on both variables
+#
+# trait Bitraversable (f : Type -> Type -> Type) where
+#     traverse : (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
+#
+
+from __future__ import annotations
+
+from abc             import abstractmethod
+from collections.abc import Callable
+
+from .applicative    import Applicative, IdentityA
+from .bifunctor      import Bifunctor
+from .functions      import identity
+from .wrappers       import get_effect
+
+__all__ = ['Bitraversable', 'bitraverse', 'bisequence']
+
+
+class Bitraversable(Bifunctor):
+    @abstractmethod
+    def bitraverse(self, f: type[Applicative], g1: Callable, g2: Callable) -> Applicative:   # Hard to type properly in Python
+        ...
+
+def bitraverse( g1: Callable, g2: Callable, bt: Bitraversable, effect: type[Applicative] = IdentityA) -> Applicative:
+    """Evaluates effectful functions at each element of a structure, giving the same shape in an effectful context.
+
+    Type: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
+
+    """
+    return bt.traverse(get_effect(g1) or get_effect(g2) or effect, g1, g2)
+
+
+def bisequence(bt: Bitraversable, effect: type[Applicative] = IdentityA) -> Applicative:
+    """Evaluate effects on each element of a structure, collecting the results in the effectful context.
+
+    Type: (Bitraversable t, Applicative f) =>  t a b -> f (t a b)
+
+    """
+    return bitraverse(identity, identity, bt, effect)

functorial/cofunctor.py

@@ -0,0 +1,70 @@
+#
+# Contravariant functors, the dual of Functor, or equivalently a functor on the op category.
+#
+# trait CoFunctor (f : Type -> Type) where
+#     comap : (b -> a) -> f a -> f b
+#
+
+from __future__ import annotations
+
+from abc             import abstractmethod
+from collections.abc import Callable
+from typing          import Protocol
+
+from .functions      import Function
+
+__all__ = ['CoFunctor', 'comap', 'colift', 'Predicate']
+
+#
+# CoFunctor as a mixin
+#
+
+class CoFunctor(Protocol):
+    @abstractmethod
+    def comap[A, B](self, g: Callable[[B], A]):
+        ...
+
+def comap[A, B](f: Callable[[B], A], cf: CoFunctor):
+    """Maps a function over a contravariant functor, returning a transformed cofunctor.
+
+    """
+    return cf.comap(f)
+
+def colift[A, B](f: Callable[[B], A]):
+    """Lifts a function to a mapping on cofunctors.
+
+    This is just the partial application comap(f, __).
+
+    """
+    def colift_f(cf: CoFunctor):
+        return cf.comap(f)
+
+    return colift_f
+
+
+#
+# Examples
+#
+
+class Predicate[A](Function, CoFunctor):
+    def __init__(self, predicate: Callable[[A], bool]):
+        super().__init__(predicate)
+
+    def __call__(self, x: A, *args, **kwds) -> bool:
+        return super().__call__(x, *args, **kwds)
+
+    def comap[B](self, g: Callable[[B], A]):
+        return self @ g
+
+
+#  even = Predicate(lambda x: x % 2 == 0)
+#  odd = comap(inc, even)
+#
+#  even(10)
+#  #=> True
+#  even(9)
+#  #=> False
+#  odd(10)
+#  #=> False
+#  even(9)
+#  #=> True