Community编程与开发github.com

sk-python

编写和调试Python代码时,特别关注那些会导致静默错误行为的陷阱——可变默认参数、闭包迟绑定、浅拷贝、静默异常,以及类型注解、环境和uv或venv打包、pytest测试结构。适用于编写Python脚本、服务或库、设置Python项目,或调试看似不可能的行为。

sk-python 是什么?

该技能旨在帮助开发者规避Python中容易出现的、导致静默错误的陷阱,并提供项目设置的最佳实践。它详细阐述了六个常见陷阱:可变默认参数、闭包迟绑定、身份与相等性混淆、浅拷贝、裸except和整数除法与浮点比较,每个陷阱都配有错误和正确代码示例。此外,它指导用户使用虚拟环境(venv或uv)隔离项目环境,通过pyproject.toml管理依赖和锁定文件,确保环境可重现。类型注解方面,强调注解函数签名边界,在CI中运行类型检查器(如mypy),并推荐使用X | None语法和DataClass等结构化类型。在测试上,推荐使用pytest和parametrize进行数据驱动测试,使用fixture管理共享状态,并断言特定异常。它还涵盖高性能编码习惯(如使用生成器、pathlib、enumerate/zip)以及性能优化方法(如使用内置函数、避免重复字符串拼接)。该技能适用于Claude Code、Cursor、Codex等AI代理工具,以及任何Python开发场景。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-python

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Python

Python 易于编写,但也容易在细微之处出错。本文涵盖那些导致静默错误的陷阱,以及如何正确设置项目以避免破坏环境。

造成静默错误的陷阱

可变默认参数 在定义时只会被求值一次,并在所有调用中共享:

def add(item, bucket=[]):   # 错误:bucket 会在多次调用间持续存在
def add(item, bucket=None): # 正确
    bucket = [] if bucket is None else bucket

闭包迟绑定。在循环中创建的 lambda 捕获的是变量本身,而不是它的值,因此所有 lambda 都看到最终的值。使用默认参数显式绑定,或者使用 functools.partial。

is 是身份比较,而非相等性比较。它只能用于 None、True 和 False,不能用于其他任何值。在小整数和短字符串上它似乎能正常工作,因为这些值是被驻留的,而正是这一点使得 bug 能够逃过测试。

拷贝是浅拷贝。list(xs)、xs[:] 和 dict(d) 只复制了容器,但共享了其中的元素。嵌套结构需要使用 copy.deepcopy。

裸 except: 会捕获所有异常,包括 KeyboardInterrupt 和 SystemExit。请捕获特定的异常,并且永远不要写 except Exception: pass —— 如果异常确实可以忽略,请记录日志并说明原因。

整数除法和浮点数相等性比较。/ 总是返回浮点数;// 向负无穷大取整,因此 -7 // 2 的结果是 -4。永远不要使用 == 比较浮点数;应使用 math.isclose,或者对于金额使用 Decimal。

在遍历集合时修改它 会跳过元素。请构建一个新列表,或者遍历集合的副本。

生成器只能被消费一次。第二次遍历同一个生成器不会产生任何元素,这会表现为空结果而非错误。

环境与打包

永远不要安装到系统解释器中。为每个项目创建一个虚拟环境并激活它,或者让 uv 来管理:

uv venv && uv pip install -e ".[dev]"     # 或者:python -m venv .venv

在 pyproject.toml 中声明依赖,并提交一个锁定文件,以确保环境是可重现的。带有未固定版本号的 requirements.txt 是不可重现的,并且在将来的机器上会失效。

固定项目支持的 Python 版本,并在 pyproject.toml 中明确说明。不同次要版本之间的行为差异比人们想象的要大。

当某个导入在一个地方成功而在另一个地方失败时,原因几乎总是出在解释器上,而不是代码本身。在调试导入问题之前,请检查 which python 和 python -c "import sys; print(sys.executable)"。

类型注解

对函数签名进行注解——包括参数和返回值。函数体内部很少需要注解;但边界处始终需要,因为其他代码依赖于此。

在 CI 中运行类型检查器。未经验证的注解会逐渐过时,变成误导性的文档。

使用 X | None 而不是约定俗成的可选参数,并且让可选性在签名中清晰可见。优先使用具体类型,而不是 Any;当类型确实未知时,请使用 unknown 的等价物——object——然后进行窄化,这样类型检查器会强制你进行窄化。

对于结构化数据,优先使用 dataclass,或者在数据从外部到来的边界处使用验证模型。在函数之间传递的字符串字典在遇到第一个拼写错误时就会失去所有保证。

重要的惯用法

当需要映射或过滤时使用推导式,当需要做其他事情时使用循环。包含副作用或三个子句的推导式比它替换掉的循环更难阅读。

使用 pathlib.Path 而不是字符串路径,并且对任何需要关闭的资源——文件、连接、锁、临时目录——都使用上下文管理器。

当输入很大或大小不确定时,从生成器中产出数据,而不是构建列表;这就是一个流式处理的脚本和一个耗尽内存的脚本之间的区别。

使用 enumerate、zip 和带默认值的 dict.get,而不是索引运算和成员检查。它们更快,并且消除了差一错误。

测试

使用 pytest,搭配普通的 assert。对于数据驱动的用例,使用 @pytest.mark.parametrize 而不是在一个测试内部使用循环,这样每个用例都能单独报告。

将共享的设置在所需范围内最小的 fixture 中。一个持有可变状态的会话级 fixture 会在测试之间泄漏,并产生依赖于执行顺序的失败。

使用 pytest.raises 断言特定的异常,当异常消息很重要时也要包含它。

性能(当它很重要时)

在优化之前先测量——使用 time.perf_counter 获取粗略数值,使用 cProfile 查看时间花在哪里。

通常的优化手段是将工作移出解释器:使用内置函数、推导式、用 str.join 替代重复的字符串拼接、使用 set 或 dict 查找替代遍历列表,或者对于数值计算使用向量化库函数。

对于 I/O 密集型并发,使用 asyncio 或线程;对于 CPU 密集型工作,使用进程,因为全局解释器锁意味着线程无法带来帮助。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

相关技能