Install the skill above, then run this in your AI tool:
/python-code-style <your description>
About
Consistent code style and clear documentation make codebases maintainable and collaborative. This skill covers modern Python tooling, naming conventions, and documentation standards.
Source
What gets added to your project
Preview every file this package writes on install before you run the command above.
Summary
Python code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.
Skill instructions
Python Code Style & Documentation
Consistent code style and clear documentation make codebases maintainable and collaborative. This skill covers modern Python tooling, naming conventions, and documentation standards.
When to Use This Skill
Setting up linting and formatting for a new project
Writing or reviewing docstrings
Establishing team coding standards
Configuring ruff, mypy, or pyright
Reviewing code for style consistency
Creating project documentation
Core Concepts
1. Automated Formatting
Let tools handle formatting debates. Configure once, enforce automatically.
2. Consistent Naming
Follow PEP 8 conventions with meaningful, descriptive names.
3. Documentation as Code
Docstrings should be maintained alongside the code they describe.
4. Type Annotations
Modern Python code should include type hints for all public APIs.
Quick Start
bash
# Install modern tooling
pip install ruff mypy
# Configure in pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"# Adjust based on your project's minimum Python version
[tool.mypy]
strict = true
Fundamental Patterns
Pattern 1: Modern Python Tooling
Use ruff as an all-in-one linter and formatter. It replaces flake8, isort, and black with a single fast tool.
toml
# pyproject.toml[tool.ruff]line-length = 120target-version = "py312"# Adjust based on your project's minimum Python version[tool.ruff.lint]select = [
"E", # pycodestyle errors"W", # pycodestyle warnings"F", # pyflakes"I", # isort"B", # flake8-bugbear"C4", # flake8-comprehensions"UP", # pyupgrade"SIM", # flake8-simplify
]
ignore = ["E501"] # Line length handled by formatter[tool.ruff.format]quote-style = "double"indent-style = "space"
Run with:
bash
ruff check --fix . # Lint and auto-fix
ruff format . # Format code
Pattern 2: Type Checking Configuration
Configure strict type checking for production code.
Group imports in a consistent order: standard library, third-party, local.
python
# Standard libraryimport os
from collections.abc importCallablefrom typing importAny# Third-party packagesimport httpx
from pydantic import BaseModel
from sqlalchemy import Column
# Local importsfrom myproject.models import User
from myproject.services import UserService
Write docstrings for all public classes, methods, and functions.
Simple Function:
python
defget_user(user_id: str) -> User:
"""Retrieve a user by their unique identifier."""
...
Complex Function:
python
defprocess_batch(
items: list[Item],
max_workers: int = 4,
on_progress: Callable[[int, int], None] | None = None,
) -> BatchResult:
"""Process items concurrently using a worker pool.
Processes each item in the batch using the configured number of
workers. Progress can be monitored via the optional callback.
Args:
items: The items to process. Must not be empty.
max_workers: Maximum concurrent workers. Defaults to 4.
on_progress: Optional callback receiving (completed, total) counts.
Returns:
BatchResult containing succeeded items and any failures with
their associated exceptions.
Raises:
ValueError: If items is empty.
ProcessingError: If the batch cannot be processed.
Example:
>>> result = process_batch(items, max_workers=8)
>>> print(f"Processed {len(result.succeeded)} items")
"""
...
Class Docstring:
python
classUserService:
"""Service for managing user operations.
Provides methods for creating, retrieving, updating, and
deleting users with proper validation and error handling.
Attributes:
repository: The data access layer for user persistence.
logger: Logger instance for operation tracking.
Example:
>>> service = UserService(repository, logger)
>>> user = service.create_user(CreateUserInput(...))
"""def__init__(self, repository: UserRepository, logger: Logger) -> None:
"""Initialize the user service.
Args:
repository: Data access layer for users.
logger: Logger for tracking operations.
"""self.repository = repository
self.logger = logger
Pattern 6: Line Length and Formatting
Set line length to 120 characters for modern displays while maintaining readability.
python
# Good: Readable line breaksdefcreate_user(
email: str,
name: str,
role: UserRole = UserRole.MEMBER,
notify: bool = True,
) -> User:
...
# Good: Chain method calls clearly
result = (
db.query(User)
.filter(User.active == True)
.order_by(User.created_at.desc())
.limit(10)
.all()
)
# Good: Format long strings
error_message = (
f"Failed to process user {user_id}: "f"received status {response.status_code} "f"with body {response.text[:100]}"
)
Pattern 7: Project Documentation
README Structure:
markdown
# Project Name
Brief description of what the project does.
## Installation
\`\`\`bash
pip install myproject
\`\`\`
## Quick Start
\`\`\`python
from myproject import Client
client = Client(api_key="...")
result = client.process(data)
\`\`\`
## Configuration
Document environment variables and configuration options.
## Development
\`\`\`bash
pip install -e ".[dev]"
pytest
\`\`\`
CHANGELOG Format (Keep a Changelog):
markdown
# Changelog## [Unreleased]### Added- New feature X
### Changed- Modified behavior of Y
### Fixed- Bug in Z
Best Practices Summary
Use ruff - Single tool for linting and formatting
Enable strict mypy - Catch type errors before runtime
120 character lines - Modern standard for readability
Descriptive names - Clarity over brevity
Absolute imports - More maintainable than relative
Add this badge to a GitHub README so readers can open the package page and install the same version.
[](https://www.aipm-registry.com/skills/wshobson/python-code-style/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)
This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.
AI assistant context
What this skill is for
@wshobson/python-code-style@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: Python code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.
Run aipm add @wshobson/python-code-style@1.0.0 in a project that has AIPM initialized.
Supported tools
@wshobson/python-code-style@1.0.0 supports All tools.
Before installing
AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.