跳到主内容
智客 ZICQ

技能库 智客分类:设计创意 python-best-practices

Python Best Practices

Python软件工程指南来自真实的PR审查模式. 在写作,审查,或重构Python代码时,应当使用这种技能——特别是数据类,服务界面,错误处理,以及类型说明. 触发任务涉及Python模块,API设计,数据建模,类型安全,例外处理,或用于可维护性的再造. 关于亚眠和通币指导,请参见蟒-亚眠-最佳实践技巧.

810 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

Python软件工程指南来自真实的PR审查模式. 在写作,审查,或重构Python代码时,应当使用这种技能——特别是数据类,服务界面,错误处理,以及类型说明. 触发任务涉及Python模块,API设计,数据建模,类型安全,例外处理,或用于可维护性的再造. 关于亚眠和通币指导,请参见蟒-亚眠-最佳实践技巧.

何时用

官方 description 未单独写出 Use when。按规范,代理会在用户任务与这段 description 的关键词匹配时激活本技能。

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Python Best Practices、When to Apply、Impact Levels、Python Version Baseline、Rule Categories by Priority、Quick Reference。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.

Python Best PracticesWhen to ApplyImpact LevelsPython Version BaselineRule Categories by PriorityQuick ReferenceData Modeling (`data-`)Error Handling (`error-`)Type Safety (`types-`)API Design (`api-`)Code Simplification (`simplify-`)Performance (`perf-`)

· 许可:MIT

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
python-best-practices
description
Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.
许可
MIT
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「python-best-practices」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-ea18d84c61693501-Python-%E6%9C%80%E4%BD%B3%E5%81%9A%E6%B3%95.html
请存为 .cursor/skills/python-best-practices/SKILL.md 或 .claude/skills/python-best-practices/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/nathan-gage/python-skills' --list

npx skills add 'https://github.com/nathan-gage/python-skills' --skill 'python-best-practices'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: python-best-practices description: Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill. license: MIT metadata: author: python-best-practices version: "1.5.0" pythonVersion: ">=3.11"

Python Best Practices

Guidelines for writing and reviewing Python. 75 rules across 8 categories, prioritized by impact.

A rule match is a signal, not a verdict. Most rules are design preferences for new code, not bugs to fix across the repo — check the rule's impact level before flagging in review or refactoring stable code.

Quick-reference lines are triggers, not licenses: before applying a rule as a review finding or a transformation, open the rule file and check its counter-signal — the marker-opened paragraph (**When ...** / **Scope:** / **Preserve ...**) saying when NOT to apply it.

When to Apply

  • Writing new Python modules, functions, classes, or data models
  • Reviewing code for correctness or type safety
  • Refactoring patterns in code that's being edited anyway

Avoid applying these rules as a blanket sweep across stable code — the churn rarely pays off.

Impact Levels

  • CRITICAL — prevents a real bug class (data corruption, swallowed cancellations, insecure defaults). Fix when found.
  • HIGH — meaningful correctness or maintainability win. Worth fixing in most contexts.
  • MEDIUM — good practice; clarity or drift prevention. Apply to new code; don't churn stable code.
  • LOW-MEDIUM / LOW — style or micro-optimizations. Apply opportunistically.

Python Version Baseline

Rules assume Python 3.11+. Rules depending on higher versions call it out inline:

  • warnings.deprecated() — 3.13+
  • zoneinfo — 3.9+
  • Union types in isinstance() — 3.10+
  • assert_never — 3.11+ (backport via typing_extensions)
  • PEP 695 type statement and generic syntax — 3.12+ (noted inline in types-modern-syntax)

Rules tagged applicability:pydantic are Pydantic-specific.

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Data Modeling | HIGH | data- | | 2 | Error Handling | MEDIUM-HIGH | error- | | 3 | Type Safety | MEDIUM-HIGH | types- | | 4 | API Design | MEDIUM | api- | | 5 | Code Simplification | LOW-MEDIUM | simplify- | | 6 | Performance | LOW-MEDIUM | perf- | | 7 | Naming | LOW-MEDIUM | naming- | | 8 | Imports & Structure | LOW | imports- |

Section impact is a typical-case label; individual rules range one level above or below — check the rule file.

Quick Reference

Data Modeling (data-)

  • data-mutable-defaults — Never def f(items=[]); use None + body construction or default_factory
  • data-derive-dont-store — Compute booleans from state; don't cache flags that mirror each other
  • data-mutation-contract — One unambiguous contract per function: mutate (new-info returns fine) or return new — never the mutated object as if fresh
  • data-aware-datetimes — Timezone-aware datetime.now(timezone.utc); utcnow() is deprecated
  • data-discriminated-unions — Tag variants instead of optional-field bags
  • data-explicit-variants — Concrete classes per mode beat is_thread / is_edit flags
  • data-phased-composition — Group co-present optionals into one nested optional
  • data-encapsulate-mutable-state — Trap mutable state in the narrowest clear scope
  • data-sentinel-when-none-is-valid — Private sentinel when None is a meaningful value
  • data-newtype-for-ids — NewType('UserId', str) so IDs aren't interchangeable
  • data-delete-dead-variants — Remove union arms that aren't constructed
  • data-reject-bool-as-int — bool subclasses int; reject it explicitly before numeric checks

Error Handling (error-)

  • error-specific-exceptions — Catch specific types; never bare except: or except BaseException: (breaks Ctrl-C and async cancellation); except Exception: is cancellation-safe on 3.8+
  • error-context-managers — with / async with for files, locks, sessions
  • error-assert-debug-only — assert vanishes under -O; not for runtime contracts
  • error-validate-at-boundaries — Fail fast at system edges before expensive work
  • error-trust-validated-state — Trust immutable, locally-constructed state
  • error-consolidate-try-except — Merge blocks with the same catch and handling
  • error-assert-never-exhaustiveness — typing.assert_never for exhaustiveness
  • error-raise-from-for-chains — raise NewErr(...) from original to preserve causality
  • error-inherit-base-exceptions — New exceptions inherit existing bases for compatibility
  • error-log-exception-context — logger.exception(...) inside except; keep the traceback in the log
  • error-repr-in-messages — f"tool {name!r}" for identifiers in error text
  • error-match-types-not-messages — Classify by exception type and status code, never message substrings

Type Safety (types-)

  • types-fix-errors-not-ignore — Fix type errors; # type: ignore is a last resort
  • types-avoid-any — Protocols, TypeVars, unions over Any
  • types-typeddict-over-dict-any — TypedDict / dataclass when structure is known
  • types-literal-for-fixed-sets — Literal["a", "b"] for fixed strings
  • types-fix-types-not-cast — Fix the definition; cast() only when runtime genuinely narrows
  • types-isinstance-for-narrowing — isinstance() over hasattr / type(x).__name__
  • types-narrow-to-runtime-reality — Annotations match what control flow actually allows
  • types-trust-the-checker — Drop runtime checks the types already enforce
  • types-remove-redundant-optional — Drop | None when values are guaranteed present
  • types-type-checking-imports — if TYPE_CHECKING: for optional or heavy imports
  • types-modern-syntax — X | None, list[str]; not Optional / Union / typing.List
  • types-sequence-over-list-params — Sequence / Mapping for read-only params; list is invariant

API Design (api-)

  • api-required-before-optional — Required fields before optional (Python enforces this)
  • api-keyword-only-params — * marker for optional/config params
  • api-no-boolean-flag-params — Literal / Enum over True, False soup
  • api-immutable-transforms — Return new collections; don't mutate inputs
  • api-model-cohesion — Flat models; no duplicate or single-key-wrapped fields
  • api-underscore-for-private — _prefix for internals; exclude from __all__
  • api-deprecated-aliases — warnings.deprecated() (3.13+) for renamed APIs
  • api-no-private-access — Don't reach into _prefixed names from outside the module
  • api-instance-vs-module-fn — Pick the namespace that matches ownership

Code Simplification (simplify-)

  • simplify-early-return — Return early; don't nest the happy path
  • simplify-extract-after-duplication — Second copy is the decision point; third is the safe default
  • simplify-cached-property — @cached_property on immutable instances; not thread-safe
  • simplify-comprehensions — Comprehensions over for + .append()
  • simplify-any-all-builtins — any() / all() over manual flag + break
  • simplify-fallback-or — x or default when falsy values aren't semantic
  • simplify-flatten-nested-if — if cond1 and cond2: when no intervening code
  • simplify-inline-single-use-vars — Drop intermediates used once
  • simplify-remove-dead-code — Delete commented-out code; git preserves history

Performance (perf-)

  • perf-set-for-membership — set for repeated in checks
  • perf-dict-index-over-nested-loops — Build a dict for lookups
  • perf-lru-cache-pure-fns — functools.lru_cache / functools.cache on pure functions
  • perf-generator-over-list — Stream with generators when memory or latency matters
  • perf-combine-iterations — Fuse filter + map into one pass
  • perf-compile-regex-module-level — Compile static regex at module scope; matters in tight loops
  • perf-type-adapter-constant — Module-scope TypeAdapter (applicability: pydantic)
  • perf-isinstance-tuple-syntax — Tuple form is marginally faster; profiled hot paths only

Naming (naming-)

  • naming-rename-on-behavior-change — Rename when behavior changes; stale names mislead
  • naming-consistent-terminology — Same concept, same word across code/docs/errors
  • naming-specific-over-generic — toolset_id; not bare id
  • naming-drop-redundant-prefixes — ToolConfig.description; not ToolConfig.tool_description
  • naming-upper-case-constants — MAX_RETRIES; _ prefix for internal
  • naming-no-type-suffixes — No _dict / _list suffixes; types annotate types

Imports & Structure (imports-)

  • imports-no-side-effects — Modules must be cheap to import — no network/model/env reads at import
  • imports-top-of-file — Imports at the top; documented exceptions for circular / optional / deferred
  • imports-optional-dependencies — try / except ImportError with install hints
  • imports-scope-helpers-to-usage — Define helpers near where they're used
  • imports-remove-unused — Delete unused imports
  • imports-no-duplicates — One import per name
  • imports-lightweight-init — Parent __init__.py runs on every submodule import; keep heavy/optional deps out

How to Use

Read individual rule files for detail:

rules/data-mutable-defaults.md
rules/error-specific-exceptions.md

Each rule has:

  • Impact level in frontmatter
  • Brief explanation
  • Incorrect example
  • Correct example
  • Optional note on edge cases

For the full compiled guide with all rules expanded: AGENTS.md.

相关技能

设计创意

Automation Workflows

设计和实施自动化工作流程,以节省时间和规模化操作作为独家. 用于识别重复任务实现自动化,构建跨工具的工作流程,设置触发器和行动,或优化现有自动化. 包括自动化机会识别,工作流程设计,工具选择(Zapier,Make,n8n),测试,和维护. 触发"自动","自动","工作流程自动…

设计创意

Ui Ux Pro Max

UI/UX设计智能及建筑抛光接口实施指导. 当用户要求UI设计,UX流量,信息架构,视觉风格方向,设计系统/托盘,组件规格,副本/显微镜,可访问性,或生成/critique/refine前端UI(HTML/CSS/JS,React,Next.js,Vue,Svelte,Tailw…

设计创意

Frontend Design

创建美丽现代UI的专家前端设计指南. 在构建起落架页面,仪表板,或任何用户界面时使用.

设计创意

N8n Workflow Automation

设计和输出 n8n 工作流程 JSON 有强力触发器, idempotency, 错误处理, 记录, 重试, 以及 人入"一站"审查队列. 当您需要可审计的自动化时使用.