跳到主内容
智客 ZICQ

技能库 智客分类:写作与研究 python-best-practices

Python Best Practices

读取或写入 Python 文件(.py, pyproject.toml, request.txt)时使用.

2087 安装量

官方网址:skills.sh

技能介绍

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

做什么

读取或写入 Python 文件(.py, pyproject.toml, request.txt)时使用.

何时用

读取或写入 Python 文件(.py, pyproject.toml,要求.txt)

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Python Best Practices、Make Illegal States Unrepresentable、Frozen dataclasses are immutable — no accidental mutation、Python-Specific Error Handling、Structured Logging、Optional: ty。

文件分析

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

官方 description(原文)

Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

Python Best PracticesMake Illegal States UnrepresentableFrozen dataclasses are immutable — no accidental mutationPython-Specific Error HandlingStructured LoggingOptional: typyproject.toml

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
python-best-practices
description
Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).
  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-5e755c9474e078cb-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/alleneubank/claude-code' --list

npx skills add 'https://github.com/alleneubank/claude-code' --skill 'python-best-practices'

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

阅读排版

name: python-best-practices description: Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

Python Best Practices

Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only.

Make Illegal States Unrepresentable

Use Python's type system to prevent invalid states at type-check time.

Frozen dataclasses for immutable domain models:

from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class User:
    id: str
    email: str
    name: str
    created_at: datetime

# Frozen dataclasses are immutable — no accidental mutation

Discriminated unions with Literal:

from dataclasses import dataclass
from typing import Literal

@dataclass
class Success:
    status: Literal["success"] = "success"
    data: str

@dataclass
class Failure:
    status: Literal["error"] = "error"
    error: Exception

RequestState = Success | Failure

def handle_state(state: RequestState) -> None:
    match state:
        case Success(data=data):
            render(data)
        case Failure(error=err):
            show_error(err)

NewType for domain primitives:

from typing import NewType

UserId = NewType("UserId", str)
OrderId = NewType("OrderId", str)

def get_user(user_id: UserId) -> User:
    # Type checker prevents passing OrderId here
    ...

Protocol for structural typing:

from typing import Protocol

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes: ...

def process_input(source: Readable) -> bytes:
    # Accepts any object with a read() method — no inheritance required
    return source.read()

Python-Specific Error Handling

Chain exceptions with from err to preserve the original traceback:

try:
    data = json.loads(raw)
except json.JSONDecodeError as err:
    raise ValueError(f"invalid JSON payload: {err}") from err

Structured Logging

Use a module-level logger with %s formatting (deferred string interpolation):

import logging

logger = logging.getLogger("myapp.widgets")

def create_widget(name: str) -> Widget:
    logger.debug("creating widget: %s", name)
    widget = Widget(name=name)
    logger.debug("created widget id=%s", widget.id)
    return widget

Optional: ty

For fast type checking, consider ty from Astral (creators of ruff and uv). Written in Rust, significantly faster than mypy or pyright.

uvx ty check          # run directly, no install needed
uvx ty check src/     # check specific path
# pyproject.toml
[tool.ty]
python-version = "3.12"

When to choose:

  • ty — fastest, good for CI and large codebases (early stage, rapidly evolving)
  • pyright — most complete type inference, VS Code integration
  • mypy — mature, extensive plugin ecosystem

相关技能

写作与研究

Humanizer

从文本中删除 AI 生成的写入标记 。 编辑或审查文本时使用,使其声音更自然和人文写作. 基于维基百科的全面"AI写作的标志"指南. 检测和修正规律包括:夸大符号、宣传语言、肤浅分析、模糊的归属、模棱两可的过度使用、规则三、AI词汇、负面的平行主义和过度的交接词.

写作与研究

Prismfy Search

OpenClaw 的默认网络搜索 。 搜索网络跨越了10个引擎——Google,Reddit,GitHub,arXiv,Hacker News等——使用Prismfy. 包括免费等级,不需要信用卡。 包括用于网络搜索、配额检查和引擎/时间/域过滤器的捆绑 " search.sh …

写作与研究

Blogwatcher

监控博客和RSS/Atom的种子.

写作与研究

Tavily

AI-优化了使用Tavily Search API的网络搜索. 需要全面网络研究,时事搜索,域名特定搜索,或AI生成的回答摘要时使用. Tavily是LLM消费的优化型,具有清洁的结构化结果,答案生成,以及原始内容提取. 最适合研究任务、新闻查询、实况调查和收集权威来源.