functorial 0.1.1__tar.gz

functorial-0.1.1/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)"
+    ]
+  }
+}

functorial-0.1.1/.dir-locals.el

@@ -0,0 +1,4 @@
+;;; Directory Local Variables            -*- no-byte-compile: t -*-
+;;; For more information see (info "(emacs) Directory Variables")
+
+((python-mode . ((pyvenv-activate . "/Users/genovese/.local/venvs/default14"))))

functorial-0.1.1/.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 120
+ignore = E201, E202, E241, E266, E272, E302, E305, E731, W503, W504

functorial-0.1.1/.gitignore

@@ -0,0 +1,25 @@
+# -*- mode: fundamental; -*-
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.hypothesis
+
+# Virtual environments
+.venv
+
+# Ignore emacs backup files (at least, the ones I generate)
+.*~
+# Ignore scratch file
+.bonz
+.save
+# Ignore mac specific junk
+.DS_Store
+
+# Temporary Notes file
+Notes.md
+TODO

functorial-0.1.1/.pylintrc

@@ -0,0 +1,46 @@
+[DESIGN]
+
+# Maximum number of return statements in a function (see R0915)
+max-returns = 10
+
+# Maximum number of boolean expressions in an if statement (see R0916).
+max-bool-expr = 8
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods = 0
+
+[FORMAT]
+
+# Maximum number of characters on a single line.
+max-line-length=120
+
+[MESSAGES CONTROL]
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once). You can also use "--disable=all" to
+# disable everything first and then re-enable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use "--disable=all --enable=classes
+# --disable=W".
+disable=raw-checker-failed,
+        bad-inline-option,
+        locally-disabled,
+        file-ignored,
+        suppressed-message,
+        useless-suppression,
+        deprecated-pragma,
+        use-symbolic-message-instead,
+        use-implicit-booleaness-not-comparison-to-string,
+        use-implicit-booleaness-not-comparison-to-zero,
+        too-few-public-methods,
+        unnecessary-ellipsis,
+        unnecessary-lambda-assignment
+
+
+[VARIABLES]
+
+# List of names allowed to shadow builtins
+allowed-redefined-builtins=map

functorial-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

functorial-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Christopher R. Genovese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

functorial-0.1.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: functorial
+Version: 0.1.1
+Summary: Functional Programming concepts playground
+Author-email: "Christopher R. Genovese" <genovese@cmu.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# functorial
+
+Functional-programming concepts for Python: typeclasses (Functor, Applicative,
+Monad, Foldable, Traversable, Alternative, ...), standard FP data types
+(`Maybe`, `Either`, `List`, `Dict`, `NTuple`, trees, `IO`, `Reader`, `Writer`,
+`State`), and a profunctor-based optics library (lenses, prisms, traversals,
+folds, isos, and their indexed variants).
+
+This is an evolving, educational project — the API is still settling and not
+everything on the roadmap is implemented yet. Feedback and issues are welcome.
+
+## Installation
+
+```bash
+pip install functorial
+# or
+uv add functorial
+```
+
+Requires Python 3.12+.
+
+## Quick taste
+
+```python
+from functorial.maybe import Some, Nothing
+from functorial.optics.lens import lens
+from functorial.optics.getter import view
+from functorial.optics.setter import over
+
+# Maybe: a Functor/Applicative/Monad/Traversable
+Some(3).map(lambda x: x + 1)     # Some(4)
+Nothing().map(lambda x: x + 1)   # Nothing()
+
+# Optics: compose lenses with @, act on them with view/over
+fst = lens(lambda s: s[0], lambda s, b: (b, s[1]))
+snd = lens(lambda s: s[1], lambda s, b: (s[0], b))
+
+view(fst)((1, 2))                     # 1
+over(fst @ snd, str)(((1, 2), 3))     # ((1, '2'), 3)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

functorial-0.1.1/README.md

@@ -0,0 +1,51 @@
+# functorial
+
+Functional-programming concepts for Python: typeclasses (Functor, Applicative,
+Monad, Foldable, Traversable, Alternative, ...), standard FP data types
+(`Maybe`, `Either`, `List`, `Dict`, `NTuple`, trees, `IO`, `Reader`, `Writer`,
+`State`), and a profunctor-based optics library (lenses, prisms, traversals,
+folds, isos, and their indexed variants).
+
+This is an evolving, educational project — the API is still settling and not
+everything on the roadmap is implemented yet. Feedback and issues are welcome.
+
+## Installation
+
+```bash
+pip install functorial
+# or
+uv add functorial
+```
+
+Requires Python 3.12+.
+
+## Quick taste
+
+```python
+from functorial.maybe import Some, Nothing
+from functorial.optics.lens import lens
+from functorial.optics.getter import view
+from functorial.optics.setter import over
+
+# Maybe: a Functor/Applicative/Monad/Traversable
+Some(3).map(lambda x: x + 1)     # Some(4)
+Nothing().map(lambda x: x + 1)   # Nothing()
+
+# Optics: compose lenses with @, act on them with view/over
+fst = lens(lambda s: s[0], lambda s, b: (b, s[1]))
+snd = lens(lambda s: s[1], lambda s, b: (s[0], b))
+
+view(fst)((1, 2))                     # 1
+over(fst @ snd, str)(((1, 2), 3))     # ((1, '2'), 3)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

functorial-0.1.1/pyproject.toml

@@ -0,0 +1,122 @@
+[project]
+name = "functorial"
+dynamic = ["version"]
+description = "Functional Programming concepts playground"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "Christopher R. Genovese", email = "genovese@cmu.edu" }
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.118.0",
+    "pytest>=8.3.3",
+    "ruff>=0.7.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/functorial/__about__.py"
+
+[[tool.hatch.envs.all.matrix]]
+python = ["3.12", "3.13", "3.14"]
+
+[tool.black]
+target-version = ["py312"]
+line-length = 120
+skip-string-normalization = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+lint.select = [
+  "A",
+  "ARG",
+  "B",
+  "C",
+  "DTZ",
+  "E",
+  "EM",
+  "F",
+  "FBT",
+  "I",
+  "ICN",
+  "ISC",
+  "N",
+  "PLC",
+  "PLE",
+  "PLR",
+  "PLW",
+  "Q",
+  "RUF",
+  "S",
+  "T",
+  "TID",
+  "UP",
+  "W",
+  "YTT",
+]
+
+lint.ignore = [
+  # My ignores
+  "I001", "EM101", "Q000", "E501", "N999", # Ruff doesn't support "E241", "E272", "E302", "E305", "W504",
+  # Allow non-abstract empty methods in abstract base classes
+  "B027",
+  # Allow boolean positional values in function calls, like `dict.get(... True)`
+  "FBT003",
+  # Ignore checks for possible passwords
+  "S105", "S106", "S107",
+  # Ignore complexity
+  "C901", "PLR0911", "PLR0912", "PLR0913", "PLR0915",
+]
+
+lint.unfixable = [
+  # Don't touch unused imports
+  "F401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can use magic values, assertions, and relative imports
+"tests/**/*" = ["PLR2004", "S101", "TID252"]
+
+[tool.ruff.lint.isort]
+section-order = ["future", "standard-library", "first-party", "local-folder", "third-party"]
+lines-between-types = 1
+lines-after-imports = 1
+
+[tool.pylint]
+max-line-length = 120
+max-bool-expr = 8
+min-public-methods = 0
+allowed-redefined-builtins = ["map"]
+disable = [
+    "raw-checker-failed",
+    "bad-inline-option",
+    "locally-disabled",
+    "file-ignored",
+    "suppressed-message",
+    "useless-suppression",
+    "deprecated-pragma",
+    "use-symbolic-message-instead",
+    "use-implicit-booleaness-not-comparison-to-string",
+    "use-implicit-booleaness-not-comparison-to-zero",
+    "too-few-public-methods",
+    "unnecessary-ellipsis",
+    "unnecessary-lambda-assignment"
+]

functorial-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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