graftpy

Graftable Python — functions you can pip install or lift into any project.

Your code has two readers now: the humans on your team and the AI writing alongside them. graftpy is built to be legible — and liftable — by both. (read the manifesto)

pip install graftpy                          # use it as a dependency...
python -m graftpy show retry_with_backoff    # ...or graft one self-contained file

Most "utility" libraries make you choose: install the whole package and accept its web of internal imports, or copy a snippet off Stack Overflow with no types, no tests, and no idea if it's right. graftpy refuses the trade-off.

Every function here lives in its own file, depends only on the standard library (plus, at most, one clearly-declared third-party package), and never imports a sibling. So you can use it however you — or your AI coding agent — like:

# 1) install it
pip install graftpy
from graftpy.decorators import retry_with_backoff

# 2) ...or graft a single, self-contained file straight into your project
python -m graftpy show retry_with_backoff > myproject/retry.py

Both give you the exact same code: fully typed, documented, and covered by a runnable example.

Why "graftable"? The one principle

We optimize for lift, not DRY.

If two functions need the same little helper, each carries its own copy. We trade a bit of duplication for a hard guarantee: any function is one Ctrl-C away from living in your codebase, with nothing to untangle. That guarantee isn't a promise — it's enforced in CI (tools/check_liftability.py), so it can't silently rot.

Built for humans and AI, on purpose

Coding is increasingly a conversation with an AI. A library that agents can read, find, and reuse reliably is worth ten that they can't. So graftpy is designed to be legible to both:

• One job per file, descriptive names → grep-able and embedding-searchable.
• Full type hints + Google-style docstrings + a runnable example → an agent can understand and call any function correctly from its signature alone.
• A machine-readable catalog (catalog.json) and an agent guide (AGENTS.md / llms.txt) → an agent can discover the right function without reading the whole repo.
• python -m graftpy show <name> → an agent (or you) can fetch one function's verbatim source with zero install.

Quickstart

from graftpy.iterables import chunked
for batch in chunked(range(7), 3):
    print(batch)          # [0, 1, 2] / [3, 4, 5] / [6]

from graftpy.decorators import retry_with_backoff

@retry_with_backoff(retries=5, base_delay=0.2)
def fetch(url): ...

The CLI

python -m graftpy list                    # every graftable function + one-liner
python -m graftpy search retry            # find by name / summary / tag
python -m graftpy show chunked            # print the standalone source to lift

How it's organized

src/graftpy/<category>/<function>.py   # one public function per file

Browse the full, auto-generated list in INDEX.md. Categories (e.g. iterables, decorators) are shallow on purpose — deep nesting hurts both humans and retrieval.

Contributing

New functions are welcome — but they have to clear the bar that makes graftpy what it is. See CONTRIBUTING.md: self-contained, fully typed, docstring with a runnable example, one function per file. CI checks all of it.

License

MIT — lift freely.