mcpField
W
writing-python

writing-python

github.com/julianobarbosa开发14132 次安装2 天前更新
代码仓库

关于 writing-python

writing-python 是面向 Python 开发的 Agent 技能，适合编写、测试和维护 Python 项目的开发者。它提供类型标注、标准库优先等规范，并围绕 uv、ruff、pytest 和 mypy 给出工具链建议。

主要功能

  1. 01强调标准库优先与明确错误处理
  2. 02要求函数和参数使用类型标注
  3. 03提供数据类与模式匹配示例
  4. 04推荐 uv、ruff、pytest 和 mypy
  5. 05涵盖代码风格与类型安全参考

适用场景

  1. 01为 Python 函数补充类型标注
  2. 02配置项目的格式检查与类型检查
  3. 03编写 pytest 测试并运行检查
  4. 04查阅异步依赖与注解相关注意事项

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill writing-python

安装后在 Claude Code 中输入/writing-python确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

CLI.md
PATTERNS.md
TESTING.md
References/
code-style.md
type-safety.md

详细介绍

Python 开发（3.14+）

核心原则

  • 标准库优先：只有在确有必要时才使用外部依赖
  • 处处添加类型提示：所有函数、所有参数都要添加
  • 显式优于隐式：清晰胜过巧妙
  • 尽早失败：尽早抛出信息明确的错误

工具链

uv           # Package management (not pip/poetry)
ruff         # Lint + format (not flake8/black)
pytest       # Testing
mypy         # Type checking

快速模式

类型提示
def process_users(users: list[User], limit: int | None = None) -> list[Result]:
    ...

async def fetch_data(url: str, timeout: float = 30.0) -> dict[str, Any]:
    ...
数据类
from dataclasses import dataclass, field

@dataclass
class Config:
    host: str
    port: int = 8080
    tags: list[str] = field(default_factory=list)
模式匹配
match event:
    case {"type": "click", "x": x, "y": y}:
        handle_click(x, y)
    case {"type": "key", "code": code}:
        handle_key(code)
    case _:
        raise ValueError(f"Unknown event: {event}")

Python 3.14 特性

  • 延迟注解：不再需要 from __future__ import annotations
  • 模板字符串（t""）：t"Hello {name}" 会返回 Template 对象
  • except 无需括号：except ValueError, TypeError:
  • concurrent.interpreters：通过子解释器实现真正的并行
  • compression.zstd：标准库内置 Zstandard
  • 自由线程构建：无 GIL（选择启用）

参考资料

工具

uv sync                    # Install deps
ruff check --fix .         # Lint and autofix
ruff format .              # Format
pytest -v                  # Test
mypy .                     # Type check

已合并的子技能（整合后）

此技能现已涵盖原有的 python-code-style 和 python-type-safety 技能。其原始 SKILL.md 内容作为深度参考予以保留：

主题路径
ruff、mypy、命名、导入、文档字符串（Google 风格）References/code-style.md
类型注解、泛型、协议、严格检查模式References/type-safety.md

有关系统可靠性（后台任务、重试、可观测性），请参阅同级的 python-infrastructure 技能。有关依赖管理和项目脚手架，请参阅 uv。

注意事项

  • from __future__ import annotations 会将所有注解转换为字符串 — 运行时内省（typing.get_type_hints）需要实际类型可用；对局部作用域类的前向引用会失败。
  • f 字符串调试语法（f"{var=}"）需要 3.8+ — 在 3.7 及更早版本中会静默失败（将 = 视为字面字符）。
  • dataclass(slots=True) 需要 3.10+ — 在 3.9 中会静默失效。若要保持可移植性，请手动使用 __slots__。
  • PEP 604 联合类型语法（int | None）在运行时需要 3.10+ — 在 3.9 中配合 from __future__ import annotations 可作为字符串注解使用，但在运行时内省时会失败。
  • FastAPI 依赖项中的 async def 与 def：异步依赖项在事件循环中运行；同步依赖项在线程池中运行。未经考虑地混用会导致阻塞或额外的上下文切换开销。

评论

支持 Markdown