From 3bfeecbfb1c6b450767fd6358479bb5cb2340dcc Mon Sep 17 00:00:00 2001 From: Philipp Acsany Date: Mon, 14 Sep 2026 18:28:00 +0000 Subject: [PATCH] Add sample code for the agentic coding project setup tutorial Finished project from "How to Set Up a Python Project for Agentic Coding": a uv package layout wired up with Ruff, mypy in strict mode, pytest with a 90% coverage gate, and pre-commit hooks. Verified with uv 0.11.26: pytest passes at 100% coverage, mypy --strict is clean, ruff check and format are clean, and all three pre-commit hooks pass on a first commit. Co-Authored-By: Claude Opus 5 --- .../.env.example | 3 ++ python-project-for-agentic-coding/.gitignore | 16 +++++++ .../.pre-commit-config.yaml | 10 +++++ python-project-for-agentic-coding/AGENTS.md | 18 ++++++++ python-project-for-agentic-coding/README.md | 45 +++++++++++++++++++ .../pyproject.toml | 30 +++++++++++++ .../src/ai_agent_project/__init__.py | 2 + .../tests/test_main.py | 5 +++ 8 files changed, 129 insertions(+) create mode 100644 python-project-for-agentic-coding/.env.example create mode 100644 python-project-for-agentic-coding/.gitignore create mode 100644 python-project-for-agentic-coding/.pre-commit-config.yaml create mode 100644 python-project-for-agentic-coding/AGENTS.md create mode 100644 python-project-for-agentic-coding/README.md create mode 100644 python-project-for-agentic-coding/pyproject.toml create mode 100644 python-project-for-agentic-coding/src/ai_agent_project/__init__.py create mode 100644 python-project-for-agentic-coding/tests/test_main.py diff --git a/python-project-for-agentic-coding/.env.example b/python-project-for-agentic-coding/.env.example new file mode 100644 index 0000000000..011e388109 --- /dev/null +++ b/python-project-for-agentic-coding/.env.example @@ -0,0 +1,3 @@ +# Copy this file to .env and fill in the values your project needs. +# .env is git-ignored, so real secrets never reach the repository. +API_KEY=your-api-key-here diff --git a/python-project-for-agentic-coding/.gitignore b/python-project-for-agentic-coding/.gitignore new file mode 100644 index 0000000000..29d2eeae67 --- /dev/null +++ b/python-project-for-agentic-coding/.gitignore @@ -0,0 +1,16 @@ +# Python-generated files +__pycache__/ +*.py[oc] +build/ +dist/ +wheels/ +*.egg-info + +# Virtual environments +.venv + +# Environment variables +.env + +# Coverage +.coverage diff --git a/python-project-for-agentic-coding/.pre-commit-config.yaml b/python-project-for-agentic-coding/.pre-commit-config.yaml new file mode 100644 index 0000000000..ae391d2e41 --- /dev/null +++ b/python-project-for-agentic-coding/.pre-commit-config.yaml @@ -0,0 +1,10 @@ +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.15.21 + hooks: + - id: ruff-check + - id: ruff-format + - repo: https://github.com/pre-commit/mirrors-mypy + rev: 'v2.3.0' + hooks: + - id: mypy diff --git a/python-project-for-agentic-coding/AGENTS.md b/python-project-for-agentic-coding/AGENTS.md new file mode 100644 index 0000000000..e432352c5d --- /dev/null +++ b/python-project-for-agentic-coding/AGENTS.md @@ -0,0 +1,18 @@ +# `AGENTS.md` + +## Development workflow + +- This project is typed. Run mypy after adding or modifying code: + - `uv run mypy .` +- Use Ruff for formatting and linting: + - `uv run ruff format .` + - `uv run ruff check .` +- Run the full test suite after modifying code: + - `uv run pytest` +- Add or update tests when changing behavior. +- Before committing, run: + - `uv run pre-commit run --all-files` +- Prefer small, focused functions. + +## Documentation +- Update documentation when public behavior changes. diff --git a/python-project-for-agentic-coding/README.md b/python-project-for-agentic-coding/README.md new file mode 100644 index 0000000000..f96dd2f4a0 --- /dev/null +++ b/python-project-for-agentic-coding/README.md @@ -0,0 +1,45 @@ +# How to Set Up a Python Project for Agentic Coding + +This folder contains the sample code for the Real Python tutorial +[How to Set Up a Python Project for Agentic Coding](https://realpython.com/python-project-for-agentic-coding/). + +It is the finished project from the tutorial: a small Python package wired up +with the automated feedback an AI coding agent needs, namely Ruff for linting +and formatting, mypy in strict mode for type checking, pytest with a coverage +gate for behavior, and pre-commit to run those checks before every commit. + +## Setup + +Install [uv](https://docs.astral.sh/uv/#installation), then install the +dependencies and the pre-commit hooks: + +```console +$ uv sync +$ uv run pre-commit install +``` + +## Running the checks + +Each tool can be run on its own: + +```console +$ uv run ruff check . +$ uv run mypy . +$ uv run pytest +``` + +Or run everything the way the agent is told to in `AGENTS.md`: + +```console +$ uv run pre-commit run --all-files +``` + +## What each file is for + +| File | Purpose | +| --- | --- | +| `pyproject.toml` | Dependencies plus the Ruff, mypy, and pytest configuration | +| `AGENTS.md` | Workflow conventions an agent should follow | +| `.pre-commit-config.yaml` | Checks that run before each commit | +| `tests/` | Executable specification of the expected behavior | +| `.env.example` | Documents required environment variables without exposing secrets | diff --git a/python-project-for-agentic-coding/pyproject.toml b/python-project-for-agentic-coding/pyproject.toml new file mode 100644 index 0000000000..ab591e1c16 --- /dev/null +++ b/python-project-for-agentic-coding/pyproject.toml @@ -0,0 +1,30 @@ +[project] +name = "ai-agent-project" +version = "0.1.0" +description = "Add your description here" +readme = "README.md" +requires-python = ">=3.14" +dependencies = [] + +[build-system] +requires = ["uv_build>=0.11.26,<0.12.0"] +build-backend = "uv_build" + +[dependency-groups] +dev = [ + "mypy>=2.3.1", + "pre-commit>=4.6.2", + "pytest>=9.1.1", + "pytest-cov>=7.1.0", + "ruff>=0.16.7", +] + +[tool.ruff] +line-length = 80 + +[tool.mypy] +strict = true + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "--cov=src --cov-report=term-missing --cov-fail-under=90" diff --git a/python-project-for-agentic-coding/src/ai_agent_project/__init__.py b/python-project-for-agentic-coding/src/ai_agent_project/__init__.py new file mode 100644 index 0000000000..8f777bc6a1 --- /dev/null +++ b/python-project-for-agentic-coding/src/ai_agent_project/__init__.py @@ -0,0 +1,2 @@ +def double(value: int) -> int: + return value * 2 diff --git a/python-project-for-agentic-coding/tests/test_main.py b/python-project-for-agentic-coding/tests/test_main.py new file mode 100644 index 0000000000..ba26d5dcf5 --- /dev/null +++ b/python-project-for-agentic-coding/tests/test_main.py @@ -0,0 +1,5 @@ +from ai_agent_project import double + + +def test_double_returns_twice_the_input() -> None: + assert double(4) == 8