Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
80 lines
2.3 KiB
Markdown
80 lines
2.3 KiB
Markdown
---
|
|
type: reference
|
|
title: Python
|
|
description: Current best practices for Python projects - uv, pyproject.toml, frameworks, linting, and testing.
|
|
tags:
|
|
- python
|
|
- uv
|
|
- fastapi
|
|
- django
|
|
- bootstrap
|
|
- engineering
|
|
timestamp: 2026-08-11
|
|
verified: 2026-08-28
|
|
---
|
|
|
|
CUT
|
|
# Python
|
|
|
|
This page covers current (2025/2026) best practices for Python projects.
|
|
|
|
## Package and Project Management
|
|
|
|
Use `uv` for new projects. `uv` replaces pip, pip-tools, pyenv, poetry, and virtualenv. It is much faster than pip and supports workspaces and lockfiles.
|
|
|
|
Scaffold a project with:
|
|
|
|
```bash
|
|
uv init my-project --bare
|
|
```
|
|
|
|
The command creates a `pyproject.toml` and a virtual environment. A `uv.lock` file pins exact dependency versions. Do not edit the lockfile by hand.
|
|
|
|
Use `pyproject.toml` as the project manifest. It follows PEP 621. This replaces the older `setup.py`.
|
|
|
|
## Tooling
|
|
|
|
| Category | Tool | Notes |
|
|
|----------|------|-------|
|
|
| Linter and formatter | Ruff | Replaces Black, isort, flake8, and pylint. |
|
|
| Type checker | pyright or mypy | Use pyright in VS Code. Use mypy for strict CI. |
|
|
| Testing | pytest | Use pytest-asyncio for async tests. |
|
|
| Pre-commit | pre-commit | Run ruff, mypy, and pytest. |
|
|
|
|
## Framework Comparison
|
|
|
|
| Framework | Best For | Notes |
|
|
|-----------|----------|-------|
|
|
| FastAPI | Modern REST APIs, async | Auto documentation, type-hint validation. |
|
|
| Django | Full-stack web apps | Batteries included: ORM, admin, auth. |
|
|
| Flask | Lightweight apps | Simpler than FastAPI. |
|
|
|
|
Use FastAPI for new REST APIs. The recommended workflow is `uv run fastapi dev`.
|
|
|
|
## Notable 2025/2026 Changes
|
|
|
|
* `uv` is the dominant project manager.
|
|
* `ruff` replaced most separate lint and format tools.
|
|
* `pyproject.toml` is the universal manifest.
|
|
* Python 3.12 gives stability. Python 3.13 adds performance improvements.
|
|
|
|
## Related Technologies
|
|
|
|
* Uvicorn as the ASGI server.
|
|
* SQLAlchemy 2.0 with Alembic for the ORM and migrations.
|
|
* httpx for async HTTP clients.
|
|
* pydantic-settings for configuration.
|
|
* OpenTelemetry for observability.
|
|
|
|
## Citations
|
|
|
|
* [uv documentation](https://docs.astral.sh/uv/)
|
|
* [Ruff](https://ruff.rs/)
|
|
* [FastAPI](https://fastapi.tiangolo.com/)
|
|
* [pyproject-build](https://pyproject-build.github.io/)
|
|
|
|
## See Also
|
|
|
|
* [SDLC and Tooling](../sdlc.md)
|
|
* [Infrastructure and Cloud](../infra/index.md)
|