funstruct 0.1.2__tar.gz → 1.0.1__tar.gz

funstruct-1.0.1/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/andrewstefanich/dev/jf/jellyfish/**)",
+      "Bash(make start-auth-build *)"
+    ]
+  }
+}

funstruct-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --dev
+      - run: uv run ruff check funstruct/
+      - run: uv run ruff format --check funstruct/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --dev
+      - run: uv run ty check funstruct/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --dev
+      - run: uv run pytest tests/ funstruct/ -q

funstruct-1.0.1/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --group docs
+      - name: Deploy docs
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if [ "${{ github.event_name }}" = "release" ]; then
+            VERSION=${{ github.event.release.tag_name }}
+          else
+            VERSION=dev
+          fi
+          uv run mike deploy "$VERSION" latest --update-aliases --push
+          uv run mike set-default latest --push

funstruct-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

funstruct-1.0.1/.gitignore

@@ -0,0 +1,136 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# personal dev configs
+pyrightconfig.json
+coc-settings.json
+.vimspector.json
+notes.txt
+.benchmarks/

funstruct-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.4
+    hooks:
+      - id: ruff-format # Run the formatter.
+        args:
+          - --config
+          - pyproject.toml
+      - id: ruff # Run the linter.
+        args:
+          - --config
+          - pyproject.toml
+          - --fix
+        stages: [pre-push]
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-mkdocs
+  - repo: local
+    hooks:
+      - id: typecheck
+        name: typecheck
+        entry: bash -c "just check"
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

funstruct-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+This repo utilizes [just](https://github.com/casey/just), which defines a set of common
+commands. Simply type `just` to see a list of available commands. These commands are for
+testing, debugging, etc.
+
+## Formatting/Linting
+
+This repo utilizes [ruff](https://github.com/astral-sh/ruff). Initial Setup:
+
+- `mise trust && mise install`

funstruct-1.0.1/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: funstruct
+Version: 1.0.1
+Summary: Fun & functional structures for Python
+Project-URL: Homepage, https://veyga.github.io/funstruct/
+Project-URL: Documentation, https://veyga.github.io/funstruct/
+Project-URL: Repository, https://github.com/veyga/funstruct
+Author-email: Andrew Stefanich <andrewstefanich@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cons,data structures,fp,functional,immutable
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# funstruct
+
+A helpful collection of functional utilities.
+
+## Install
+
+```bash
+pip install funstruct || uv add funstruct
+```
+
+## Functional Primer
+
+### Type Class Hierarchy
+
+```
+Semigroup              Functor
+    │                      │
+ Monoid              Applicative
+                           │
+                         Monad
+                           │
+                    MonadTransformer
+```
+
+#### Diagrams
+
+**Semigroup** — associative combine (`+` being the canonical 'combine' operation)
+
+```
+A ─┐
+    ├──( + )──> A
+A ─┘
+```
+
+**Monoid** — semigroup with an identity element
+
+```
+A ─┐
+    ├──( + )──> A       (+ identity = A)
+A ─┘
+```
+
+**Functor** — transform the value inside a context
+
+```
+F[A] ---( f: A -> B )---> F[B]
+```
+
+**Applicative** — combine independent computations
+
+```
+F[A] ─┐
+       ├──> F[(A, B)]
+F[B] ─┘
+```
+
+**Monad** — sequence computations that produce new contexts
+
+```
+F[A] ---( f: A -> F[B] )---> F[B]
+```
+
+```python
+@dataclass(frozen=True)
+class Semigroup:
+    typ: type
+    combine: Callable  # (A, A) -> A
+
+@dataclass(frozen=True)
+class Monoid(Semigroup):
+    typ: type
+    combine: Callable  # (A, A) -> A
+    empty: object      # identity element
+
+class Functor(ABC):
+    def map(self, f) -> Functor: ...
+
+class Applicative(Functor):
+    def pure(cls, value) -> Applicative: ...
+    def ap(self, other) -> Applicative: ...
+    def __add__ = ap  # alias
+
+class Monad(Applicative):
+    def bind(self, f) -> Monad: ...
+    def do(cls, gen_fn) -> Monad: ...
+    def __rshift__ = bind  # >>
+
+class MonadTransformer(Monad, Generic[_F, _A]):
+    def lift_f(cls, inner: _F) -> MonadTransformer: ...
+    def and_then(self, other) -> MonadTransformer: ...
+```
+
+```python
+# Multiple semigroups for the same type:
+int_add = Monoid(typ=int, combine=lambda a, b: a + b, empty=0)
+int_mul = Monoid(typ=int, combine=lambda a, b: a * b, empty=1)
+```
+
+### ~ Scala equivalent
+
+```scala
+trait Semigroup[A] {
+  def combine(x: A, y: A): A
+}
+
+trait Monoid[A] extends Semigroup[A] {
+  def empty: A
+}
+
+trait Functor[F[_]] {
+  def map[A, B](fa: F[A])(f: A => B): F[B]
+}
+
+trait Applicative[F[_]] extends Functor[F] {
+  def pure[A](a: A): F[A]
+  def ap[A, B](ff: F[A => B])(fa: F[A]): F[B]
+}
+
+trait Monad[F[_]] extends Applicative[F] {
+  def bind(fa: F[A])(f: A => F[B]): F[B]
+}
+```
+
+### Implementations
+
+| Typeclass        | Implementations                              |
+| ---------------- | -------------------------------------------- |
+| Functor          | Tree, frozendict, + all below                |
+| Applicative      | Validated, + all below                       |
+| Monad            | Option, Either, State, Reader, Writer, CList |
+| MonadTransformer | ReaderT, StateT, EitherT, OptionT, WriterT   |
+
+| Type                | What it models                              |
+| ------------------- | ------------------------------------------- |
+| `Option[A]`         | Value might not exist                       |
+| `Either[E, A]`      | Value or typed error                        |
+| `Result[A]` (alias) | `Either[Exception, A]` + `@Try` decorator   |
+| `State[S, A]`       | Stateful computation                        |
+| `Reader[Ctx, A]`    | Shared environment                          |
+| `Writer[W, A]`      | Accumulated output                          |
+| `Validated[E, A]`   | Error accumulation (applicative, not monad) |
+| `Future[E, A]`      | Lazy async + typed error                    |
+| `CList[A]`          | Persistent singly-linked list               |
+| `Tree[A]`           | Immutable binary tree (functor only)        |
+| `frozendict[K, V]`  | Persistent HAMT dictionary                  |
+
+### Monad Transformers
+
+A transformer combines effects by wrapping one monad inside another.
+
+```
+ReaderT[F, Ctx, A]  =  Ctx -> F[A]         (environment + F's effects)
+StateT[F, S, A]     =  S -> F[(S, A)]      (state + F's effects)
+EitherT[F, E, A]    =  F[Either[E, A]]     (errors + F's effects)
+OptionT[F, A]       =  F[Option[A]]        (absence + F's effects)
+WriterT[F, W, A]    =  F[(A, W)]           (output + F's effects)
+```
+
+**Why transformers?** Monads don't compose automatically. If you need
+config + errors + logging, you'd manually unwrap 3 nested layers at
+every step. Transformers flatten that into one `bind`:
+
+```python
+# Without transformer — nested pattern matching at every step:
+result = fetch_user(id)  # Either[Err, Option[User]]
+match result:
+    case Left(e):
+        ...  # handle error
+    case Right(Nothing()):
+        ...  # handle absence
+    case Right(Some(user)):
+        ...  # finally, the value
+
+# With OptionT — one flat pipeline:
+pipeline = (
+    OptionT(fetch_user(id))
+    .bind(lambda user: OptionT(get_email(user)))
+    .map(lambda email: email.upper())
+)
+```
+
+### Laws
+
+Every implementation must satisfy these mathematical laws:
+
+**Semigroup**
+
+- Associativity: `(a + b) + c == a + (b + c)`
+
+**Monoid**
+
+- Left identity: `empty + a == a`
+- Right identity: `a + empty == a`
+
+**Functor**
+
+- Identity: `fa.map(id) == fa`
+- Composition: `fa.map(f).map(g) == fa.map(g ∘ f)`
+
+**Applicative**
+
+- Identity: `pure(id).ap(v) == v`
+- Homomorphism: `pure(f).ap(pure(x)) == pure(f(x))`
+- Interchange: `u.ap(pure(y)) == pure(λf. f(y)).ap(u)`
+- Composition: `pure(∘).ap(u).ap(v).ap(w) == u.ap(v.ap(w))`
+
+**Monad**
+
+- Left identity: `pure(a).bind(f) == f(a)`
+- Right identity: `m.bind(pure) == m`
+- Associativity: `m.bind(f).bind(g) == m.bind(λx. f(x).bind(g))`
+
+## Why no IO type?
+
+In Haskell, `IO` exists because the language is purely functional — there is
+no way to perform side effects without wrapping them in the `IO` monad. The
+type system enforces purity: if a function doesn't return `IO`, it cannot
+touch the network, filesystem, or mutable state.
+
+Python has no such constraint. Any function can perform side effects at any
+time. An `IO` wrapper in Python would be:
+
+1. **Unenforceable** — nothing stops you from doing I/O outside the wrapper.
+    The type system can't prevent `print()` in a "pure" function.
+1. **Purely ceremonial** — it adds a wrapper you must manually construct and
+    unwrap, but provides no guarantee. It's a comment dressed as a type.
+1. **Redundant with async** — Python's `async/await` already separates
+    "description of a computation" from "execution of that computation,"
+    which is most of what `IO` provides in Haskell.
+
+Instead, funstruct provides:
+
+- **`Either[E, A]`** — for operations that might fail (the error is a value)
+- **`Future[E, A]`** — for async operations that might fail (lazy, composable)
+- **`@Try` / `@TryAsync`** — for wrapping exception-throwing code at boundaries
+
+These give you the composition benefits of monadic pipelines where they
+matter (error handling, async sequencing) without pretending Python is
+something it isn't.