Type hints, and what they do not do

Python has type hints. They look like TypeScript, they read like TypeScript, and the thing they promise is meaningfully weaker. Being precise about how weaker is the point of this lesson, because the gap is where the bugs live.

The syntax, which will feel like home

def retry(url: str, attempts: int = 3, backoff: float = 1.5) -> bool:
    ...

names: list[str] = []
config: dict[str, int] = {}
pair: tuple[str, int] = ("a", 1)
maybe: str | None = None
handler: Callable[[str], None] = print

Generics use the built-in names directly (list[str], dict[str, int]), which is modern style since 3.9. Older code imports List and Dict from typing and means exactly the same thing; you will read plenty of it and you should not write any more of it.

Unions use | since 3.10. Optional[X] is X | None and Union[A, B] is A | B, both spelled the old way.

The thing that is different, stated precisely

Annotations are recorded and then ignored. The interpreter stores them in __annotations__ and does nothing else with them. No check, no coercion, no warning.

def double(n: int) -> int:
    return n * 2

double("ha")     # 'haha'

Now, TypeScript’s types are also erased at runtime, so the naive comparison says these are the same situation. They are not, and the difference is in the pipeline rather than in the type system.

TypeScript’s compiler is a required step. To get JavaScript out, you run tsc, and code that does not typecheck does not normally ship. The type system is not enforced at runtime, but it is enforced at build time, and there is a build.

Python has no required step. The checker is an external tool you may or may not have installed, may or may not run, and may or may not have wired into CI. So the honest question about a Python codebase is never “is it typed”, it is “is a checker run, and does it pass”. A repo full of beautiful annotations that nobody checks has documentation. Good documentation, worth having, but not a guarantee.

Any is any. object is unknown.

def loose(x: Any) -> None:
    x.whatever().at_all()      # fine. Checking is off for x.

def strict(x: object) -> None:
    x.whatever()               # ERROR. object has no such attribute.
    if isinstance(x, Sender):
        x.whatever()           # fine. Narrowed.

Same advice as TypeScript: prefer the one that forces you to narrow. Any is the escape hatch and every use of it is a small hole. object is the honest top type.

Narrowing works the way you expect. isinstance checks, is None checks, and truthiness checks all narrow, and both major checkers understand them.

Type aliases and generics

type UserId = str                          # a type alias, PEP 695
type Handler = Callable[[str], None]

def first[T](items: list[T]) -> T | None:  # a generic function
    return items[0] if items else None

class Box[T]:                              # a generic class
    def __init__(self, value: T) -> None:
        self.value = value

That syntax is new and clean. Code written before 3.12 uses TypeVar explicitly and a TypeAlias annotation, which is noisier and means the same thing:

from typing import TypeVar, TypeAlias

UserId: TypeAlias = str
T = TypeVar("T")

def first(items: list[T]) -> T | None: ...

Both are current in the sense that both work. The old one dominates existing code because most libraries still support older Python versions.

Literal, Final, and the small useful ones

from typing import Literal, Final, TypedDict, NoReturn

Mode = Literal["fast", "careful"]     # a string-literal union. Same idea as TS.
MAX: Final = 10                       # a constant. The checker enforces it; nothing else does.
def die(msg: str) -> NoReturn: ...    # this function never returns normally

Literal is the one you will use most, because it is how a library says this argument is one of these four strings without inventing an enum.

Annotations at runtime, which matters more than you would expect

Some libraries genuinely read annotations at runtime and build behaviour from them. Pydantic does, and so does every framework that derives a schema from a function signature, which in your near future means LangChain tool definitions and FastAPI route handlers.

This used to be fragile. Annotations were evaluated eagerly at definition time, so a forward reference to a class defined later in the file had to be written as a string. from __future__ import annotations (PEP 563) fixed that by making all annotations strings, which fixed forward references and broke every library that wanted the actual objects.

Python 3.14 resolves it properly with PEP 649: annotations are now evaluated lazily, on demand, via annotationlib. Forward references work without quoting, and libraries that need the real values can still get them.

What to actually do

1. Annotate every function signature. Parameters and return. Local variables mostly infer fine and annotating them is noise.
2. Run a checker in CI, or accept that your annotations are comments. uv add --dev pyright and one CI line.
3. Treat Any as a hole you are choosing, the same way you treat any.
4. Check whether a dependency ships types before being surprised that nothing is checked downstream of it.

Where this goes

Annotations describe shapes. The next lesson is the three ways Python actually builds a structured shape, which is where your interface reflex needs redirecting: TypedDict, dataclass, and Protocol. All three are the same idea wearing very different clothes, and picking the wrong one is the most common structural mistake a TypeScript developer makes here.