patos

A flock of typed, zero-dependency Python design patterns. Each pattern is a single self-contained pato (a duck you adopt), fully typed, standard library only, and small enough to read in one sitting.

Install

pip install patos

Or copy a single duck. Open its docs page, copy the source from the Source section, and paste it into your own project. No dependency, no version pin, no tool, just one module you own.

The optional PostgreSQL toolkit installs SQLAlchemy, pgvector, and inflection only when a project asks for them.

pip install "patos[sql]"

from patos import sql

Patterns

Creational

pato	description	docs
Singleton	one instance per class, __init__ runs once	docs
FlyweightMeta	a metaclass that interns instances by constructor args, build-once and immutable	docs

Dispatch & selection

pato	description	docs
Registry	self-registering class hierarchies via __init_subclass__, with try-each dispatch, select(predicate) and first_available()	docs
Strategy	a named family of interchangeable implementations, with first_available()	docs
value_dispatch	dispatch on a value the way singledispatch dispatches on a type	docs
type_dispatch	dispatch on the first argument's type, the open-type-ladder dual of value_dispatch	docs

Structural & lifecycle

pato	description	docs
Decorator	a transparent wrapper that forwards everything to the wrapped object but what it overrides	docs
Pipeline	a reversible stack of stages, applied forward and unwound in reverse around a core op	docs
Lifecycle	a typed state machine that permits only the transitions its table declares	docs
DerivedCache	a load-once cache of a derived value keyed by exactly what it depends on	docs

Command-line

pato	description	docs
StrFlag	an enum Flag whose members carry a literal string, OR-combinable and iterable	docs

Research registration

pato	description	docs
SourceRegistration	binds one research node to the exact source set governing a run and seals it
statement_bytes	the sealed statement of a node file, front matter and settlement sections excluded
sha256_text_file, sha256_text_sources	checkout-independent digests of registered text

The seal covers the node's statement and the whole bytes of every other registered source. The statement starts at the first ## heading after the front matter and ends before the first ## Evidence, ## Ledger or ## Log heading, matched without regard to case. Front matter is never sealed, so status, date and the registration_sha256 field itself move freely, and a node that settles and appends to its log still verifies against the claim it was registered under. Every source is hashed as relative POSIX path \0 LF-normalized bytes \0, ordered by path, which keeps one seal identical on Windows and POSIX checkouts alike.

Optional extensions

namespace	description	docs
sql	typed SQLModel columns, native PostgreSQL enums, pgvector cosine distance, JSONB reads, and set based SQL helpers	docs

Example

from patos import Singleton


class Settings(Singleton):
    def __init__(self) -> None:
        self.debug = False


a = Settings()
a.debug = True
b = Settings()      # same object, __init__ did not run again

assert a is b and b.debug

Documentation

Full documentation lives at phvv.me/patos.

Development

• Install: pip install -e ".[dev]"
• Lint: ruff check . && ruff format --check .
• Typecheck: pyrefly check
• Test: pytest
• Docs: pip install -e ".[docs]" && mkdocs build
• Build: python -m build