AgentSkillsCN

python-standards

使用 uv、ruff、mypy 和 pytest 进行现代 Python 开发。适用场景如下： - 编写或审查 Python 代码 - 搭建 Python 项目或配置 pyproject.toml - 选择依赖管理工具（uv、poetry、pip） - 配置代码风格检查、格式化或类型检查 - 整理 Python 软件包 关键词：Python、pyproject.toml、uv、ruff、mypy、pytest、类型注解、虚拟环境、锁定文件、软件包结构

SKILL.md
--- frontmatter
name: python-standards
description: |
  Modern Python development with uv, ruff, mypy, and pytest. Use when:
  - Writing or reviewing Python code
  - Setting up Python projects or pyproject.toml
  - Choosing dependency management (uv, poetry, pip)
  - Configuring linting, formatting, or type checking
  - Organizing Python packages
  Keywords: Python, pyproject.toml, uv, ruff, mypy, pytest, type hints,
  virtual environment, lockfile, package structure

Python Standards

Modern Python with uv + ruff + mypy + pytest. All config in pyproject.toml.

Toolchain

ToolPurpose
uvDependencies + virtual envs (lockfile: uv.lock)
ruffLinting + formatting (replaces black, isort, flake8)
mypyType checking (strict mode)
pytestTesting + coverage
bash
# Setup
uv init && uv add <deps> && uv sync

# Daily workflow
uv run ruff check . --fix && uv run ruff format .
uv run mypy . && uv run pytest

Type Hints

All functions and classes must have explicit type hints:

python
def fetch_user(user_id: str) -> User | None:
    """Fetch user by ID."""
    ...

def process_items(items: list[Item]) -> dict[str, int]:
    ...

mypy strict mode:

toml
[tool.mypy]
strict = true
disallow_untyped_defs = true
disallow_any_generics = true

Package Structure

Feature-based, not layer-based:

code
src/myproject/
  users/           # Domain
    __init__.py    # Public API: __all__ = ['User', 'UserService']
    models.py
    services.py
  orders/          # Another domain
  shared/          # Cross-cutting concerns

Error Handling

Catch specific exceptions with context:

python
try:
    result = parse_config(path)
except FileNotFoundError:
    logger.warning(f"Config not found: {path}")
    return defaults
except json.JSONDecodeError as e:
    raise ConfigError(f"Invalid JSON in {path}") from e

Never: bare except:, silent swallowing, except Exception.

pyproject.toml

Single source of truth (no setup.py, requirements.txt):

toml
[project]
name = "myproject"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = ["httpx", "pydantic"]

[project.optional-dependencies]
dev = ["pytest", "mypy", "ruff"]

[tool.ruff]
select = ["E", "W", "F", "I", "B", "UP", "SIM", "S", "ANN"]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = ["--cov=src", "--cov-fail-under=85"]

Anti-Patterns

  • •Any without documented justification
  • •Layer-based folders (/controllers, /models, /views)
  • •Circular imports
  • •Legacy tools (pip, black+isort, flake8)
  • •Multiple config files
  • •noqa comments without justification

References