Modernize Python template and agent guidance

.gitignore

@@ -12,7 +12,11 @@ __pypackages__/
 *.swp
 .DS_Store
 .qtmlib/
-*.venv/
+.venv/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.ty/
 
 # autogenerated by sphinx-napoleon
 docs/source/modules.rst

.python-version

@@ -0,0 +1 @@
+3.14

AGENTS.md

@@ -0,0 +1,47 @@
+# Agent Instructions
+
+This repository is a modern Python template. When making changes, prefer the repository's modern Python workflow over legacy Python tooling.
+
+## Preferred Workflow
+
+- Use `uv` for dependency management and environment execution.
+- Use `ruff` for linting and formatting.
+- Use `ty` for type checking.
+- Use `pytest` for testing.
+- Use `pip-audit` for dependency vulnerability checks.
+- Use `prek` for repository hooks and pre-commit-style checks.
+
+## Dependency Management Rules
+
+- Add and remove Python dependencies with `uv add` and `uv remove`.
+- Do not use `pip install`, `uv pip install`, `requirements.txt`, Poetry, Pipenv, or manual virtualenv activation for normal project work.
+- Keep development-only tools in `[dependency-groups]` in `pyproject.toml`, not in `[project.optional-dependencies]`.
+- Commit `uv.lock` when dependency changes are made.
+
+## Project Layout
+
+- Source code lives in `src/`.
+- Tests live in `tests/`.
+- Tool configuration should stay centralized in `pyproject.toml` when practical.
+
+## Build and Run Commands
+
+- Sync dependencies: `uv sync --all-groups`
+- Run the package: `uv run pytemplate`
+- Format code: `uv run ruff format .`
+- Lint code: `uv run ruff check .`
+- Type check: `uv run ty check src tests`
+- Test: `uv run pytest`
+- Audit dependencies: `uv run pip-audit`
+
+## Editing Guidance
+
+- Prefer `uv_build` as the build backend for this template.
+- Prefer `src/` layout for packages.
+- Avoid introducing legacy tool configuration such as `setup.py`, `setup.cfg`, `.flake8`, `mypy.ini`, or a standalone `ruff.toml` unless there is a strong repo-specific reason.
+- If adding documentation or examples, keep them aligned with the commands above.
+
+## If Your Environment Supports Skills
+
+- If an agent/runtime supports reusable skills or slash-commands, prefer the `modern-python` skill for changes in this repository.
+- If that skill is unavailable, follow the instructions in this file as the fallback source of truth.

Dockerfile

@@ -7,8 +7,8 @@ WORKDIR /pytemplate
 # Copy pyproject.toml and other files to the container
 COPY . .
 
-# Install the dependencies
-RUN uv sync --frozen
+# Install runtime dependencies only
+RUN uv sync --frozen --no-default-groups
 
 # Run the command
-CMD ["uv", "run", "pytemplate/main.py"]
+CMD ["uv", "run", "pytemplate"]

Makefile

@@ -1,24 +1,29 @@
-.PHONY: install dev tests lint docs clean build
-
-install:
-	uv pip install .
+.PHONY: dev format lint test audit docs clean build
 
 dev:
-	uv pip install -e .
+	uv sync --all-groups
 
-tests:
-	uv run pytest .
+format:
+	uv run ruff format .
 
 lint:
+	uv run ruff format --check .
+	uv run ruff check .
+	uv run ty check src tests
 	uv run prek run --all-files
-	uvx ty check
+
+test:
+	uv run pytest
+
+audit:
+	uv run pip-audit
 
 docs:
-	uv run sphinx-apidoc -f -o docs/source/ pytemplate
+	uv run sphinx-apidoc -f -o docs/source/ src/pytemplate
 	uv run sphinx-build -M html docs/source/ docs/build/
 
 clean:
-	rm -rf *.egg-info dist build docs/build
+	rm -rf *.egg-info .coverage .pytest_cache .ruff_cache .ty dist build docs/build
 
 build: clean
 	uv build

README.md

@@ -1,6 +1,6 @@
 # pytemplate
 
-This is a Python 3.14 app called pytemplate. The project includes Docker, ty, uv, ruff, typos, GitHub Actions, prek, and Sphinx.
+This is a Python 3.14 package template called `pytemplate`. The project uses `uv` for dependency management, `ruff` for linting and formatting, `ty` for type checking, `pytest` with coverage for tests, `prek` for repository checks, and Sphinx for docs.
 
 The extremely fast Python package and project manager, [uv](https://docs.astral.sh/uv/#getting-started), is required.
 
@@ -10,36 +10,55 @@ The extremely fast Python package and project manager, [uv](https://docs.astral.
 
 ## Project Structure
 
-The source code is located in the `pytemplate` folder, which contains the `__init__.py`, `main.py`, and `utils.py` files. The tests are located in the `tests` folder, which contains the `test_main.py` and `test_utils.py` files.
+The source code lives in `src/pytemplate`, and the tests live in `tests`.
 
-The project uses toml for configuration instead of `setup.py`. The configuration file is located in `pyproject.toml`.
+Project configuration is centralized in `pyproject.toml`.
 
-The project includes Docker, with a `Dockerfile` located in the root directory. The `.dockerignore` file is also located in the root directory.
+The project includes Docker with a `Dockerfile` in the repository root.
 
-The project includes `ty` for static type checking (use `make lint`), `typos` for code spell check, `ruff` for linting & code formatting, and `prek` for enforcing these checks before git commits and on the CI. The configuration for these tools is located in the `ruff.toml` and `.pre-commit-config.yaml` files.
+The project includes `ty` for static type checking, `typos` for spell checking, `ruff` for linting and formatting, and `prek` for repository checks before commits and in CI. Tool configuration lives in `pyproject.toml` and `.pre-commit-config.yaml`.
 
-The project includes Sphinx for documentation, with the documentation located in the `docs` folder. The `source/conf.py` file contains the configuration for Sphinx.
+The project includes Sphinx documentation in `docs`.
 
-The project includes GitHub Actions for continuous integration, with the configuration located in the `.github/workflows/python-app.yml` file.
+The project includes GitHub Actions CI in `.github/workflows/python-app.yml`.
 
 </details>
 
-## Usage Notes
+## Template Setup
 
-- [Replace](https://github.com/your-tools/ruplacer) all mentions of "pytemplate" to your own project's name.
-- Edit `.github/workflows/python-app.yml` to configure which triggers and jobs to enable/disable.
+- Replace all mentions of `pytemplate` with your package name.
+- Rename `src/pytemplate` to your package name and update imports in `tests/`.
+- Update package metadata in `pyproject.toml`, including name, description, authors, and repository URL.
+- Update the console script name in `pyproject.toml` if you do not want to keep `pytemplate`.
+- Update Sphinx metadata in `docs/source/conf.py`, then run `make docs`.
+- Review `.github/workflows/python-app.yml` and align it with your intended CI triggers and install commands.
+- Agentic coding tools should follow the repository guidance in `AGENTS.md`.
 
 ## Installation
 
-To install the project, clone the repository and run:
+Install dependencies and tooling with:
 
 ```sh
-uv sync
+uv sync --all-groups
 uv run prek install
 ```
 
-See `Makefile` for other useful commands.
+The package also exposes a console entry point:
+
+```sh
+uv run pytemplate
+```
+
+See `Makefile` for the common workflows.
 
 ## Testing
 
-Issue `make tests` or `uv run pytest` from the root directory.
+Use `make test` or `uv run pytest`.
+
+## Linting and Type Checking
+
+Use `make lint` to run `ruff`, `ty`, and `prek`.
+
+## Dependency Audit
+
+Use `make audit` or `uv run pip-audit` to scan the environment for known vulnerable packages.

docs/source/conf.py

@@ -8,7 +8,7 @@
 import pathlib
 import sys
 
-sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+sys.path.insert(0, pathlib.Path(__file__).parents[2].joinpath("src").resolve().as_posix())
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

pyproject.toml

@@ -1,30 +1,80 @@
 [build-system]
-requires = ["setuptools", "wheel"]
-build-backend = "setuptools.build_meta"
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
 
 [project]
 name = "pytemplate"
 version = "0.0.1"
 description = "A python library"
+dependencies = []
 readme = "README.md"
 requires-python = ">=3.14"
 authors = [{ name = "Author", email = "author@email.com" }]
 
+[project.scripts]
+pytemplate = "pytemplate.main:main"
+
 [dependency-groups]
+audit = [
+    "pip-audit>=2.10.0",
+]
 dev = [
-  "prek~=0.3.1",
-  "pytest~=9.0.2",
-  "sphinx~=9.1.0",
+  { include-group = "audit" },
+  { include-group = "docs" },
+  { include-group = "lint" },
+  { include-group = "test" },
 ]
+docs = ["sphinx~=9.1.0"]
+lint = ["prek~=0.3.1", "ruff~=0.12.12", "ty~=0.0.1a18"]
+test = ["pytest~=9.0.2", "pytest-cov~=7.0.0"]
 
-[tool.setuptools.packages.find]
-where = ["."]
+[tool.uv]
+default-groups = ["dev"]
 
 [project.urls]
 Repository = "https://github.com/CQCL/pytemplate.git"
 
 [tool.pytest.ini_options]
-pythonpath = ["."]
+addopts = [
+  "--cov=pytemplate",
+  "--cov-report=term-missing",
+  "--cov-fail-under=80",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812", "ISC001"]
+
+[tool.ruff.lint.per-file-ignores]
+"docs/*" = ["D100", "INP001"]
+"tests/*" = ["ANN", "INP001", "PLR2004", "S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.coverage.run]
+branch = true
+source = ["src/pytemplate"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "if __name__ == .__main__.:",
+]
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.ty.environment]
+python-version = "3.14"
 
-[tool.refurb]
-python_version = "3.14"
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+unused-ignore-comment = "warn"

src/pytemplate/main.py

@@ -0,0 +1,15 @@
+"""Entrypoint helpers for the pytemplate package."""
+
+
+def hello_world() -> str:
+    """Return a greeting string for the template package."""
+    return "Hello, World!"
+
+
+def main() -> None:
+    """Run the package's console entry point."""
+    print(hello_world())  # noqa: T201
+
+
+if __name__ == "__main__":
+    main()

pytemplate/utils.py → src/pytemplate/utils.py

@@ -2,5 +2,5 @@
 
 
 def add_numbers(a: int, b: int) -> int:
-    """Add two numbers and returns the result."""
+    """Add two numbers and return the result."""
     return a + b