template instructions added

[AlexAndrewsAI]

Small change adding additional instructions to README.md

[AlexAndrewsAI]

Code Review: python-package-template

Reviewer Cursor Composer 2.5
Reviewed: 2026-05-24
Scope: Full repository (python_package_template/, tests/, pyproject.toml, docs)
Mode: Analysis only (no source changes)

Executive Summary

This is a small, well-scoped Python package template with clear separation between configuration (config.py), domain logic (hello.py), and CLI (cli.py). The project follows its own stated standards: type hints, Google-style docstrings, logging instead of print() in library code, and a sensible pyproject.toml toolchain (uv, ruff, mypy, pytest).

Automated checks (run during review):

Check	Result
uv run pytest	9 passed
uv run ruff check .	All checks passed
uv run ruff format --check .	6 files formatted
uv run mypy .	Success (6 source files)
uv build	sdist + wheel built successfully

Overall: Suitable as a starter template. Findings below are mostly maintainability, consistency, and “next step” improvements rather than blocking defects.

---

Strengths

1. Clean layering — Config → HelloWorld → CLI is easy to extend without cross-cutting concerns.
2. Pydantic usage — Frozen Config with Field defaults is a good pattern for immutable settings.
3. Logging — HelloWorld.greet() logs at INFO with structured %s formatting (ruff G rules friendly).
4. Tooling — Ruff rule set is thorough (security S, bugbear B, docstrings D, pytest style PT, etc.) with sensible test exemptions.
5. Tests — Core library paths and CLI happy paths are covered; log capture tests validate observability, not just return strings.
6. Packaging — Dynamic version via hatch reading __init__.py, console script entry point, and build both work out of the box.
7. Documentation — README and dual AGENTS*.md files match the repo layout and workflows.

---

Findings

Medium — Duplicate --version handling in CLI

cli.py implements version display in two places:

• Global callback: version_callback on @app.callback() (lines 15–19, 24–30).
• hello subcommand: inline if version: block (lines 57–59).

Both print the same string and call typer.Exit(). This works but violates DRY and increases risk of drift (e.g., message format or exit code changes in one place only).

Recommendation: Keep version only on the root callback (Typer’s usual pattern) and remove the version option from hello, or extract a single show_version_and_exit() helper used by both.

---

Medium — Empty name is allowed without validation

test_cli_hello_empty_name documents that --name "" yields Hello, !. Pydantic accepts an empty string because name: str has no min_length or custom validator.

For a greeting template this may be intentional (shows where to add validation), but it is inconsistent with “configuration validation” messaging in the README.

Recommendation: Either add Field(min_length=1) (and a unit test for ValidationError) or document in README that empty names are allowed by design.

---

Medium — No CI workflow in repository

There are no GitHub Actions (or similar) workflows. For a public template, a minimal CI job running uv sync --dev, pytest, ruff check, and mypy would reinforce the README/AGENTS promises and protect forks.

Recommendation: Add a small workflow (matrix optional; single 3.12 job is enough for a template).

---

Low — Test gaps

Gap	Notes
hello -V on subcommand	Works at runtime (hello-world hello -V); only --version long form is tested in test_cli_hello_version.
Config validation	No tests for frozen immutability, invalid types, or optional future fields.
Library error paths	No negative tests (e.g., passing invalid config types if API expands).
Coverage tooling	README claims “comprehensive” coverage; no pytest-cov or coverage threshold in pyproject.toml.

These are acceptable for a minimal template but worth calling out for consumers who copy the repo verbatim.

---

Low — README vs AGENTS CLI invocation

• README: uv run hello-world hello
• AGENTS.md: uv run python -m python_package_template.cli hello

Both work; aligning on one canonical invocation reduces confusion for new contributors.

---

Low — No python -m python_package_template entry

There is no __main__.py. Module execution goes through python_package_template.cli. Adding __main__.py that delegates to app() would match common package conventions (python -m python_package_template).

---

Low — pyproject.toml license metadata

license = {text = "MIT"} is valid but older style. PEP 621 now prefers license = "MIT" (SPDX) where tooling supports it. Cosmetic for a template.

---

Nit — main() callback body is pass

The Typer callback exists only to attach --version. An ellipsis (...) or a one-line comment is slightly clearer than pass, but ruff/mypy are fine with current code.

---

Nit — REVIEW.md is gitignored

.gitignore lists REVIEW.md first. Agent instructions direct reviews into this file, so findings stay local unless force-added. Fine for ephemeral agent output; document if you want reviews committed in forks.

---

Security & Reliability

• Input surface: CLI name is a short string passed to an f-string greeting. No injection risk beyond odd output for empty or unusual names.
• Dependencies: Pinned ranges in pyproject.toml with lockfile (uv.lock). Template consumers should keep uv lock / dependabot habits.
• Ruff S rules: Enabled globally; tests correctly allow S101 (assert).

No issues requiring immediate action for this codebase size.

---

Alignment with AGENTS.md

Directive	Status
Type hints on all signatures	Met
Google docstrings on public APIs	Met
logging not print() in library code	Met (typer.echo in CLI is appropriate)
Tests for behavior changes	Met for current features
Relative paths in code	Met (no hardcoded absolute paths)
uv sync --dev before work	Verified during review

---

Suggested Priority Order (if improving the template)

1. Deduplicate CLI version handling.
2. Decide on name validation (constraint + test, or explicit docs).
3. Add minimal CI workflow.
4. Add test_cli_hello_version_short for hello -V (one line).
5. Optional: __main__.py, SPDX license field, pytest-cov in dev group.

---

Files Reviewed

• python_package_template/__init__.py
• python_package_template/config.py
• python_package_template/hello.py
• python_package_template/cli.py
• tests/test_hello.py
• tests/__init__.py
• pyproject.toml
• README.md
• AGENTS.md / AGENTS_MANUAL_CHECKS.md
• .gitignore