braincraft

A workshop of small, sharp utilities — carefully shaped helpers you reuse across projects to keep everyday coding tasks fast, tidy, and consistent.

Prerequisites

• Python >=3.14

Installation

Install via pip:

pip install braincraft

Or add it as a Poetry dependency:

poetry add braincraft

Components

graph TD
    A[braincraft] --> B[ignorefile]
    A --> C[retry]
    B --> B1["IgnoreFile — gitignore-style path matching"]
    B --> B2["PatternHandler — extensible custom pattern handlers"]
    C --> C1["retry_rand_exp — async retry with full-jitter back-off"]

Usage

IgnoreFile

Reads a gitignore-style ignore file and determines whether a given path should be ignored. Pattern matching follows the full gitignore specification: *, ?, [...] wildcards, negation (!), directory-only patterns (trailing /), ** double-star rules, and anchoring.

Anchored patterns (containing / at the start or middle, e.g. doc/build or /dist) are matched relative to a base directory — by default the current working directory at the time IgnoreFile is created. An explicit base_dir (str | Path) can be supplied to override this. The ignore file can live anywhere, independently of base_dir.

Matching always occurs — no error is raised for paths outside the base directory.

from pathlib import Path
from braincraft import IgnoreFile

ig = IgnoreFile(Path(".gitignore"))

print(ig.is_ignored(Path("dist/output.js")))       # True
print(ig.is_ignored(Path("src/main.py")))          # False
print(ig.is_ignored(Path("build/")))               # True (if build/ is a directory)

Custom base directory

By default IgnoreFile uses the current working directory as the root for anchored patterns. Pass base_dir (str or Path) to pin matching to a specific directory regardless of where the process is running or where the ignore file lives.

from pathlib import Path
from braincraft import IgnoreFile

project = Path("/srv/myproject")
ig = IgnoreFile(project / ".gitignore", base_dir=project)

# Anchored pattern /dist matches relative to project, not the process CWD
print(ig.is_ignored(project / "dist" / "bundle.js"))   # True
print(ig.is_ignored(project / "src" / "main.py"))      # False

# Works equally well with plain strings
ig2 = IgnoreFile("/srv/myproject/.gitignore", base_dir="/srv/myproject")
print(ig2.is_ignored("/srv/myproject/dist/bundle.js"))  # True

Custom pattern handlers

Extend matching behaviour by registering a PatternHandler subclass. Custom handlers are consulted first; returning None falls through to the built-in gitignore handler.

from pathlib import Path
from braincraft import IgnoreFile, PatternHandler


class SizePatternHandler(PatternHandler):
    """Ignore files larger than a size encoded as 'size:>NNN' in the ignore file."""

    def matches(self, pattern: str, path: Path, base_dir: Path) -> bool | None:
        if not pattern.startswith("size:>"):
            return None  # not our pattern — let the built-in handle it
        limit = int(pattern.removeprefix("size:>"))
        if path.is_file():
            return path.stat().st_size > limit
        return None


ig = IgnoreFile(Path(".myignore"))
ig.register_handler(SizePatternHandler())

print(ig.is_ignored(Path("huge_dump.bin")))  # True if file > limit

retry_rand_exp

Calls an async coroutine with automatic retry and full-jitter exponential back-off. Retries on any exception up to max_attempts times, sleeping a random jittered duration between attempts. Re-raises the last exception when all attempts are exhausted.

from braincraft import retry_rand_exp

async def fetch_data(url: str) -> str:
    # your async operation here
    ...

result = await retry_rand_exp(
    fetch_data,
    "https://example.com/api",
    max_attempts=5,
    base_delay=1.0,
    max_delay=30.0,
)

Development

Prerequisites

• Poetry 2.2+

Install dependencies

poetry install

Format and lint

poetry run black braincraft; poetry run pylint braincraft

Run tests with coverage

poetry run pytest --cov=braincraft tests --cov-report html

Changelog

See CHANGELOG.md for a full history of changes.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Author

Ron Webb