Metadata-Version: 2.4
Name: graftpy
Version: 0.2.0
Summary: Graftable Python: self-contained functions you can pip-install or lift into any project.
Project-URL: Homepage, https://github.com/THartyMBA/graftpy
Project-URL: Source, https://github.com/THartyMBA/graftpy
Author-email: "Dr. Tom Harty, DBA" <tom.hartymba@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,copy-paste,graftable,reusable,snippets,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# graftpy

[![CI](https://github.com/THartyMBA/graftpy/actions/workflows/ci.yml/badge.svg)](https://github.com/THartyMBA/graftpy/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/graftpy.svg)](https://pypi.org/project/graftpy/)
[![Python](https://img.shields.io/pypi/pyversions/graftpy.svg)](https://pypi.org/project/graftpy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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](docs/manifesto.md))

```bash
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:

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

```bash
# 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`](catalog.json)) and an
  agent guide ([`AGENTS.md`](AGENTS.md) / [`llms.txt`](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

```python
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

```bash
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`](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`](CONTRIBUTING.md): self-contained, fully typed,
docstring with a runnable example, one function per file. CI checks all of it.

## License

MIT — lift freely.
