Back to Details

dignified-python

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dignified Python Coding Standards

高标准Python编码规范

Core Knowledge (ALWAYS Loaded)

核心知识（始终加载）

@dignified-python-core.md
@dignified-python-core.md

Version Detection

版本检测

Identify the project's minimum Python version by checking (in order):
  1. pyproject.toml
    - Look for 
    requires-python
    field (e.g., 
    requires-python = ">=3.12"
    )
  2. setup.py
    or 
    setup.cfg
    - Look for 
    python_requires
  3. .python-version
    file - Contains version like 
    3.12
    or 
    3.12.0
  4. Default to Python 3.12 if no version specifier found
Once identified, load the appropriate version-specific file:
  • Python 3.10: Load 
    versions/python-3.10.md
  • Python 3.11: Load 
    versions/python-3.11.md
  • Python 3.12: Load 
    versions/python-3.12.md
  • Python 3.13: Load 
    versions/python-3.13.md
按以下顺序检查，确定项目的最低Python版本：
  1. pyproject.toml
    - 查找
    requires-python
    字段（例如
    requires-python = ">=3.12"
    ）
  2. setup.py
    或
    setup.cfg
    - 查找
    python_requires
  3. .python-version
    文件 - 包含类似
    3.12
    或
    3.12.0
    的版本号
  4. 若未找到版本说明，默认使用Python 3.12
确定版本后，加载对应的版本专属文件：
  • Python 3.10: 加载
    versions/python-3.10.md
  • Python 3.11: 加载
    versions/python-3.11.md
  • Python 3.12: 加载
    versions/python-3.12.md
  • Python 3.13: 加载
    versions/python-3.13.md

Conditional Loading (Load Based on Task Patterns)

条件加载（根据任务模式加载）

Core files above cover 80%+ of Python code patterns. Only load these additional files when you detect specific patterns:
Pattern detection examples:
  • If task mentions "click" or "CLI" -> Load 
    cli-patterns.md
  • If task mentions "subprocess" -> Load 
    subprocess.md
上述核心文件覆盖了80%以上的Python代码场景。仅当检测到特定模式时才加载以下额外文件：
模式检测示例：
  • 若任务提及"click"或"CLI" -> 加载
    cli-patterns.md
  • 若任务提及"subprocess" -> 加载
    subprocess.md

When to Read Each Reference Document

各参考文档的适用场景

The 
references/
directory contains detailed guidance for specialized topics. Load these on-demand when you encounter relevant patterns:
references/
目录包含专业主题的详细指引。当你遇到相关场景时按需加载：

references/exception-handling.md

references/exception-handling.md

Read when:
  • Writing try/except blocks
  • Wrapping third-party APIs that may raise
  • Seeing or writing 
    from e
    or 
    from None
  • Unsure if LBYL alternative exists
适用场景：
  • 编写try/except代码块
  • 封装可能抛出异常的第三方API
  • 遇到或编写
    from e
    或
    from None
    代码
  • 不确定是否存在LBYL替代方案时

references/interfaces.md

references/interfaces.md

Read when:
  • Creating ABC or Protocol classes
  • Writing @abstractmethod decorators
  • Designing gateway layer interfaces
  • Choosing between ABC and Protocol
适用场景：
  • 创建ABC或Protocol类
  • 编写@abstractmethod装饰器
  • 设计网关层接口
  • 需要在ABC和Protocol之间做选择时

references/typing-advanced.md

references/typing-advanced.md

Read when:
  • Using typing.cast()
  • Creating Literal type aliases
  • Narrowing types in conditional blocks
适用场景：
  • 使用typing.cast()时
  • 创建Literal类型别名时
  • 在条件代码块中做类型收窄时

references/module-design.md

references/module-design.md

Read when:
  • Creating new Python modules
  • Adding module-level code (beyond simple constants)
  • Using @cache decorator at module level
  • Seeing Path() or computation at module level
  • Considering inline imports
适用场景：
  • 创建新的Python模块时
  • 添加模块级代码（简单常量之外的内容）时
  • 在模块级别使用@cache装饰器时
  • 遇到模块级的Path()调用或计算逻辑时
  • 考虑使用内联导入时

references/api-design.md

references/api-design.md

Read when:
  • Adding default parameter values to functions
  • Defining functions with 5 or more parameters
  • Using ThreadPoolExecutor.submit()
  • Reviewing function signatures
适用场景：
  • 为函数添加默认参数值时
  • 定义参数数量≥5的函数时
  • 使用ThreadPoolExecutor.submit()时
  • 评审函数签名时

references/checklists.md

references/checklists.md

Read when:
  • Final review before committing Python code
  • Unsure if you've followed all rules
  • Need a quick lookup of requirements
适用场景：
  • 提交Python代码前的最终评审
  • 不确定是否遵守了所有规则时
  • 需要快速查询规范要求时

How to Use This Skill

如何使用本规范

  1. Core knowledge is loaded automatically (LBYL, pathlib, basic imports, anti-patterns)
  2. Version detection happens once - identify the minimum Python version and load the appropriate version file
  3. Reference documents are loaded on-demand based on the triggers above
  4. Additional patterns may require extra loading (CLI patterns, subprocess)
  5. Each file is self-contained with complete guidance for its domain
  1. 核心知识自动加载（LBYL、pathlib、基础导入、反模式）
  2. 版本检测仅执行一次：确定最低Python版本并加载对应版本文件
  3. 参考文档根据上述触发条件按需加载
  4. 特殊场景可能需要额外加载（CLI模式、subprocess）
  5. 每个文件都自包含，对应领域的指引完整独立