Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (45 loc) · 1.78 KB

AGENTS.md

File metadata and controls

58 lines (45 loc) · 1.78 KB

AGENTS.md

Purpose

This repository is a reusable Python 3.12+ package template for small, well-tested libraries. Keep changes focused, keep the public API intentional, and prefer standard-library solutions unless a third-party dependency clearly improves the maintenance story.

Setup

  • Create and activate a virtual environment:
    • python -m venv .venv
    • source .venv/bin/activate
  • The preferred interpreter target lives in .python-version (3.12).
  • Install local tooling with make dev.
  • For a frozen environment based on uv.lock, use make repro.

Testing And Validation

Use the smallest useful check while iterating, then run the full gate before merging.

  • Fast local loop:
    • make fmt
    • make lint
    • make type
    • make test
  • If docs changed:
    • make docs-check
    • make docs
  • If the example changed:
    • make run-example
  • Pre-merge baseline:
    • make ci
  • Pre-publish baseline:
    • make release-check

Public Vs Private Boundaries

  • The supported public surface is whatever is re-exported from src/python_template/__init__.py.
  • Prefer adding new public behavior to stable top-level modules before creating deeper internal package trees.
  • If you add internal helper modules later, prefix them with _ and keep them out of the top-level exports unless there is a deliberate API decision.

Behavioral Guardrails

  • Keep tests deterministic and offline by default.
  • Update tests, docs, and examples alongside behavior changes.
  • Avoid broad dependency growth in the base install.
  • Keep this template easy to fork: simple defaults beat clever abstractions.

Keep This File Up To Date

Update this file whenever the contributor workflow changes, especially when setup commands, validation commands, or the public API expectations change.