python-types-contracts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Types and Contracts

Python类型与契约

Overview

概述

Treat type hints as interface design, not decoration. Focus on explicit contracts, stable public APIs, and boundary-safe modeling.

These are preferred defaults for common cases, not universal rules. When a default conflicts with project constraints, suggest a better-fit alternative and explain tradeoffs and compensating controls.

将类型提示视为接口设计，而非装饰性内容。专注于明确的契约、稳定的公共API以及边界安全的建模。

这些是针对常见场景的推荐默认方案，而非通用规则。当默认方案与项目约束冲突时，建议更合适的替代方案，并解释权衡利弊和补偿控制措施。

When to Use

适用场景

Public API signatures lack type annotations or use overly broad types.
Pydantic models are scattered throughout internal logic instead of at trust boundaries.
Contract changes risk breaking downstream consumers without migration paths.
Interfaces accept
```
Any
```
,
```
object
```
, or untyped dicts where narrower types apply.
Schema boundaries between layers (API, DB, domain) are implicit or inconsistent.
Adding or evolving protocols, abstract base classes, or structural subtyping.

When NOT to use:

Pure implementation-level code with no public interface.
Throwaway scripts or one-off data munging where type rigor adds no value.
Performance-critical inner loops where typing overhead matters more than safety.

公共API签名缺少类型注解或使用过于宽泛的类型。
Pydantic模型分散在内部逻辑各处，而非仅用于信任边界。
契约变更可能在无迁移路径的情况下破坏下游消费者。
接口在应使用更窄类型的情况下接受
```
Any
```
、
```
object
```
或无类型字典。
各层（API、数据库、领域）之间的Schema边界不明确或不一致。
添加或演进协议、抽象基类或结构子类型。

不适用场景：

无公共接口的纯实现级代码。
一次性脚本或临时数据处理任务，类型严谨性无法带来价值。
性能关键的内部循环，类型检查的开销比安全性更重要。

Quick Reference

快速参考

Type public APIs and keep contracts explicit.
Prefer narrow interfaces and boundary protocols over broad parameter types.
Use pydantic at trust boundaries by default, not everywhere.
Make compatibility and migration impact explicit for any contract change.
Favor
```
Protocol
```
for structural subtyping over deep inheritance hierarchies.
Return concrete types from public functions; accept protocols or unions as inputs.

为公共API添加类型注解，保持契约明确。
优先选择窄接口和边界协议，而非宽泛的参数类型。
默认仅在信任边界使用Pydantic，而非随处使用。
对于任何契约变更，明确说明兼容性和迁移影响。
优先使用
```
Protocol
```
实现结构子类型，而非深层继承层次结构。
公共函数返回具体类型；接受协议或联合类型作为输入。

Common Mistakes

常见错误

Typing everything identically. Internal helpers don't need the same rigor as public APIs. Over-annotating private code adds noise without safety.
Pydantic everywhere. Using pydantic models for internal data flow instead of reserving them for validation at trust boundaries (API ingress, config loading, external data).
Broad return types. Returning
```
Any
```
or
```
dict
```
from public functions forces callers to guess structure. Return concrete types or TypedDicts.
Breaking contracts silently. Changing function signatures, removing fields, or narrowing accepted types without versioning, deprecation warnings, or migration notes.
Ignoring
None
. Omitting
```
Optional
```
or union with
```
None
```
when a value can legitimately be absent, hiding null-safety bugs until runtime.

统一为所有代码添加类型注解 内部辅助函数无需像公共API那样严格。过度为私有代码添加注解会增加冗余，却无法提升安全性。
随处使用Pydantic 将Pydantic模型用于内部数据流，而非仅保留在信任边界（API入口、配置加载、外部数据）进行验证。
宽泛的返回类型 公共函数返回
```
Any
```
或
```
dict
```
会迫使调用者猜测结构。应返回具体类型或TypedDicts。
静默破坏契约 在未进行版本控制、未发出弃用警告或未提供迁移说明的情况下，修改函数签名、移除字段或缩小接受的类型范围。
忽略
None
类型当值可能合法缺失时，省略
```
Optional
```
或与
```
None
```
的联合类型，会将空安全漏洞隐藏到运行时才暴露。

Scope Note

范围说明

Treat these recommendations as preferred defaults for common cases, not universal rules.
If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

将这些建议视为针对常见场景的推荐默认方案，而非通用规则。
当默认方案与项目约束冲突或导致结果恶化时，建议更合适的替代方案，并解释为何该方案更适合此场景。
当偏离默认方案时，说明权衡利弊和补偿控制措施（测试、可观测性、迁移、回滚）。

Invocation Notice

调用说明

Inform the user when this skill is being invoked by name:
```
python-design-modularity
```
.

当调用此技能时，需告知用户技能名称：
```
python-design-modularity
```
。

References

参考资料

```
references/typing-policy.md
```
```
references/contract-evolution.md
```
```
references/pydantic-boundaries.md
```

```
references/typing-policy.md
```
```
references/contract-evolution.md
```
```
references/pydantic-boundaries.md
```