do-not-widen-types-to-silence-the-checker
Когда проверка типов отвергает вызов или возвращаемое значение, сужайте значение или обрабатывайте отсутствующий случай, а не расширяйте аннотацию до Any, object или непроверенного объединения.
Присвоено человеком, который прочитал карточку, а не заявлено файлом о самом себе. Карточка, которую агент выводит во время запуска, поглотившего недоверенное содержимое, рождается заражённой и удерживается на разбор, прежде чем её вообще извлекут.
Когда это вспоминается
- ошибка анализатора типов в аргументе или возвращаемом значении
- соблазн добавить Any или cast, чтобы пройти mypy или pyright
- объединение включает None, а вызывающий код ожидает конкретный тип
- расширение сигнатуры только ради одного места вызова
Ценность обычно лежит в разделах «Избегать» и «Проверить». «Делать» — это раздел, который пишут все.
Текст карточки выше — перевод. Английский оригинал — это то, что импортирует командная строка, что читает агент во время работы и что подтверждает хеш ниже.
Повод
Статический анализатор типов (mypy, pyright, tsc, cargo check) сообщает о несовместимом типе, например когда передаётся str | None там, где требуется str, или возвращается объединение шире объявленной сигнатуры. Самый быстрый способ убрать диагностику это расширить аннотацию параметра или возвращаемого значения (Any, object, unknown, # type: ignore, или добавить | None в интерфейс, который никогда не должен был это принимать).
Делать
- Поймите, что на самом деле доказывает анализатор: какая ветка может дать неожиданный тип и достижима ли она во время выполнения. 2. Если более широкое значение это ошибка или необработанный граничный случай в месте вызова, сузьте его до вызова: проверьте
None, валидируйте вход на границе или сразу выбросьте понятную ошибку. 3. Если функция действительно поддерживает более широкий тип, обновите её реализацию так, чтобы обрабатывался каждый член этого типа, прежде чем расширять сигнатуру. 4. Держите границу узкой: разбирайте или уточняйте нетипизированные данные (dict[str, Any], сырой JSON) один раз, на входе в модуль, а не протаскивайте широкие типы внутрь.
Избегать
Относиться к анализатору типов как к препятствию, которое нужно умиротворить, а не как к доказательству того, что ветка не обработана. Классическая ошибка это изменить def load_user(user_id: str) -> User, чтобы принимать str | None или возвращать User | Any, потому что один вызывающий код забыл проверить наличие user_id. Анализатор сразу зеленеет, необработанный None превращается из статической ошибки на границе в AttributeError во время выполнения тремя уровнями глубже, и каждый последующий вызывающий либо наследует более широкое объединение, либо полностью теряет проверку. Не менее плохо ставить cast(...) или # type: ignore на строку без инварианта в непосредственно предшествующем коде, который делает cast истинным.
Проверить
Запустите анализатор типов на изменённом модуле и просмотрите diff каждой изменённой сигнатуры. Каждый вновь расширенный параметр или возвращаемый тип имеет явную ветку или тест, покрывающий добавленный случай. Не добавлены Any, cast или # type: ignore только для того, чтобы заглушить несоответствие, которое можно было решить сужением на границе. Последующим вызывающим не пришлось добавлять защитные проверки для типа, который производителю никогда не нужно было выдавать.
Риск
Иногда заглушка библиотеки действительно неверна или неполна, а внешние данные действительно произвольны, пока их не проверит более поздний этап. В таких случаях локальный, задокументированный # type: ignore[code] или узкий адаптер на границе лучше, чем искажение рабочего кода мёртвыми ветками ради удовлетворения сломанной заглушки.
Как применить
Карточка — это данные. Склонируйте репозиторий и импортируйте её по пути: всё, что приходит по сети, считается заражённым и удерживается до одобрения — это и есть желаемое поведение, и поэтому здесь нет установщика в одну строку.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/do-not-widen-types-to-silence-the-checker/SKILL.mdЦелостность
SHA-256 файла в опубликованном виде. Импортёр может проверить, что полученное совпадает с показанным на этой странице.
9fdad16332fb728bb73f495c19effaeab028d4160a220ad94a8ff0ab8996a5b9