mcpField
F
fix-types

fix-types

github.com/saaspegasus开发32282 次安装12 周前更新
代码仓库

关于 fix-types

一项指导 Python 项目修复 mypy 类型错误的开发技能。它要求先分组错误，再逐项提出修复方案并等待确认，同时强调清晰的类型转换和运行时错误处理。

主要功能

  1. 01运行 mypy 检查类型错误
  2. 02将错误归纳分组
  3. 03逐项征求修复确认
  4. 04优先使用 cast()
  5. 05为必要的 type: ignore 添加说明
  6. 06处理 Django 延迟翻译字符串类型

适用场景

  1. 01按步骤修复项目中的 mypy 错误
  2. 02在修改前审核每项类型修复方案
  3. 03为 Django 延迟翻译字符串添加类型注解

安装

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

$npx skills add https://github.com/saaspegasus/django-skills --skill fix-types

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

详细介绍

您的任务

要修复类型问题，请执行以下操作。

  1. 首先运行类型检查器，查看有哪些问题： 
    uv run mypy .
  2. 将发现的错误归类到逻辑分组中。
  3. 对于每组错误，逐一检查错误，告诉我您想采用的修复方案，然后询问我在继续之前是否有任何问题或建议。
  4. 只有在我批准后，才应用修复并继续处理该组中的下一个错误。
  5. 完成一组错误后，询问我是否要继续处理下一组。
优先使用 cast()，而不是 type: ignore

当 mypy 无法推断出正确类型时，优先使用 cast()，而不是 # type: ignore：

# Preferred - documents the expected type
choices = cast(list[tuple[str, str]], field.choices)

# Avoid when cast is possible - just silences the error
choices = list(field.choices)  # type: ignore[arg-type]

原因： cast() 会明确说明您期望的类型，让代码更易读、更易维护。它也不会屏蔽同一行上的其他潜在错误。

检查空值时，优先使用恰当的错误，而不是断言

添加空值检查以满足 mypy 要求时，优先抛出恰当的异常，而不是使用 assert：

# Preferred - proper error handling
if obj.related_field is None:
    raise ValueError("Object must have a related field")
result = obj.related_field.some_method()

# Avoid - assertions can be disabled with -O flag
assert obj.related_field is not None
result = obj.related_field.some_method()

原因： 在生产环境中，python -O 可以禁用断言，因此断言不能可靠地用于运行时验证。恰当的异常可确保检查始终执行，并提供更好的错误处理。

使用 type: ignore 时，添加注释

如果必须使用 type: ignore（例如，mypy 对有效代码的限制），请务必添加简短说明：

# Good - explains why the ignore is needed
self.tier = tier  # type: ignore[misc]  # mypy can't handle Enum tuple values with custom __init__

# Bad - no explanation
self.tier = tier  # type: ignore[misc]
Django 惰性翻译字符串的类型提示

对 Django 的惰性翻译字符串（gettext_lazy）使用类型提示时，请采用以下模式，以避免 mypy 报错，同时确保代码在生产环境中正常运行（生产环境不会安装 django-stubs-ext）：

from __future__ import annotations  # Must be the first import

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from django_stubs_ext import StrOrPromise


# Then use StrOrPromise in type hints
def my_function(name: StrOrPromise) -> StrOrPromise: ...


class MyData:
    title: StrOrPromise
    description: StrOrPromise

采用此模式的原因：

  • from __future__ import annotations 会让类型注解在运行时成为字符串（而非进行求值）
  • if TYPE_CHECKING: 可确保该导入只在类型检查期间执行，而不会在运行时执行
  • django-stubs-ext 是开发依赖项，生产环境中不会提供
  • 此模式允许接受普通字符串和惰性翻译字符串

评论

支持 Markdown