python-best-practices
npx machina-cli add skill lklimek/claudius/python-best-practices --openclawFiles (1)
SKILL.md
1.8 KB
Python Best Practices
Technical Standards
- Python Version: 3.9+ features
- Code Style: PEP 8, use black/ruff for formatting
- Type Hints: typing module for all public APIs
- Testing: pytest with minimum 80% coverage
- Documentation: One-line docstring for every public function/class; expand only when non-obvious (Google/NumPy/Sphinx style)
- Error Handling: Specific exception types, proper error messages
- Dependencies: poetry or pip-tools
- Virtual Environments: Always use virtual environments
Best Practices
- Context managers (with statements) for resource management
- Prefer composition over inheritance
- Use dataclasses or Pydantic for data structures
- Generators for memory efficiency with large datasets
- Proper logging (logging module, not print)
- async/await for I/O-bound operations when beneficial
- No mutable default arguments
Code Quality Tools
- Linting: pylint, flake8, or ruff
- Formatting: black or ruff
- Type Checking: mypy or pyright
- Testing: pytest with coverage.py
- Security: bandit for security checks
Code Review Checklist
- PEP 8 compliance and consistent style
- Type hint coverage on public APIs
- Docstring presence and accuracy
- DRY compliance: duplicated logic, copy-paste patterns
- Naming clarity: variables, functions, classes, modules
- Context managers for resource management
- Exception types are specific, not bare except
- Test quality: meaningful assertions, edge cases, error paths, proper mocking
- Code brevity: flag code that can be expressed in fewer lines without losing clarity
Use PY-NNN prefix for all findings.
Source
git clone https://github.com/lklimek/claudius/blob/main/skills/python-best-practices/SKILL.mdView on GitHub Overview
This skill codifies Python best practices across PEP 8, type hints, testing, error handling, and code quality tooling. It helps developers write, review, and discuss Python code with consistent standards, modern tooling, and measurable quality.
How This Skill Works
The skill prescribes a practical workflow: enforce PEP 8 formatting with Black or Ruff, annotate all public APIs with typing, and maintain one-line docstrings; run tests with pytest aiming for at least 80% coverage; use linting (pylint/flake8/ruff), type checking (mypy/pyright), and security checks (Bandit). During reviews, issues are reported with the PY-NNN prefix for traceability.
When to Use It
- Starting a new Python project or adding new modules
- Reviewing pull requests to enforce style and quality
- Refactoring for clearer design, favoring composition over inheritance
- Modeling data structures with dataclasses or Pydantic
- Optimizing I/O or memory usage with generators or async/await where beneficial
Quick Start
- Step 1: Set up a Python 3.9+ virtual environment (virtualenv or poetry) and a project skeleton
- Step 2: Install and configure tools: Black/Ruff, mypy/pyright, pytest with coverage, Bandit for security
- Step 3: Start applying practices: annotate public APIs, add one-line docstrings, run linters and tests, and label issues with PY-NNN
Best Practices
- Context managers (with statements) for resource management
- Prefer composition over inheritance
- Use dataclasses or Pydantic for data structures
- Generators for memory-efficient data processing
- Use logging module instead of print and proper logging configuration
Example Use Cases
- Opening files with with open(...) as f to ensure proper cleanup
- A class designed with composition, delegating behavior to component objects
- A data model defined as a @dataclass with explicit type hints
- A large data pipeline implemented as a generator to stream data
- Replacing print statements with a configured logging.Logger for output
Frequently Asked Questions
Add this skill to your agents
