Skip to content

AGENTS.md

Latest commit

 

History

History
200 lines (132 loc) · 4.28 KB

AGENTS.md

File metadata and controls

200 lines (132 loc) · 4.28 KB
Raw

Pluggable Cache Architecture for Python

The project implements a pluggable caching architecture for Python programs.

Follow these instructions strictly.

Style and Conventions

  • PEP 8.
  • Maximum line length is 79 characters.

You must:

  • Use type annotations.
  • Use str | None and built-in generics such as list[T].
  • Prefix module-local objects with _, except logger.
  • Add all imports at the top of modules, unless requested for lazy loading.
  • Use pathlib.Path internally; public APIs should accept str | Path and convert accordingly.

You must not:

  • Add imports inside functions or methods, or between non import statements.
  • Make unrelated refactors or move logic across layers unnecessarily.
  • Add # noqa, fix the underlying issue instead. Exceptions:
    • PLC0415 when lazy loading of modules is required.
    • E501 on long multi-line strings.
    • V107 on Protocol subclass method arguments.
  • Add # type: ignore or use cast() under src/; stop and ask for guidance if unavoidable.
  • Leave internal passthrough functions behind after refactors.

Documentation Rules

Public APIs must include PEP 257 docstrings following Google standard.

Docstrings should describe behavior, not implementation details.

Adapter Implementation Spec

The file ADAPTER_SPEC.md contains the specification for external adapter developers to create adapters for cache backends that can be used with this API.

  • The document must have everything an external developer needs to develop a backend adapter without looking at this project's codebase.
  • Do not add any internal implementation details from this codebase to the developer spec.
  • Always update the spec when adding/updating the codebase and the changes you make are important to adapter developers.

Versioning

This project adheres to Semantic Versioning.

Testing

  • Do not test internal functions/methods; test observable behaviour only.
  • Avoid brittle tests.

Strict Rules

You must:

  • Make minimal, focused edits
  • Avoid large refactors unless explicitly requested
  • Preserve existing API behavior

Changelog

Follow Keep a Changelog (>=1.1.0).

Sections names:

  • Added
  • Changed
  • Deprecated
  • Removed
  • Fixed
  • Security

You must:

  • Keep CHANGELOG.md updated for end user-visible changes.
  • Write entries for humans.
  • Group by change type.
  • Wrap lines at 80 columns.
  • Update the changelog in the same change as version bumps.
  • Be concise, do not just replicate details already in the README.md file.

You must not:

  • Change past entries under released versions.
  • Document internal development or non end-user visible changes.

Git

Only read-only Git commands are allowed.

Do not:

  • Rewrite history.
  • Force push.
  • Use destructive Git commands.
  • Commit unless explicitly requested, even if committed before.

Change Workflow

You must follow this workflow, no exceptions:

  1. Inspect existing patterns and conventions.
  2. Implement changes.
  3. Auto-fix and format changed Python files.
  4. Run global code QA.
  5. Run relevant targeted tests.
  6. Run full test suite with coverage
    • add tests if coverage is below threshold and repeat.

Important:

  • Fix all QA and test issues before proceeding to the next step.
  • Do not run QA/tests on non code changes.
  • Do not skip steps.
  • Do not change order.

Completion Criteria

  • All non-private APIs have Google Style docstrings.
  • QA passes.
  • Full test suite passes.
  • Test coverage meets project's threshold.
  • Changelog updated with user-visible changes.
  • Documentation and docstrings updated.

Commands

Auto-fix and format:

ruff check --fix
ruff format

QA checks:

ruff check
vulture
mypy

Targeted file test:

python -m unittest  --failfast --buffer --quiet tests.test_cache

Targeted class test:

python -m unittest  --failfast --buffer --quiet tests.test_cache.TestCache

Single function test:

python -m unittest  --failfast --buffer --quiet tests.test_cache.TestCache.test_add_get

Full test suite with coverage:

coverage run -m unittest --failfast --buffer --quiet

Get coverage percentage:

coverage report --format=total

Show missing coverage report:

coverage report --skip-covered --show-missing