PY-TYPE1001 · shared_typing_placement
Decide which reusable typing declarations belong in a shared module.
This is a contextual rule for python. Read its implementation.
Definition
Section titled “Definition”Group resolved aliases, Protocols, TypedDicts, and typing factories at their narrowest common
directory. Nominate declarations outside a preferred typing module only when the scope reaches
all three configured reuse floors. Decide to move only when the declaration is a low dependency
contract shared by that scope. Keep a declaration beside the runtime concept it describes.
Missing ownership or cycle evidence is uncertain.
minimum_definitions, minimum_imported_definitions, and minimum_cross_module_imports
define those floors. preferred_modules names destinations that already satisfy the policy.
Evidence
Section titled “Evidence”Every candidate carries its name, exact source range, current module, proposed destination, importing modules, and all scope reuse counts. One model turn answers for one declaration, so unrelated declarations cannot share a verdict.
Exceptions
Section titled “Exceptions”Scopes below any configured floor and declarations already in a preferred module never reach classification. Domain models, enums, dataclasses, and ordinary runtime classes are not typing declarations. A type stays with its owner when moving it would weaken cohesion or make a cycle.
Examples
Section titled “Examples”A generic parsing Protocol imported throughout one package can move to that package’s
typings.py. An alias describing the private state of one runtime class stays beside that
class even when annotations elsewhere mention it.
References
Section titled “References”- Cites “Python typing specification”, aliases and
NewType. Open reference - Cites “Python typing specification”, Protocols. Open reference
- Cites “Fluent Python”, chapter 13