following-conventions
Tenzir Python coding standards and tooling setup. Use when editing .py files, running ruff/mypy/pytest, encountering pyproject.toml/uv.lock, or setting up a new Python project.
When & Why to Use This Skill
This Claude skill streamlines Python development by enforcing Tenzir's professional coding standards and automating tooling setup. It integrates essential modern tools like uv for dependency management, Ruff for linting and formatting, Mypy for static type checking, and pytest for robust testing, ensuring high-quality, maintainable codebases.
Use Cases
- New Project Setup: Automatically initialize a Python 3.12+ project with standardized directory structures, pyproject.toml configurations, and uv virtual environments.
- Automated Quality Gates: Execute a unified command chain (Ruff, Mypy, pytest) to validate code quality and type safety before commits or releases.
- Code Style Enforcement: Automatically format code and sort imports according to strict PEP 8-compliant rules using Ruff to maintain a consistent codebase.
- Type Hinting & Validation: Implement strict Mypy settings and Pydantic models to eliminate type errors and ensure data integrity across public APIs.
- CLI & API Development: Standardize the creation of REST APIs with FastAPI and command-line tools with Click, following specific naming and documentation conventions.
| name | following-conventions |
|---|---|
| description | Tenzir Python coding standards and tooling setup. Use when writing python code, running ruff/mypy/pytest, encountering pyproject.toml/uv.lock, or setting up a new Python project. |
Python Coding Conventions
Coding standards for Python projects at Tenzir.
Required Tools
All projects use:
- uv — Dependency management and virtual environments
- Ruff — Linting and formatting
- Mypy — Static type checking
- pytest — Testing
Default Libraries
Prefer to use these libraries to ensure uniform codebase across Tenzir repositories:
- pydantic - Defining and validating models
- FastAPI - Declaring REST APIs
- Click - Providing a CLI interface
Quality Gates
Run before committing or releasing:
uv run ruff check \
&& uv run ruff format --check \
&& uv run mypy \
&& uv run pytest \
&& uv build
The chain fails fast on the first error.
Python Version
Target Python 3.12+. Use modern syntax and stdlib features freely—no backwards-compatibility with older versions.
Coding Style
Formatting
- Ruff controls whitespace: 4-space indentation, double-quoted strings
- 88 character line limit (Ruff/Black default)
- Let Ruff order imports automatically
Type Hints
- All public surfaces must be fully typed
- Strict Mypy settings reject untyped or partial definitions
- Avoid
Any; fix warnings rather than ignoring them
Package structure and imports
- Keep
__init__.pyfiles empty. They are only used to mark a directory as importable but do not contain any content, let alone non-trivial code. - Always use absolute imports from the package top level:
from this_package.foo import barinstead offrom .foo import bar. - Never use wildcard imports
Naming Conventions
| Element | Convention | Example |
|---|---|---|
| Modules | snake_case |
my_module.py |
| Functions | snake_case |
calculate_total() |
| Variables | snake_case |
user_count |
| Classes | PascalCase |
DataProcessor |
| Constants | CONSTANT_CASE |
MAX_RETRIES |
CLI Conventions
- Use kebab-case for CLI flags:
--output-file, not--output_file - Keep user messages concise
Documentation Style
- Write in active voice; rewrite passive sentences before committing
- Focus on user-facing impact, not implementation details
- Use explicit imports; isolate configuration helpers in
config.py
Unit Test Conventions
- Use
pytestas testing framework - Use
CliRunnerfor end-to-end CLI testing - Favor
tmp_pathfor filesystem tests - Use parametrization for scenario variation
- Maintain ≥80% coverage when coverage is configured
Project Setup
Only read the specific file you need when setting up a new project or modifying that tool's configuration:
- project-structure.md — Directory layout and testing conventions
- pyproject.md — Project metadata and build config
- ruff.md — Ruff linting and formatting config
- mypy.md — Mypy type checking config
- pytest.md — Pytest runner config
- coverage.md — Coverage reporting config
- dev-dependencies.md — Dev dependency group
- upgrading-dependencies.md — Upgrading and committing dependency changes