git:20260914.d23bb45 to git:20260916.50d6810

16 added, 45 removed. Audit A to A.

---

name: python-stack

- description: Define shared Python project defaults and scaffold a minimal typed package. Use when choosing or aligning a Python stack, layout, or quality baseline.

+ description: "Develop Python with uv, Ruff, ty, Pydantic, async, and LangExtract; fix packaging, lint, imports, and type errors."

license: MIT

metadata:

+ kind: collection

author: Médéric HURIER (Fmind)

source: github.com/fmind/dot/tree/main/skills/python-stack

created: "2026-06-23"

- updated: "2026-09-14"

+ updated: "2026-09-16"

---

- # Python Stack Standard

- Own the shared Python foundation and select the specialist for the task. Preserve existing project conventions. Load only the relevant owner; specialist skills can use these defaults without restarting the bootstrap workflow.

- ## Defaults

- - **Toolchain**: mise owns the interpreter under the [shared tool baseline](../mise/references/tool-versions.md); uv owns package environments and `uv.lock`. Python follows the same `latest` baseline and exact project pins as other tools. Align `.python-version` with the selected pin within `requires-python`; check a library's minimum interpreter with `uv run --isolated --python <min> pytest` (`--isolated` leaves the project `.venv` untouched).

- - **Foundation**: a `src/<package>/` layout and no runtime dependencies until the application uses them. Distribution slugs may contain hyphens; import names use underscores.

- - **Quality**: Ruff for Python formatting/lint, ty for types, pytest for behavior, and dprint for markup/config. Keep checks warning-free; use deterministic offline tests and an initial 85% branch-coverage target adapted to the project.

- - **Boundaries**: use Pydantic/settings when external input or application configuration needs typed validation, and structlog when structured logging is required. Respect ecosystem-native formats; otherwise use YAML for human-maintained configuration and JSON for program-owned data, with explicit defaults and override precedence.

+ # Python Stack

- For application templates, set output-appropriate escaping explicitly and prefer `StrictUndefined` in new Jinja templates when missing data is an error; review compatibility before changing existing undefined behavior. Template generation and tracked updates use [cookiecutter](../cookiecutter/SKILL.md).

+ Maintain a small typed Python foundation and choose libraries for demonstrated requirements. Preserve the existing environment and conventions rather than restarting a scaffold for every feature.

## Workflow

- 1. **Choose the owner** from [profiles](references/profiles.md) and the table below. For an existing application's feature or diagnostic, go directly to its specialist.

- 1. **Create the foundation only when needed** using [bootstrap](references/bootstrap.md), the shared manifest and tasks below, and the minimal library example. Add the selected specialist's scaffold before final qualification; generated agent and Django projects retain their native layouts.

- 1. **Verify the result** through focused behavior tests and the project's canonical gate. Build a new package, install its wheel in a fresh environment, and exercise its public import or command outside the source tree; an editable install alone does not qualify packaging.

- 1. **Finish** through [repository-docs](../repository-docs/SKILL.md). [new-project](../new-project/SKILL.md) owns repository-wide setup, CI, licensing, and authorized publication.

- ## Task owners

- | Need | Owner |

- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

- | Dependencies, environments, Python versions, builds | [uv](../uv/SKILL.md) |

- | Python lint/format or type diagnostics | [ruff](../ruff/SKILL.md), [ty](../ty/SKILL.md) |

- | Task definitions, hooks, markup/config formatting | [mise](../mise/SKILL.md), [lefthook](../lefthook/SKILL.md), [dprint](../dprint/SKILL.md) |

- | CLI scaffold and command behavior | [typer](../typer/SKILL.md), [cli-contracts](../cli-contracts/SKILL.md) |

- | Web application | [django](../django/SKILL.md) for ORM, admin, auth, and server-rendered pages; [litestar](../litestar/SKILL.md) for typed ASGI APIs and services; [fastapi](../fastapi/SKILL.md) for an existing or generated scaffold |

- | Async tasks, cancellation, deadlines, shutdown | [python-async](../python-async/SKILL.md) |

- | Persisted schema or data changes | [data-migration](../data-migration/SKILL.md), including Alembic; use installed database/framework documentation for query APIs. |

- | Agent, LLM, and MCP application code | [agents-cli](../agents-cli/SKILL.md) and [google-adk](../google-adk/SKILL.md) for Google agents; [langchain](../langchain/SKILL.md) or [langgraph](../langgraph/SKILL.md) for framework code; [mcp-server](../mcp-server/SKILL.md) for tool servers |

- | Single-file utility or reactive notebook | [python-script](../python-script/SKILL.md), [marimo](../marimo/SKILL.md) |

- | Local data queries and exports | [duckdb](../duckdb/SKILL.md); use the project's dataframe and plotting libraries through their installed source and official docs. |

- | Input validation, logging, external HTTP | [pydantic](../pydantic/SKILL.md), [observability](../observability/SKILL.md), [api-client](../api-client/SKILL.md) |

- | Python tests and Hypothesis integration | [test-driven-development](../test-driven-development/SKILL.md), including pytest mechanics and property-testing references. |

- | Broader test campaigns | [quality-assurance](../quality-assurance/SKILL.md) |

- | CPU and allocation profiling | [systematic-debugging](../systematic-debugging/SKILL.md), including its Python profiler recipes. |

- | Security scans and dependency upgrades | [secure](../secure/SKILL.md), [upgrade-tools](../upgrade-tools/SKILL.md) |

+ Read only the matching guide and its required resources. Use a known guide directly when shared prerequisites are not needed.

- ## Foundation resources

+ ## Task guides

- - [pyproject.toml.template](references/pyproject.toml.template), [mise.toml](references/mise.toml), and [lefthook.yml](references/lefthook.yml) define the shared foundation. Preserve supported package ranges; resolve scaffold tool selectors to exact baseline pins before installation.

- - [AGENTS.md](references/AGENTS.md) and [gitignore](references/gitignore) supply project conventions.

- - [init-library.py](references/init-library.py) and [test_library.py](references/test_library.py) supply the minimal library example; application code and tests live with the selected specialist.

+

- ## Documentation

+ - [foundation](references/foundation/GUIDE.md): Python package layout, dependency choices, defaults, and project scaffolding.

+ - [langextract](references/langextract.md): Extract structured facts from text with LangExtract and source-grounded evidence.

+ - [pydantic](references/pydantic.md): Typed validation, serialization, and settings boundaries.

+ - [python-async](references/python-async/GUIDE.md): Async design, cancellation, timeouts, and shutdown.

+ - [ruff](references/ruff.md): Python linting, formatting, imports, and safe fixes.

+ - [ty](references/ty.md): Type diagnostics and environment resolution.

+ - [uv](references/uv.md): Dependency resolution, environments, packaging, and lockfiles.

- - [Python](https://docs.python.org/3/) · [Python packaging](https://packaging.python.org/)

- - [agent-project](../agent-project/SKILL.md) owns vendor skill discovery and the dated official-source audit; selecting a stack does not install every vendor bundle.

- - Releases: [Python versions](https://devguide.python.org/versions/) · [CPython changelog](https://docs.python.org/3/whatsnew/changelog.html)

+