Python Code Style

作者 wshobson46891e7e60da无许可证收录于 2026年10月8日更新于 2026年10月8日

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.

仅含说明Software Development
AI 生成的概览

指导 Python 代码风格、代码检查、格式化、命名、类型检查与文档字符串规范。

功能
该技能提供建立并应用 Python 代码风格标准的参考指引。内容涵盖配置 ruff 进行代码检查与格式化、使用严格的 mypy 或 pyright 类型检查、PEP 8 命名约定、导入组织、Google 风格文档字符串、行长度，以及 README 和 CHANGELOG 等项目文档结构。它产出的是配置片段与风格建议，而非可执行工具。
适用场景
适用于编写或审查 Python 代码以保持风格一致、为新项目设置代码检查与格式化、配置 ruff、mypy 或 pyright、编写文档字符串，或制定团队编码规范时。
运行要求
不包含脚本，仅为说明性指引。应用这些指引通常需要 ruff、mypy 或 pyright 等 Python 工具以及 pyproject.toml 配置文件，但技能本身除智能体外无需其他依赖。

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

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-fixruff format .       # Format code

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

Alternative: Use pyright for faster checking.

toml
[tool.pyright]pythonVersion = "3.12"typeCheckingMode = "strict"

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

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

Constants:

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

Use absolute imports exclusively:

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

python
def get_user(user_id: str) -> User:    """Retrieve a user by their unique identifier."""    ...

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

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

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]}")

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\`\`\`

CHANGELOG Format (Keep a Changelog):

markdown
# Changelog
## [Unreleased]
### Added- New feature X
### Changed- Modified behavior of Y
### Fixed- Bug in Z

Best Practices Summary

  1. Use ruff - Single tool for linting and formatting
  2. Enable strict mypy - Catch type errors before runtime
  3. 120 character lines - Modern standard for readability
  4. Descriptive names - Clarity over brevity
  5. Absolute imports - More maintainable than relative
  6. Google-style docstrings - Consistent, readable documentation
  7. Document public APIs - Every public function needs a docstring
  8. Keep docs updated - Treat documentation as code
  9. Automate in CI - Run linters on every commit
  10. Target Python 3.10+ - For new projects, Python 3.12+ is recommended for modern language features

来源与署名

来源：wshobson/agents位于plugins/python-development/skills/python-code-style提交46891e7

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 wshobson/agents 的技能

Uv Package Manager

wshobson

关于使用 uv Python 包管理器管理依赖、虚拟环境和项目工作流的参考指南。

Software Development2026年10月8日

Web Component Design

wshobson

指导在 React、Vue 和 Svelte 中构建可复用 UI 组件，涵盖组合模式、CSS-in-JS 选择与组件 API 设计。

Software Development2026年10月8日

Python Type Safety

wshobson

指导 Python 类型注解、泛型、协议以及 mypy/pyright 严格类型检查。

Software Development2026年10月8日

Visual Design Foundations

wshobson

指导排版、色彩、间距与图标设计，帮助建立统一且无障碍的视觉设计体系。

Design & Creative2026年10月8日

Responsive Design

wshobson

指导使用容器查询、流体排版、CSS Grid 和断点策略实现响应式网页布局。

Software Development2026年10月8日

Python Resource Management

wshobson

指导 Python 开发者使用上下文管理器、清理模式和流式处理来确定性管理资源。

Software Development2026年10月8日

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Testing Strategy

anthropics

精选

设计测试策略与测试计划，涵盖测试类型、覆盖率目标与示例测试用例。

Software Development27K今天更新

Tech Debt

anthropics

精选

识别、分类并排序技术债务，产出评分后的待办清单与分阶段整改计划。

Software Development27K今天更新

System Design

anthropics

精选

通过需求、高层设计、深入设计、扩展与权衡分析来指导系统与架构设计。

Software Development27K今天更新