{"title":"Type Hints Basics","description":"","content":"Type hints let you annotate variables, function parameters, and return values with the types they're expected to hold. They don't change how Python runs your code, but they give your editor, type checkers, and teammates a way to catch bugs before the program ever executes. This lesson covers what type hints are, the syntax for basic annotations, why Python ignores them at runtime, and how to inspect them programmatically.\n\n---\n\n# Why Type Hints Exist\n\nPython is dynamically typed. A variable can hold a string today and a list tomorrow, and the interpreter won't complain until something blows up at runtime. That flexibility is great for quick scripts and prototypes. It's painful when a six-month-old function silently accepts the wrong shape of data and corrupts an order.\n\nType hints were standardized in PEP 484, shipped with Python 3.5 in 2015. The pitch was simple: let developers write down the types they intend, and let external tools (editors, linters, type checkers like `mypy`) read those annotations and flag mismatches. The interpreter itself stays out of it.\n\nSo when you write a function that computes a cart total, you can say \"this takes a list of floats and returns a float\" in the function signature itself. Your IDE then autocompletes accurately, your reviewer reads the contract without scrolling, and a type checker run in CI catches the moment somebody passes a list of strings by mistake.\n\n\n```python\ndef cart_total(prices: list[float]) -> float:\n return sum(prices)\n\nprint(cart_total([29.99, 14.99, 9.99]))\n```\n\n\nThe `: list[float]` after `prices` and the `-> float` after the parenthesis are the type hints. The function body is unchanged. Without the hints, this is exactly the same code; with them, your editor knows `prices` supports `sum()` and that the return value is a `float`.\n\nThe diagram below shows where type hints sit in the development loop. The Python interpreter ignores them; everything useful happens in the gray box on the left.\n\n\n```mermaid\nflowchart LR\n SRC[Source code with
type hints]:::cyan --> CHECK[Type checker
mypy / pyright]:::orange\n SRC --> IDE[IDE / Editor
autocomplete, hover]:::orange\n CHECK --> DEV[Developer
fixes type bugs]:::green\n IDE --> DEV\n SRC --> PY[Python interpreter
ignores annotations]:::teal\n PY --> RUN[Program runs]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe interpreter parses annotations (it has to, they're part of the grammar) but never enforces them. Type checking is a separate, opt-in step that you run before the code ships.\n\n---\n\n# Annotating Variables\n\nThe syntax for a variable annotation is `name: type = value`. The colon attaches a type to the name; the rest is a normal assignment.\n\n\n```python\ncustomer_name: str = \"Alice\"\nprice: float = 19.99\nquantity: int = 3\nin_stock: bool = True\n\nprint(customer_name, price, quantity, in_stock)\n```\n\n\nYou can also annotate a variable without assigning a value, which is useful when the assignment happens later, for example inside an `if` branch or in a class body:\n\n\n```python\ndiscount: float\nif quantity >= 5:\n discount = 0.10\nelse:\n discount = 0.0\n\nprint(discount)\n```\n\n\nThe bare `discount: float` line doesn't create a variable at runtime. It only records the intended type. If you try to read `discount` before assigning it, you'll get a regular `NameError`, the same as any unassigned name.\n\nAnnotations work on any assignment target Python allows, but they only attach to a single name at a time. Multiple assignment doesn't support annotations:\n\n\n```python\n# This is fine\na: int = 1\nb: int = 2\n\n# This is a SyntaxError\n# a: int, b: int = 1, 2\n```\n\n\nFor container types, the hint should describe what's inside the container, not just the container itself. A bare `list` is legal but uninformative; `list[str]` says \"a list of strings\" and lets the type checker catch the moment you append an `int`:\n\n\n```python\nproduct_names: list[str] = [\"Wireless Mouse\", \"USB Cable\", \"Charger\"]\ncart_quantities: dict[str, int] = {\"Wireless Mouse\": 1, \"USB Cable\": 2}\nshipping_address: tuple[str, str, int] = (\"123 Main St\", \"Springfield\", 62701)\ntags: set[str] = {\"electronics\", \"wireless\", \"bestseller\"}\n\nprint(product_names)\nprint(cart_quantities)\nprint(shipping_address)\nprint(tags)\n```\n\n\nThe next section covers built-in generic syntax in more depth, including the difference between `list[int]` and the older `List[int]` from the `typing` module.\n\n---\n\n# Annotating Function Parameters and Returns\n\nFunction annotations follow the same `name: type` pattern for each parameter, plus an arrow `->` followed by the return type before the colon.\n\n\n```python\ndef calculate_total(price: float, quantity: int) -> float:\n return price * quantity\n\nresult = calculate_total(19.99, 3)\nprint(f\"Total: ${result:.2f}\")\n```\n\n\nA function that doesn't return anything (or only uses a bare `return`) should be annotated `-> None`. This isn't decorative; type checkers use it to flag code that mistakenly tries to use the return value:\n\n\n```python\ndef log_order(order_id: int, customer: str) -> None:\n print(f\"Order {order_id} placed by {customer}\")\n\nlog_order(101, \"Alice\")\n```\n\n\nDefault values come after the type, in the usual position. The annotation describes the parameter type; the default is the value used when the caller omits the argument:\n\n\n```python\ndef apply_discount(price: float, percent: float = 10.0) -> float:\n return price * (1 - percent / 100)\n\nprint(apply_discount(50.0))\nprint(apply_discount(50.0, 25.0))\n```\n\n\nFor functions that can return more than one type, you'll typically reach for `Union` or the `|` operator. For now, the basic case is enough: a function either always returns one type, or returns `None` when it has no useful value to give back.\n\nAnnotations work on methods exactly the same way. The `self` parameter is conventionally left unannotated because the type checker infers it from the enclosing class:\n\n\n```python\nclass ShoppingCart:\n def __init__(self, customer: str) -> None:\n self.customer: str = customer\n self.items: list[str] = []\n\n def add_item(self, product: str) -> None:\n self.items.append(product)\n\n def item_count(self) -> int:\n return len(self.items)\n\ncart = ShoppingCart(\"Alice\")\ncart.add_item(\"Wireless Mouse\")\ncart.add_item(\"HDMI Cable\")\nprint(f\"{cart.customer} has {cart.item_count()} items\")\n```\n\n\nThe `self.customer: str = customer` and `self.items: list[str] = []` are instance variable annotations. They tell the type checker the shape of an instance, which is what powers the autocomplete you see when you type `cart.` in an editor.\n\n---\n\n# Built-in Generic Types\n\nContainer hints describe both the container and the type of its elements. Since Python 3.9 (PEP 585), the built-in container types support subscript syntax directly:\n\n\n| Hint | Meaning |\n| ---- | ------- |\n| `list[int]` | A list of integers |\n| `list[str]` | A list of strings |\n| `dict[str, float]` | A dict mapping strings to floats |\n| `tuple[str, int]` | A two-element tuple: string then int |\n| `tuple[int, ...]` | A tuple of any number of ints |\n| `set[str]` | A set of strings |\n| `frozenset[int]` | A frozen set of integers |\n\n\nEach of these can appear anywhere a type hint can go: variable annotations, parameter annotations, return annotations.\n\n\n```python\ndef average_rating(ratings: list[float]) -> float:\n return sum(ratings) / len(ratings)\n\ndef stock_summary(stock: dict[str, int]) -> str:\n in_stock = [name for name, qty in stock.items() if qty > 0]\n return f\"{len(in_stock)} products in stock\"\n\nratings = [4.5, 4.1, 3.8, 4.6, 4.7]\nstock = {\"Wireless Mouse\": 12, \"USB Cable\": 0, \"Charger\": 20}\n\nprint(f\"Average rating: {average_rating(ratings):.2f}\")\nprint(stock_summary(stock))\n```\n\n\nTuples have two distinct shapes. A fixed-length tuple lists each position's type:\n\n\n```python\nshipping_address: tuple[str, str, str, int] = (\"123 Main St\", \"Apt 5\", \"Springfield\", 62701)\n```\n\n\nA variable-length tuple of homogeneous elements uses `...`:\n\n\n```python\nproduct_ids: tuple[int, ...] = (101, 204, 318, 425)\n```\n\n\n`tuple[int, ...]` says \"a tuple of any number of ints, possibly empty\". `tuple[int]` (without the ellipsis) says \"a one-element tuple containing exactly one int\". The distinction matters because tuples in Python carry length information in their type.\n\nNesting works the way you'd expect. A list of carts, where each cart is a list of `(product, quantity)` pairs:\n\n\n```python\ndef total_items(carts: list[list[tuple[str, int]]]) -> int:\n return sum(qty for cart in carts for _, qty in cart)\n\ncarts = [\n [(\"Wireless Mouse\", 1), (\"USB Cable\", 2)],\n [(\"Charger\", 1)],\n [(\"HDMI Cable\", 3), (\"Webcam\", 1)],\n]\n\nprint(f\"Total items across all carts: {total_items(carts)}\")\n```\n\n\nBefore Python 3.9, the built-in containers couldn't be subscripted in annotations, so you had to import capitalized aliases from the `typing` module: `List`, `Dict`, `Tuple`, `Set`. Code written for Python 3.5 through 3.8 will look like this:\n\n\n```python\nfrom typing import List, Dict\n\ndef cart_total(prices: List[float]) -> float:\n return sum(prices)\n\ndef stock_summary(stock: Dict[str, int]) -> str:\n return f\"{sum(stock.values())} units across {len(stock)} products\"\n```\n\n\nThis style still works on Python 3.9+, but it's no longer the recommended form. The PEP 585 syntax (`list[float]`, `dict[str, int]`) is shorter, doesn't need an import, and lines up with the runtime types. You may still need to import from `typing` for things like `Optional`, `Union`, and the abstract collection types.\n\n\n> **INFO**\n>\n> **Note:** If you support Python 3.8 or older, you can't use `list[int]` in annotations without `from __future__ import annotations` at the top of the file. The `__future__` import turns all annotations into strings, which sidesteps the runtime parser. Most projects today target 3.9+ and can drop this dance.\n\n\n---\n\n# Type Hints Are Not Enforced at Runtime\n\nThis is the single most important fact about type hints in Python. The interpreter parses them, stores them as metadata, and then ignores them. A function annotated to accept an `int` will happily accept a string, a list, or anything else, and run until the body actually does something the wrong type can't handle.\n\n\n```python\ndef apply_discount(price: float, percent: float) -> float:\n return price * (1 - percent / 100)\n\n# Annotations say float, float -> float. Python doesn't care.\nresult = apply_discount(\"not a number\", \"neither\")\n```\n\n\nWhen Python runs that line, it doesn't check the annotations. It only fails inside the function body, where the actual operation can't handle strings:\n\n\n```shell\nTraceback (most recent call last):\n File \"shop.py\", line 5, in \n result = apply_discount(\"not a number\", \"neither\")\n File \"shop.py\", line 2, in apply_discount\n return price * (1 - percent / 100)\n ~~~~~~~~^~~~~\nTypeError: unsupported operand type(s) for /: 'str' and 'int'\n```\n\n\nThe `TypeError` comes from the division, not from the call. Python checked nothing about the argument types when it entered the function.\n\nA cleaner demonstration: a function whose body works on multiple types regardless of the annotation. The hint says `int`, but the function happily multiplies a string:\n\n\n```python\ndef repeat_label(text: int, times: int) -> int:\n return text * times\n\n# This is a lie at the type level, but Python runs it without complaint.\nprint(repeat_label(\"OUT OF STOCK \", 3))\n```\n\n\nThe annotations claim both parameters are `int` and the return is `int`. At runtime, `\"OUT OF STOCK \" * 3` is perfectly valid Python (string repetition), so the function returns a string with no error. A type checker run on this file would scream; the interpreter doesn't.\n\nThat gap is intentional. Runtime type checking would slow Python down on every function call, and it would conflict with the language's duck-typing philosophy (\"if it walks like a duck and quacks like a duck, it's a duck\"). The design choice was to keep types as documentation and tooling input, not as runtime contracts.\n\nThe diagram below shows the lifecycle. The annotation is recorded but never consulted during execution.\n\n\n```mermaid\nflowchart LR\n WRITE[Write annotated function]:::cyan --> COMPILE[Python compiles
and stores annotations
in __annotations__]:::teal\n COMPILE --> CALL[Function called
with wrong type]:::orange\n CALL --> CHECK{Annotation checked?}:::orange\n CHECK -->|No| RUN[Body runs
until something breaks]:::red\n RUN --> ERR[TypeError from
actual operation]:::red\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nIf you need runtime validation, you have to add it yourself: an explicit `isinstance()` check, a library like `pydantic` or `attrs` that reads annotations and validates against them, or `dataclasses` with manual validation in `__post_init__`. None of that comes from the type hint syntax alone.\n\n\n> **INFO**\n>\n> **Note:** Some libraries (FastAPI, Pydantic, SQLAlchemy 2.0) read annotations at runtime and enforce them, but only because that library deliberately introspects `__annotations__` and runs its own checks. The annotation syntax is just data the library is free to use. Python itself never enforces it.\n\n\n---\n\n# Any (and Why to Avoid It)\n\n`Any` is the escape hatch. It's a special value from the `typing` module that tells the type checker \"stop reasoning about this; assume any operation on it is fine\". It's not the same as `object`. `object` is the base of all types and accepts any value, but the type checker still restricts what you can do with an `object` (you can't call arbitrary methods on it). `Any` is the type checker's white flag.\n\n\n```python\nfrom typing import Any\n\ndef parse_legacy_record(record: Any) -> dict[str, Any]:\n # We don't know the shape of `record` ahead of time;\n # this function will handle whatever comes in.\n return {\"raw\": record, \"length\": len(record)}\n\nprint(parse_legacy_record(\"ORDER-101\"))\nprint(parse_legacy_record([1, 2, 3]))\n```\n\n\nInside this function, the type checker won't object to `len(record)`, `record + 1`, `record.upper()`, or anything else. `Any` is contagious: anything assigned from an `Any`-typed expression also becomes `Any`, which means a single sloppy annotation can erase type information across a whole module.\n\nWhen `Any` is the right call:\n\n1. You're wrapping a dynamic API (parsing untyped JSON, calling into a library with no stubs, integrating with legacy code that genuinely accepts anything).\n2. You're stubbing out a function during development and plan to tighten the types later.\n3. You're writing a truly generic helper where the type really is unknown until runtime.\n\nWhen `Any` is the wrong call:\n\n1. You couldn't figure out the right type so you reached for `Any` to silence the type checker. Now nobody benefits from the annotation.\n2. You used `Any` for a function that always takes a `str` or always takes a `dict[str, int]`. Be specific.\n3. You used `Any` because the type might be `str` or `int`. The `|` union operator handles that case without giving up checking entirely.\n\nThe rule of thumb: every `Any` should be a conscious choice you'd defend in code review, not a default. A codebase full of `Any` annotations gets the worst of both worlds: the visual noise of type hints without any of the benefit.\n\n\n```python\nfrom typing import Any\n\n# Bad: gives up all checking for no good reason\ndef cart_total(items: Any) -> Any:\n return sum(item[\"price\"] for item in items)\n\n# Better: specific about input and output shape\ndef cart_total_typed(items: list[dict[str, float]]) -> float:\n return sum(item[\"price\"] for item in items)\n\ncart = [{\"price\": 29.99}, {\"price\": 14.99}, {\"price\": 9.99}]\nprint(cart_total(cart))\nprint(cart_total_typed(cart))\n```\n\n\nBoth functions run identically. The first is invisible to the type checker; the second catches a bug the moment a caller passes a list of strings or a dict with the wrong key.\n\n---\n\n# Inspecting Annotations with `__annotations__`\n\nAnnotations are stored on the object they describe: functions have a `__annotations__` dict, classes have a `__annotations__` dict, and modules have one too (for top-level variable annotations). This is what tools like `mypy` and Pydantic use to read your hints.\n\nFor a function, `__annotations__` maps each parameter name (plus `return` for the return type) to its annotation:\n\n\n```python\ndef calculate_total(price: float, quantity: int, tax_rate: float = 0.08) -> float:\n return price * quantity * (1 + tax_rate)\n\nprint(calculate_total.__annotations__)\n```\n\n\nThe dictionary keys are parameter names; the values are the actual type objects you wrote in the source. The special key `return` holds the return annotation.\n\nFor a class, `__annotations__` collects the variables declared in the class body. Instance attributes set inside `__init__` don't show up here unless you also declare them at class scope:\n\n\n```python\nclass Product:\n name: str\n price: float\n in_stock: bool = True\n\nprint(Product.__annotations__)\n```\n\n\nA common gotcha: an annotation without an assignment doesn't create a class attribute, only an entry in `__annotations__`. So `Product.name` would raise `AttributeError` until an instance sets `self.name`, but `Product.__annotations__[\"name\"]` is `` either way.\n\nThe recommended way to read annotations from a function or class is `typing.get_type_hints()`, not `__annotations__` directly. `get_type_hints()` resolves forward references (annotations written as strings), evaluates anything wrapped in `from __future__ import annotations`, and merges class hierarchies:\n\n\n```python\nfrom typing import get_type_hints\n\ndef cart_total(prices: list[float], discount: float = 0.0) -> float:\n return sum(prices) * (1 - discount)\n\nprint(get_type_hints(cart_total))\n```\n\n\nFor most introspection work, `get_type_hints()` is the safer choice. For a quick peek during debugging, `__annotations__` is fine.\n\nWhen does this matter in practice? Three cases come up most often:\n\n1. **Library code that reads annotations.** Pydantic builds runtime validators by walking `get_type_hints()` of a model class. FastAPI generates OpenAPI schemas from route handler annotations. SQLAlchemy 2.0 reads class annotations to build column types.\n2. **Custom decorators.** A decorator that logs argument types, validates input, or generates JSON schema needs to read the wrapped function's annotations.\n3. **Documentation tooling.** Tools like Sphinx and `pdoc` read annotations to produce signature documentation without you writing it twice.\n\nFor most application code, you never touch `__annotations__` directly. The interpreter populates it, the type checker reads it, and you keep writing normal functions.","pageType":"python"}

Type Hints Basics

Get Premium