Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (76 loc) · 4.34 KB

AGENTS.md

File metadata and controls

92 lines (76 loc) · 4.34 KB

Agent Guide for scientific-python/cookie

This repo has three distinct concerns: a cookiecutter/copier template for new Python projects ({{cookiecutter.project_name}}/), a repo-review plugin (src/sp_repo_review/), and a MyST/MystMD-based developer guide (docs/).

Key commands

sp-repo-review (the package)

  • Run tests: uv run pytest (or uvx nox -s rr_tests)
  • Run linting (pre-commit via prek): uvx nox -s rr_lint
  • Run pylint: uvx nox -s rr_pylint
  • Run the CLI: uvx nox -s rr_run -- <path>
  • Regenerate README check list via cog: uvx nox -s readme
  • Build wheel/sdist: uvx nox -s rr_build

Important: tests run with PYTHONWARNDEFAULTENCODING=1.

Cookie template validation

The noxfile generates temporary projects for all 9 backends × vcs on/off × 3 docs engines (sphinx/mkdocs/zensical). These are slow.

  • nox -s "tests(hatch)" — run generated project tests for a single backend
  • nox -s "lint(hatch)" — run pre-commit (prek) on generated project
  • nox -s "dist(hatch)" — verify build output includes LICENSE
  • nox -s "native(hatch)" — test hatch/pdm/poetry native test runners
  • nox -s compare_copier — verify cookiecutter and copier produce identical files
  • nox -s compare_cruft — verify cookiecutter and cruft produce identical files
  • nox -s gha_bump — bump GitHub Actions versions across docs and templates
  • nox -s pc_bump — bump pre-commit hook versions across docs and templates

Architecture notes

  • Template directory: {{cookiecutter.project_name}}/ contains the cookiecuttter template. Copier reads copier.yml; cookiecutter reads cookiecutter.json. Keep them in sync; compare_copier checks this.
  • Entry points: sp_repo_review registers repo-review checks/families/fixtures via [project.entry-points] in pyproject.toml.
  • Generated docs: The README check list (line ~300+) is a cog block. Do not edit it by hand; run nox -s readme or cog will fail in CI.
  • Cookie template .pre-commit-config.yaml uses prek (a Rust-based pre-commit alternative), not pre-commit.
  • Ruff hook ID: .pre-commit-config.yaml uses ruff-check as the hook id (not ruff), for pre-commit 4.x compatibility.

Style and conventions

  • tool.pytest.ini_options.norecursedirs excludes {{cookiecutter.project_name}} so pytest does not descend into the template directory.
  • tool.ruff.extend-exclude also excludes \{\{cookiecutter.project_name\}\} (double-escaped in TOML).
  • tool.mypy.python_version = "3.10"; the sp_repo_review.* override enforces disallow_untyped_defs=True.
  • tool.pylint.master.ignore-paths ignores src/sp_repo_review/_version.py (auto-generated by hatch-vcs).
  • Ruff selects ALL with many ignores; notable: S101 (assert) and D (docstrings) are globally disabled.

CI quirks

  • CI uses change detection to decide whether to run cookie tests or rr-tests. Both are required to pass for the pass job.
  • rr-tests matrix runs on Python 3.10, 3.12, 3.14 across ubuntu/macos/windows.
  • Cookie tests reuse the same reusable-cookie.yml workflow.

Docs site (MyST)

  • Migrated from Jekyll to MyST (JupyterBook 2.0) using the scientific-python-myst-theme.
  • Node/Bun-based; from the repo root, run bun install then bun run build to build the site.
  • Config: docs/myst.yml (TOC, project settings), docs/config/scientific-python.yml (theme options).
  • Custom plugin: docs/rr-role.mjs — provides {rr} inline role for repo-review badge spans.
  • Custom CSS: docs/assets/css/site.css — only .rr-btn badge styling remains.
  • Docs pages in docs/pages/ contain cog blocks that auto-generate config examples from the template.
  • The repo-review interactive page is embedded using an {anywidget} directive (see docs/pages/guides/repo_review.md).
  • Tab-sets use :sync: <tab-name> for cross-page tab synchronization, where the sync key is the tab label itself (e.g., sphinx, mkdocs, trusted-publishing, scikit-build-core).
  • TOML code blocks in the docs use "ini" to get syntax highlighting for now. This is applied only at the docs layer (the code_fence cog helper in helpers/cog_helpers.py rewrites toml→ini); do not change the toml fences in the src/sp_repo_review/checks/*.py docstrings, which are rendered by repo-review itself, not this site.