Python Code Style

by wshobson46891e7e60daNo licenseListed Oct 8, 2026Updated Oct 8, 2026

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.

Instructions onlySoftware Development

AI-generated overview

Guides Python code style, linting, formatting, naming, type checking and docstring conventions.

What it does: This skill provides reference guidance for establishing and applying Python code style standards. It covers configuring ruff for linting and formatting, strict mypy or pyright type checking, PEP 8 naming conventions, import organization, Google-style docstrings, line length, and project documentation such as README and CHANGELOG structure. It produces configuration snippets and style recommendations rather than executable tooling.
When to use it: Use it when writing or reviewing Python code for style consistency, setting up linting and formatting for a project, configuring ruff, mypy or pyright, writing docstrings, or defining team coding standards.
Requirements: No scripts are included; it is instructions only. Applying the guidance assumes Python tooling such as ruff, mypy or pyright and a pyproject.toml configuration file, but the skill itself requires nothing beyond the agent.

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 toolingpip install ruff mypy
# Configure in pyproject.toml[tool.ruff]line-length = 120target-version = "py312"  # Adjust based on your project's minimum Python version
[tool.mypy]strict = true

# Install modern toolingpip install ruff mypy
# Configure in pyproject.toml[tool.ruff]line-length = 120target-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"

# 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:

Pattern 2: Type Checking Configuration

Configure strict type checking for production code.

toml

# pyproject.toml[tool.mypy]python_version = "3.12"strict = truewarn_return_any = truewarn_unused_ignores = truedisallow_untyped_defs = truedisallow_incomplete_defs = true
[[tool.mypy.overrides]]module = "tests.*"disallow_untyped_defs = false

# pyproject.toml[tool.mypy]python_version = "3.12"strict = truewarn_return_any = truewarn_unused_ignores = truedisallow_untyped_defs = truedisallow_incomplete_defs = true
[[tool.mypy.overrides]]module = "tests.*"disallow_untyped_defs = false

Alternative: Use pyright for faster checking.

Pattern 3: Naming Conventions

Follow PEP 8 with emphasis on clarity over brevity.

Files and Modules:

python

# Good: Descriptive snake_caseuser_repository.pyorder_processing.pyhttp_client.py
# Avoid: Abbreviationsusr_repo.pyord_proc.pyhttp_cli.py

# Good: Descriptive snake_caseuser_repository.pyorder_processing.pyhttp_client.py
# Avoid: Abbreviationsusr_repo.pyord_proc.pyhttp_cli.py

Classes and Functions:

python

# Classes: PascalCaseclass UserRepository:    pass
class HTTPClientFactory:  # Acronyms stay uppercase    pass
# Functions and variables: snake_casedef get_user_by_email(email: str) -> User | None:    retry_count = 3    max_connections = 100

# Classes: PascalCaseclass UserRepository:    pass
class HTTPClientFactory:  # Acronyms stay uppercase    pass
# Functions and variables: snake_casedef get_user_by_email(email: str) -> User | None:    retry_count = 3    max_connections = 100

Constants:

python

# Module-level constants: SCREAMING_SNAKE_CASEMAX_RETRY_ATTEMPTS = 3DEFAULT_TIMEOUT_SECONDS = 30API_BASE_URL = "https://api.example.com"

# Module-level constants: SCREAMING_SNAKE_CASEMAX_RETRY_ATTEMPTS = 3DEFAULT_TIMEOUT_SECONDS = 30API_BASE_URL = "https://api.example.com"

Pattern 4: Import Organization

Group imports in a consistent order: standard library, third-party, local.

python

# Standard libraryimport osfrom collections.abc import Callablefrom typing import Any
# Third-party packagesimport httpxfrom pydantic import BaseModelfrom sqlalchemy import Column
# Local importsfrom myproject.models import Userfrom myproject.services import UserService

# Standard libraryimport osfrom collections.abc import Callablefrom typing import Any
# Third-party packagesimport httpxfrom pydantic import BaseModelfrom sqlalchemy import Column
# Local importsfrom myproject.models import Userfrom myproject.services import UserService

Use absolute imports exclusively:

python

# Preferredfrom myproject.utils import retry_decorator
# Avoid relative importsfrom ..utils import retry_decorator

# Preferredfrom myproject.utils import retry_decorator
# Avoid relative importsfrom ..utils import retry_decorator

Advanced Patterns

Pattern 5: Google-Style Docstrings

Write docstrings for all public classes, methods, and functions.

Simple Function:

Complex Function:

python

def process_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")    """    ...

def process_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

class UserService:    """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

class UserService:    """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 breaksdef create_user(    email: str,    name: str,    role: UserRole = UserRole.MEMBER,    notify: bool = True,) -> User:    ...
# Good: Chain method calls clearlyresult = (    db.query(User)    .filter(User.active == True)    .order_by(User.created_at.desc())    .limit(10)    .all())
# Good: Format long stringserror_message = (    f"Failed to process user {user_id}: "    f"received status {response.status_code} "    f"with body {response.text[:100]}")

# Good: Readable line breaksdef create_user(    email: str,    name: str,    role: UserRole = UserRole.MEMBER,    notify: bool = True,) -> User:    ...
# Good: Chain method calls clearlyresult = (    db.query(User)    .filter(User.active == True)    .order_by(User.created_at.desc())    .limit(10)    .all())
# Good: Format long stringserror_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
\`\`\`bashpip install myproject\`\`\`
## Quick Start
\`\`\`pythonfrom myproject import Client
client = Client(api_key="...")result = client.process(data)\`\`\`
## Configuration
Document environment variables and configuration options.
## Development
\`\`\`bashpip install -e ".[dev]"pytest\`\`\`

# Project Name
Brief description of what the project does.
## Installation
\`\`\`bashpip install myproject\`\`\`
## Quick Start
\`\`\`pythonfrom myproject import Client
client = Client(api_key="...")result = client.process(data)\`\`\`
## Configuration
Document environment variables and configuration options.
## Development
\`\`\`bashpip 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

# 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
Google-style docstrings - Consistent, readable documentation
Document public APIs - Every public function needs a docstring
Keep docs updated - Treat documentation as code
Automate in CI - Run linters on every commit
Target Python 3.10+ - For new projects, Python 3.12+ is recommended for modern language features

Source and attribution

Source:wshobson/agentsinplugins/python-development/skills/python-code-styleat commit46891e7

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Python Code Style

Python Code Style & Documentation

When to Use This Skill

Core Concepts

1. Automated Formatting

2. Consistent Naming

3. Documentation as Code

4. Type Annotations

Quick Start

Fundamental Patterns

Pattern 1: Modern Python Tooling

Pattern 2: Type Checking Configuration

Pattern 3: Naming Conventions

Pattern 4: Import Organization

Advanced Patterns

Pattern 5: Google-Style Docstrings

Pattern 6: Line Length and Formatting

Pattern 7: Project Documentation

Best Practices Summary

Source and attribution

More from wshobson/agents

Uv Package Manager

Web Component Design

Python Type Safety

Visual Design Foundations

Responsive Design

Python Resource Management

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api