AgentSkillsCN

python-best-practices

应用生产级 Python 标准（src/ 布局、类型注解、测试、uv+taskipy+ruff、CI 门禁、安全性、性能）；适用于启动新项目或重构现有 Python 项目时使用。

SKILL.md
--- frontmatter
name: python-best-practices
description: Apply production-grade Python standards (src/ layout, typing, tests, uv+taskipy+ruff, CI gates, security, performance); use for bootstrapping or refactoring Python projects.
license: MIT
metadata:
  author: Y4rd13
  version: "1.0.0"

Use this skill to bootstrap, refactor, or review Python projects with modern production practices.

Non-negotiables

  • •Code comments MUST be ONLY essential and in ENGLISH.
  • •Prefer explicit dependencies (DI/composition root) over hidden global state (Singleton anti-pattern).
  • •Make changes minimal and behavior-preserving unless the user requests breaking changes.

Standard Tooling Baseline (uv + taskipy + ruff + mypy + pytest)

This skill standardizes uv run task lint_fix using the provided template:

  • •assets/templates/pyproject.toml.tmpl

Default expectation

  • •Project uses uv with pyproject.toml + uv.lock.
  • •Tasks exist under [tool.taskipy.tasks], including lint_fix.
  • •Lint/format is enforced via:
    • •ruff check --fix .
    • •ruff format .
    • •plus optional black . (kept for compatibility).

When to adjust the template

Adjust ONLY if necessary:

  • •Python version differs from >=3.14,<3.15
  • •Ruff target differs from py314
  • •line-length differs from 121
  • •build backend differs (e.g., hatchling/poetry) — keep src layout as-is

Workflow (apply in order)

1) Identify boundaries

  • •Project type: library / CLI / service / data pipeline.
  • •Composition root: where dependencies are wired (e.g., main.py, app/__init__.py, cli.py).
  • •I/O boundaries: API routes, CLI args, job runners, external clients.

2) Enforce project layout

Recommended baseline:

  • •src/<package>/...
  • •tests/
  • •scripts/ (project tooling only)
  • •Avoid utils.py dumping grounds; prefer domain/feature modules.

3) Dependency management with uv

Principles:

  • •Commit uv.lock for reproducibility.
  • •CI should install exactly from the lockfile:
    • •uv sync --frozen

Common commands:

  • •uv add <pkg>
  • •uv remove <pkg>
  • •uv lock
  • •uv sync

4) Enforce lint/format via taskipy

Required:

  • •uv run task lint_fix
  • •uv run task lint
  • •uv run task test

If missing, add tasks using the provided template (assets/templates/pyproject.toml.tmpl).

5) OOP and data modeling

Use classes intentionally:

  • •Prefer functions by default.
  • •Use classes when you need state, invariants, resource lifecycle, or polymorphism.

Rules:

  • •Prefer composition over deep inheritance.
  • •For data containers, prefer @dataclass with:
    • •no mutable defaults (use default_factory)
    • •frozen=True when immutability helps
    • •slots=True only if you measured and it matters

Interfaces:

  • •Prefer Protocol for decoupled interfaces.
  • •Use ABC only when you need runtime enforcement.

6) Typing as contracts

  • •Type boundaries first: public APIs, domain models, adapters.
  • •Avoid Any unless unavoidable (and document why).
  • •Keep typing policy consistent (gradual typing is OK).

7) Documentation (minimal but useful)

  • •Docstrings for public APIs.
  • •Document exceptions for boundaries.
  • •Avoid redundant comments. Comments only when they add non-obvious intent.

8) Testing

  • •Use pytest; keep tests deterministic.
  • •Prefer fixtures + parametrization.
  • •Split unit vs integration when needed.

9) Logging + error handling

  • •No print() in production codepaths.
  • •Use logging.getLogger(__name__).
  • •Never swallow exceptions silently.
  • •Use raise X from e when wrapping.

10) Async/concurrency (when applicable)

  • •Never block the event loop with sync I/O.
  • •Always use timeouts and cancellation-aware code.
  • •Add retries/backoff only at boundaries (external calls), not deep inside core logic.

11) Performance (only if justified)

  • •Choose correct data structures (e.g., deque for queues).
  • •Measure before optimizing (timeit/profilers).
  • •Use caching carefully and with limits.

12) Security baseline

  • •Never unpickle untrusted input.
  • •Avoid shell=True unless strictly required.
  • •Use secrets for tokens.

Output format (when applying this skill)

Provide:

  1. •Gaps found (tooling/layout/typing/tests/security).
  2. •A small-step plan.
  3. •Concrete diffs (pyproject/ruff/mypy/pytest) + minimal code changes.
  4. •Conventional commit messages (one line, English).
  5. •Final reminder: run uv run task lint_fix before commit.