Question 1

How do I add missing type annotations to a Python class?

Accepted Answer

Declare attribute types at class level, such as name: str or _cache: dict[str, Any], then annotate __init__ parameters and add a -> None return type. This skill surveys each file first, then applies these annotations systematically.

Question 2

When should I use Pydantic BaseModel vs TypedDict for structured dicts?

Accepted Answer

Prefer BaseModel when the dict crosses a system boundary such as an API, config file, or serialization layer, since it adds runtime validation. Prefer TypedDict for internal data structures that are never validated or serialized.

Question 3

How do I type a function that returns str or bytes depending on a flag?

Accepted Answer

Use @overload with Literal types: one overload for as_bytes: Literal[False] returning str, another for Literal[True] returning bytes, followed by the implementation signature with the union return type.

Question 4

Does tightening type annotations change runtime behavior?

Accepted Answer

Pure annotations do not, but converting a dict to a Pydantic model does change runtime behavior and can break public API compatibility. The skill flags these cases and asks before making breaking changes.

Question 5

How do I avoid circular imports when adding type annotations?

Accepted Answer

Use from __future__ import annotations combined with a TYPE_CHECKING guard block for imports only needed by the type checker. This keeps third-party types like spacy's Language available for checking without runtime import cycles.

python-tighten-types

SYSTEM DOCUMENTATION & REQUIREMENTS

Frequently Asked Questions about python-tighten-types

Related Skills

python-type-safety

0159-python-type-safety

lint-and-validate

abf