Version: 1.0.0 Applies to: Python 3.12+
Base standards that apply to all Python project types. Each project type (Web Service, Package, Data Job, Documentation Site) extends these standards with specific tools.
Mandatory Base Stack Runtime Tool Version Description Python 3.12+ Performance improvements, better generic type support, descriptive error messages
Dependency and Environment Management Tool Description Replaces uv All-in-one management: dependencies, virtual environments, Python versions. Written in Rust, 10-100x faster pip, poetry, pipenv, pip-tools, pyenv, venv
Code Quality Tool Description Replaces Ruff Extremely fast linter and formatter (Rust). 800+ rules, auto-fix, unified configuration in pyproject.toml Flake8, Black, isort, autopep8, pylint, pyupgrade Pyright Static type checker (Microsoft). Pylance engine in VS Code, better inference than mypy mypy
Testing Tool Description pytest Testing framework with extensible plugin architecture pytest-cov Coverage integration with pytest pytest-mock unittest.mock wrapper integrated with pytest
Validation and Serialization Tool Description Pydantic v2 Data validation using type hints. Rust core for maximum performance pydantic-settings Typed configuration from environment variables
Task Runner and Automation Tool Description Replaces just Modern command runner, clean syntax, cross-platform Makefile pre-commit Framework for managing Git hooks consistently Scattered bash scripts
Project Structure Layout: src-layout (Mandatory) All projects must use src-layout where source code resides within a src/ directory. This avoids accidental imports of local code during development and is officially recommended by PyPA.
Mandatory Files File Purpose pyproject.tomlCentral configuration (dependencies, tools) uv.lockLock file for exact reproducibility .python-versionProject Python version .pre-commit-config.yamlGit hooks configuration .gitignoreFiles ignored by Git .gitattributesLine ending normalization, LFS, merge strategies src/<package>/py.typedPEP 561 marker for type support JustfileStandardized project commands README.mdBasic project documentation LICENSEProject license
Configuration Files File Purpose .editorconfigFormat consistency (indentation, charset, EOL) across editors .markdownlint.yamlLinting rules for Markdown files .secrets.baselineBaseline of known secrets (detect-secrets) cspell.jsonDictionary and spell checking configuration
File Purpose LICENSEProject license (MIT, Apache 2.0, etc.) CODE_OF_CONDUCT.mdCode of conduct for contributors CONTRIBUTING.mdProject contribution guide CHANGELOG.mdChange history by version (Keep a Changelog + SemVer ) SECURITY.mdSecurity policy and vulnerability reporting process
GitHub Repository Files File Purpose .github/CODEOWNERSDefines code owners by area for automatic review .github/pull_request_template.mdPR template .github/workflows/GitHub Actions workflows .github/dependabot.ymlAutomatic update configuration
Directories Directory Purpose .devcontainer/DevContainers configuration (VS Code) .github/workflows/CI/CD pipelines docs/Project documentation (MkDocs, guides) src/<package_name>/Application source code tests/Automated tests (unit/, integration/, e2e/)
Naming Conventions Element Convention Example Modules/Packages snake_case user_service.py Classes PascalCase UserService Functions/Methods snake_case get_user() Variables snake_case user_count Constants UPPER_SNAKE_CASE MAX_CONNECTIONS Type aliases PascalCase UserId Private _ prefix_internal_cache "Very private" __ prefix__secret_key Environment variables UPPER_SNAKE_CASE DATABASE_URL
Environment Variables Practice Convention Example General format UPPER_SNAKE_CASELOG_LEVEL, DEBUG App prefix APPNAME_*MYAPP_DATABASE_URL Feature flags ENABLE_* or *_ENABLEDENABLE_CACHE, FEATURE_X_ENABLED URLs/Endpoints *_URL or *_ENDPOINTAPI_URL, REDIS_ENDPOINT Secrets *_KEY, *_SECRET, *_TOKENAPI_KEY, JWT_SECRET Timeouts *_TIMEOUT (in seconds)REQUEST_TIMEOUT Ports *_PORTSERVER_PORT
Best practices:
Practice Description Use app prefix in shared environments Avoid collisions: MYAPP_DB_HOST vs DB_HOST Document all variables Keep .env.example updated Use descriptive names DATABASE_CONNECTION_POOL_SIZE over DB_POOL Don't embed environment in name Use API_URL, not PROD_API_URL
Python Code Standards Type Hints (PEP 484, PEP 604) All functions must have type annotations:
Practice Standard Example Native generics Use built-in types list[str] not List[str] Union syntax Use pipe operator str \| None not Optional[str] Return type Always specify def get_user() -> User: Complex types Use TypeAlias UserId: TypeAlias = int
Function Definitions Practice Description Type all parameters Every parameter has a type annotation Type return values Every function has a return type Default values Type before default: name: str = "default" *args / **kwargsType the contents: *args: str, **kwargs: int
Decorators Practice Description Order matters Outermost decorator executes first Preserve metadata Use @functools.wraps in custom decorators Type decorators Use ParamSpec and TypeVar for typed decorators
Module Organization Section Order Description 1. Module docstring Top Module description 2. __future__ imports First imports Future annotations if needed 3. Standard library Second import os, import sys 4. Third-party Third import fastapi, import pydantic 5. Local imports Fourth from .models import User 6. Constants After imports MAX_RETRIES = 3 7. Type aliases After constants UserId: TypeAlias = int 8. Classes/Functions Main content Implementation 9. if __name__ Bottom Entry point guard
Code Patterns Pattern Use Avoid pathlib.PathFile system operations os.path datetime.UTCTimezone-aware datetimes Naive datetimes Context managers Resource management Manual open/close Dataclasses/Pydantic Data structures Plain dicts for structured data Enums Fixed set of values String constants
Typing Patterns Pattern When to Use ProtocolDuck typing, structural subtyping TypedDictDicts with known structure LiteralVariable with specific allowed values FinalConstants that shouldn't be reassigned ClassVarClass-level variables
Dependency Management Version Specification Format Use Example >=X.Y.ZMinimum version (preferred) fastapi>=0.115.0 >=X.Y.Z,<A.0.0Bounded range pydantic>=2.0.0,<3.0.0
Avoid: Exact versions (==), no version, overly restrictive ranges.
Dependency Separation Group Contents Installation dependenciesProduction uv sync devDevelopment and testing uv sync --all-extras docsDocumentation uv sync --extra docs
Linting and Static Analysis Ruff - Enabled Rule Categories Category Code Description Pyflakes F Logic errors, unused variables pycodestyle E, W PEP 8 style isort I Import sorting pep8-naming N Naming conventions pyupgrade UP Syntax modernization flake8-bugbear B Common bugs flake8-simplify SIM Simplifications flake8-bandit S Basic security rules Ruff-specific RUF Ruff-specific rules
Pyright - Strict Mode Type annotations on all public functions No implicit Any usage Type verification in all expressions Testing Strategy Test Structure Directory Contents Characteristics tests/unit/Unit tests Fast, no I/O, no external dependencies tests/integration/Integration tests Can use DBs, mocked APIs tests/e2e/End-to-end tests Test the complete system
Markers Marker Use @pytest.mark.unitUnit tests @pytest.mark.integrationIntegration tests @pytest.mark.slowTests > 1 second
Minimum Coverage Metric Minimum Line coverage 80% Branch coverage 80%
Security Tool Description When Bandit Static security analysis CI/CD, pre-commit pip-audit Dependency vulnerability scanning CI/CD detect-secrets Secret detection with baseline pre-commit gitleaks Secret detection in code CI/CD
Practices Practice Description Don't use eval/exec Never execute dynamic code from external input Parameterized queries Never concatenate strings for SQL Don't use pickle with external data Pickle allows arbitrary code execution Don't hardcode secrets Use environment variables or secret managers
Git and Version Control Conventional Commits Type Use featNew functionality fixBug fix docsDocumentation only styleCode style (formatting, no logic change) refactorRefactoring without functional change perfPerformance improvements testAdd or fix tests buildBuild system or dependencies ciCI/CD configuration choreMaintenance tasks revertRevert a previous commit
Semantic Versioning (SemVer) All projects follow Semantic Versioning : MAJOR.MINOR.PATCH
Component When to Increment MAJOR Backward-incompatible changes (breaking changes) MINOR New backward-compatible functionality PATCH Backward-compatible bug fixes
Pre-releases: Use suffixes -alpha.N, -beta.N, -rc.N
Changelog Standard Follow Keep a Changelog format:
Section Description AddedNew features ChangedChanges in existing functionality DeprecatedSoon-to-be removed features RemovedRemoved features FixedBug fixes SecurityVulnerability fixes
Pre-commit Hooks Branching: GitHub Flow main always in deployable stateFeatures in short branches (feature/, fix/) Pull Requests required for merge to main Squash merge as preferred method Base CI/CD Every project must have CI/CD pipelines that enforce quality standards. Implementation details will be covered in the CI/CD Standards document.
Minimum Required Checks Check Purpose Tool Lint Code style and errors Ruff Type Check Static type verification Pyright Test Automated tests with coverage pytest Security Vulnerability scanning Bandit, pip-audit
GitHub CI/CD Files File Purpose .github/workflows/CI/CD pipeline definitions .github/dependabot.ymlAutomatic dependency updates
Documentation Docstring Style: Google Style What to Document Element Required Modules Yes Public classes Yes Public functions/methods Yes Private functions Recommended
Tool Purpose Configuration File markdownlint Markdown file linting .markdownlint.yaml cspell Spell checking in code and docs cspell.json
Local Development DevContainers File Purpose .devcontainer/devcontainer.jsonContainerized development environment configuration
Benefits:
Consistent environment for the entire team Instant onboarding (just open in VS Code) Pre-installed extensions and configurations Host system isolation Easy to replicate production-like environments