python-backend
最佳实践工作流程和安全准则,适用于Python后端工作(API/服务、数据访问、后台任务、命令行界面)。在Codex编写或重构Python应用程序代码、设置Python工具、提升性能、添加测试或做出打包/代码风格/类型检查决策(uv、Ruff、mypy、pytest)时使用,包括数据工具选择(优先使用polars)和安全的配置模式(.env)。
📖 中文导读:最佳实践工作流程和安全准则,适用于Python后端工作(API/服务、数据访问、后台任务、命令行界面)。在Codex编写或重构Python应用程序代码、设置Python工具、提升性能、添加测试或做出打包/代码风格/类型检查决策(uv、Ruff、mypy、pytest)时使用,包括数据工具选择(优先使用polars)和安全的配置模式(.env)。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: python-backend description: Best-practice workflow and guardrails for Python backend work (APIs/services, data access, background jobs, CLIs). Use when Codex is writing or refactoring Python application code, setting up Python tooling, improving performance, adding tests, or making packaging/lint/type-check decisions (uv, Ruff, mypy, pytest), including data tooling choices (prefer polars) and secure config patterns (.env).
Python Backend
Apply these rules when producing or modifying Python backend code. Optimize for correctness, performance, and maintainability while keeping changes small and reversible.
Defaults
- Prefer clarity first, then optimize hotspots based on evidence (profiling/benchmarks) rather than blanket micro-optimizations.
- Avoid unnecessary abstractions; keep code minimal and easy to review.
- Use descriptive names; avoid one-letter names outside tight comprehensions.
Tooling
- Use
uvfor dependency management and virtual environments (.venv) when appropriate for the repo. - Use Ruff for formatting + linting (do not mix with Black/isort unless the repo already does).
- Use mypy for static type checking when the repo is typed; match the repo's existing strictness.
- Use pytest for tests; follow Arrange-Act-Assert for readability.
- For notebooks, install
ipykernel/ipywidgetsinto the local.venvwhen needed, but do not add them to runtime requirements.
Code style
- Follow PEP 8; default to 4-space indentation.
- Prefer
pathlib.Pathover raw string paths for file operations (unless the repo standard differs). - Use f-strings for formatting; use
enumerate()over manual counters. - Avoid mutable default arguments.
Types and APIs
- Type all public function signatures (params + return types).
- Avoid
Any; if unavoidable, isolate it at the boundary (e.g., parsing/IO) and convert to typed structures quickly. - Prefer dataclasses (or
pydanticmodels if the repo already uses them) for structured data.
Errors and logging
- Catch specific exceptions; never use bare
except:. - Do not swallow exceptions silently; log and re-raise or translate to a domain-appropriate error.
- Prefer structured logging; use
logger.exception(...)when handling unexpected failures.
Data work
- Prefer
polarsoverpandasfor new dataframe work unless the repo standardizes on pandas. - When printing a
polarsDataFrame, do not redundantly print both schema and row counts unless explicitly requested.
Security and config
- Never hardcode secrets/tokens/credentials; load from environment variables or
.envfor local dev. - Ensure
.envis excluded via.gitignorewhen relevant. - Avoid logging secrets or URLs containing secrets.
Testing expectations
- Add unit tests for new logic (pure functions and business rules first).
- Mock external dependencies (network, databases, filesystem) at the boundary.
- Do not generate "tests" inside production modules; place them in dedicated test files matching repo conventions.
Pre-PR checklist
- Run Ruff and relevant tests for changed modules.
- Run mypy if the project uses it and types were touched.
- Confirm no debug prints/breakpoints or commented-out code is introduced.