Type Hints & Annotations in Python

The Story That Explains Type Hints 🧁Type Hints समझाने वाली कहानी 🧁一个讲清类型提示的故事 🧁

Type hints write down what kind of value each variable, argument and return value should be. Python stores them but does not enforce them when the code runs. Tools such as mypy, pyright, PyCharm and VS Code read them to catch bugs, power autocompletion and document your code.

Type hints लिखते हैं कि हर variable, argument और return value किस तरह की value होनी चाहिए। Python उन्हें रखता है पर code चलते समय उन्हें लागू नहीं करता। mypy, pyright, PyCharm और VS Code जैसे tools उन्हें पढ़कर bugs पकड़ते हैं, autocompletion चलाते हैं और आपके code का दस्तावेज़ बनाते हैं।

类型提示 写明了每个变量、参数和返回值应该是什么类型的值。Python 会保存它们，但在代码运行时 不会 强制检查。mypy、pyright、PyCharm 和 VS Code 等工具会读取它们来捕获 bug、支持自动补全并生成文档。

The Problem — Untyped Python at Scale 📚समस्या — बड़े पैमाने पर बिना Types का Python 📚问题 — 大规模无类型 Python 📚

Here is the same function twice. The first is written the way most beginners write Python. The second has type hints. Both do exactly the same thing at runtime — but the second one lets a tool catch the wrong call.

यहाँ एक ही function दो बार है। पहला वैसे लिखा है जैसे ज़्यादातर beginners Python लिखते हैं। दूसरे में type hints हैं। Runtime पर दोनों बिल्कुल एक जैसा करते हैं — पर दूसरा एक tool को ग़लत call पकड़ने देता है।

下面是同一个函数的两个版本。第一个是大多数初学者写 Python 的方式，第二个带有类型提示。两者在运行时的行为完全相同 — 但第二个能让工具抓住错误的调用。

from dataclasses import dataclass

@dataclass
class User:
    name: str

# BEFORE - untyped
def greet_untyped(user):
    return "Hello " + user.name

# AFTER - typed
def greet(user: User) -> str:
    return f"Hello {user.name}"

print(greet(User("Ada")))

try:
    greet({"name": "Ada"})                 # typed: mypy flags this line
except AttributeError as e:
    print("typed version crashed:", e)

print(greet_untyped({"name": "Ada"}))      # untyped: nobody warns us

Look at both halves of the output. At runtime both versions crash on a dict. But only the typed call is flagged by mypy (line 18) — mypy says nothing about greet_untyped, because by default it does not check functions that have no annotations at all.

Output के दोनों हिस्से देखिए। Runtime पर दोनों versions dict पर crash करते हैं। पर mypy सिर्फ़ typed call को पकड़ता है (line 18) — greet_untyped के बारे में mypy कुछ नहीं कहता, क्योंकि default रूप से वह बिना किसी annotation वाले functions को जाँचता ही नहीं।

看看输出的两部分。运行时，两个 版本传入字典都会崩溃。但只有带类型的调用被 mypy 标了出来（第 18 行）— mypy 对 greet_untyped 一言不发，因为默认情况下它根本不检查没有任何注解的函数。

The Three Places Type Hints Live 🏠Type Hints की तीन जगहें 🏠类型提示的三个位置 🏠

Anatomy of a fully typed functionपूरी तरह typed function की बनावट完整带类型函数的结构

def total(prices: list[float], tax: float = 0.0) -> float:
    return sum(prices) * (1 + tax)

# Callable with confidence:
result: float = total([9.99, 14.50, 3.20], tax=0.08)
print(result)
print(round(result, 4))

Python stores hints — it does not enforce themPython hints रखता है — लागू नहीं करताPython 保存提示 — 但不强制执行

def total(prices: list[float], tax: float = 0.0) -> float:
    return sum(prices) * (1 + tax)

print(total.__annotations__)          # hints are stored, not enforced
print(total(["9.99"], tax=0))         # wrong type - Python runs it anyway

Basic Types — Your Everyday Toolkit 🧰बुनियादी Types — रोज़ का औज़ार 🧰基本类型 — 日常工具箱 🧰

# Variables
name: str = "Ada"
age: int = 30
tags: list[str] = ["dev", "python"]
scores: dict[str, float] = {"math": 91.5, "english": 88.0}
coord: tuple[float, float] = (51.5074, -0.1278)   # exactly 2 floats
unique_ids: set[int] = {101, 102, 103}

# Function
def describe(person: dict[str, str]) -> str:
    return f"{person['name']} ({person['role']})"

print(describe({"name": name, "role": tags[0]}))
age = "thirty"                    # Python allows it...
coord = (1.0, 2.0, 3.0)           # ...and this too
print(age, coord)

🧩 Simulator: Type Compatibility Explorer🧩 Simulator: Type Compatibility Explorer🧩 模拟器：类型兼容性探索器

Which values can go into which annotation? Every cell is mypy's real verdict on x: ANNOTATION = VALUE (80 checks). Click any cell — some answers are surprising.

कौन-सी values किस annotation में जा सकती हैं? हर cell x: ANNOTATION = VALUE पर mypy का असली फ़ैसला है (80 जाँच)। किसी भी cell पर click कीजिए — कुछ जवाब हैरान करने वाले हैं।

哪些值可以赋给哪种注解？每个格子都是 mypy 对 x: 注解 = 值 的真实判定（共 80 项检查）。点击任意格子 — 有些答案会让你意外。

Optional Values — Handling None Safely 🕳️Optional Values — None को सुरक्षित संभालना 🕳️可选值 — 安全地处理 None 🕳️

A value that may be either a real value or None is one of the most common patterns in Python. Type hints make you say so — and mypy makes you check before you use it.

ऐसी value जो या तो असली value हो या None, Python के सबसे आम patterns में से है। Type hints आपसे यह बताने को कहते हैं — और mypy इस्तेमाल से पहले जाँच करवाता है।

一个值 要么 是真实的值，要么 是 None，这是 Python 中最常见的模式之一。类型提示让你把这一点写明 — 而 mypy 要求你在使用前先检查。

from dataclasses import dataclass

@dataclass
class User:
    name: str

db: dict[int, User] = {42: User("Ada")}

# Modern syntax (Python 3.10+) - preferred
def find_user(user_id: int) -> User | None:
    return db.get(user_id)           # returns User OR None

def show(user_id: int) -> None:
    user = find_user(user_id)
    if user is None:
        print("not found")
    else:
        print(user.name)             # mypy KNOWS user is User here

def show_unsafe(user_id: int) -> None:
    user = find_user(user_id)
    print(user.name)                 # no None check!

show(42); show(7)
show_unsafe(7)

The runtime crash only happened for id 7 — a test with id 42 would pass. mypy found the unsafe line without running anything.

Runtime crash सिर्फ़ id 7 पर हुआ — id 42 वाला test pass हो जाता। mypy ने कुछ चलाए बिना असुरक्षित line पकड़ ली।

运行时只有 id 7 才会崩溃 — 用 id 42 的测试会顺利通过。mypy 没有运行任何代码就找到了不安全的那一行。

Union Types — When a Value Could Be Several Things 🔀Union Types — जब Value कई तरह की हो सकती है 🔀联合类型 — 当值可能是几种类型之一 🔀

Sometimes an argument can really be one of several types. Write them with | (or Union[...] on older Python). Inside the function, an isinstance check tells mypy which type you have — this is called narrowing.

कभी-कभी एक argument सच में कई types में से एक हो सकता है। उन्हें | से लिखिए (पुराने Python पर Union[...])। Function के अंदर isinstance जाँच mypy को बताती है कि आपके पास कौन-सा type है — इसे narrowing कहते हैं।

有时一个参数确实可能是几种类型之一。用 | 把它们写出来（旧版 Python 用 Union[...]）。在函数内部，isinstance 检查会告诉 mypy 你手里是哪种类型 — 这叫做 类型收窄（narrowing）。

def to_int(value: int | str | float) -> int:
    return int(value)

# Narrowing with isinstance - mypy learns the type inside each branch
def describe_id(x: int | str) -> str:
    if isinstance(x, int):
        return f"numeric id: {x:06d}"       # mypy: x is int here
    return f"named id:   {x.upper()}"       # mypy: x is str here

print(describe_id(42))
print(describe_id("ada"))
print(to_int("7"), to_int(3.9))
print(to_int("3.5"))                       # types are fine - the VALUE is not

🔎 Simulator: Narrowing Stepper🔎 Simulator: Narrowing Stepper🔎 模拟器：类型收窄单步演示

Pick a pattern and step through it. The badge shows the type mypy believes the variable has on that line — every type here comes from a real reveal_type() call.

एक pattern चुनिए और step-by-step चलिए। Badge दिखाता है कि mypy उस line पर variable का कौन-सा type मानता है — यहाँ हर type असली reveal_type() call से आया है।

选一种模式，逐步查看。徽章显示 mypy 认为该变量 在这一行 是什么类型 — 这里的每个类型都来自真实的 reveal_type() 调用。

The Type Checker Pipeline — How mypy Works ⚙️Type Checker Pipeline — mypy कैसे काम करता है ⚙️类型检查流水线 — mypy 如何工作 ⚙️

Running mypymypy चलाना运行 mypy

# Install once
pip install mypy

# Check a single file
mypy my_script.py

# Check a whole project - strict mode turns on many extra checks
mypy --strict src/

# In CI: mypy exits with code 1 when it finds errors, which fails the build
mypy --strict src/ tests/

Here is a real mypy report. Notice it says nothing about runtime — it only reads the file:

यह असली mypy report है। देखिए यह runtime के बारे में कुछ नहीं कहता — यह सिर्फ़ file पढ़ता है:

这是一份真实的 mypy 报告。注意它对运行时只字不提 — 它只是读取文件：

from dataclasses import dataclass

@dataclass
class User:
    name: str

def greet(name: str) -> str:
    return "Hello " + name

def find(uid: int) -> User | None:
    return User("Ada") if uid == 1 else None

greet(42)                              # wrong argument type
print(find(2).name)                    # may be None

🕵️ Simulator: Who Catches It — Python or mypy?🕵️ Simulator: कौन पकड़ता है — Python या mypy?🕵️ 模拟器：谁能抓住它 — Python 还是 mypy？

Eight tiny programs. For each one you see what Python did when it ran and what mypy said without running it. They catch different bugs — which is why you want both, plus tests.

आठ छोटे programs। हर एक के लिए देखिए कि चलाने पर Python ने क्या किया और बिना चलाए mypy ने क्या कहा। दोनों अलग-अलग bugs पकड़ते हैं — इसीलिए आपको दोनों चाहिए, और tests भी।

八个小程序。每个都能看到 Python 运行时做了什么，以及 mypy 不运行就说了什么。两者抓到的 bug 不同 — 所以两者都需要，再加上测试。

Callable, Iterable, Iterator — Function and Sequence Types 🔁Callable, Iterable, Iterator — Function और Sequence Types 🔁Callable、Iterable、Iterator — 函数与序列类型 🔁

from collections.abc import Callable, Iterable, Iterator

# A parameter that is a function itself
def apply(fn: Callable[[int, int], int], a: int, b: int) -> int:
    return fn(a, b)
#              ^ argument types  ^ return type

print(apply(lambda x, y: x + y, 3, 4))

# Any iterable - lists, tuples, generators, sets, ...
def total(numbers: Iterable[float]) -> float:
    return sum(numbers)

print(total([1.5, 2.5]), total((1, 2, 3)), total(x / 2 for x in range(4)))

# A generator that yields ints - Iterator[int] is usually enough
def count_up(n: int) -> Iterator[int]:
    for i in range(n):
        yield i

print(list(count_up(4)))
apply(len, 3, 4)                       # len does not take (int, int)

Callable[[int, int], int] reads as "a function that takes two ints and returns an int". mypy rejected apply(len, 3, 4) because len takes one argument, not two ints. At runtime that line would raise TypeError.

Callable[[int, int], int] को ऐसे पढ़िए: "एक function जो दो ints लेता है और int लौटाता है"। mypy ने apply(len, 3, 4) को ठुकराया क्योंकि len एक argument लेता है, दो ints नहीं। Runtime पर वह line TypeError देती।

Callable[[int, int], int] 读作"一个接收两个 int、返回 int 的函数"。mypy 拒绝了 apply(len, 3, 4)，因为 len 只接收一个参数，而不是两个 int。运行时这一行会抛出 TypeError。

Structured Data — dataclass, TypedDict, NamedTuple 🗂️Structured Data — dataclass, TypedDict, NamedTuple 🗂️结构化数据 — dataclass、TypedDict、NamedTuple 🗂️

Real programs pass around structured data. Type hints let the checker verify the shape of that data, field by field.

असली programs structured data इधर-उधर भेजते हैं। Type hints checker को उस data का आकार, field-दर-field जाँचने देते हैं।

真实程序会到处传递结构化数据。类型提示让检查器能够逐个字段地验证数据的 形状。

from dataclasses import dataclass, field
from typing import TypedDict, NamedTuple

# 1) dataclass - the workhorse
@dataclass
class User:
    id: int
    name: str
    email: str
    active: bool = True
    tags: list[str] = field(default_factory=list)

u = User(id=1, name="Ada", email="ada@x.io")
print(u)

# 2) TypedDict - for JSON-shaped data you get from an API
class WeatherPayload(TypedDict):
    city: str
    temp_c: float
    humidity: int

def summarize(w: WeatherPayload) -> str:
    return f"{w['city']}: {w['temp_c']}°C"

print(summarize({"city": "London", "temp_c": 14.2, "humidity": 67}))

# 3) NamedTuple - tiny, immutable, positional
class Point(NamedTuple):
    x: float
    y: float

p = Point(1.0, 2.0)
print(p.x, p.y)

Generics — Functions That Keep the Type 🧬Generics — Type बनाए रखने वाले Functions 🧬泛型 — 保留类型的函数 🧬

Some functions are type-preserving: whatever type goes in, the same type comes out. A TypeVar tells mypy "this is the same type in and out". reveal_type() asks mypy to print what it inferred.

कुछ functions type बनाए रखते हैं: जो type अंदर जाता है, वही बाहर आता है। TypeVar mypy को बताता है "अंदर और बाहर यही एक type है"। reveal_type() mypy से उसका अनुमान print करवाता है।

有些函数是 保留类型 的：传进去什么类型，出来就是同一类型。TypeVar 告诉 mypy"进出是同一个类型"。reveal_type() 让 mypy 打印它推断出的类型。

from collections.abc import Sequence
from typing import TypeVar, reveal_type

T = TypeVar("T")

def first(items: Sequence[T]) -> T | None:
    return items[0] if items else None

x = first([1, 2, 3])
y = first(["a", "b", "c"])
reveal_type(x)          # ask mypy what it thinks
reveal_type(y)
print(x, y)

Python and mypy see different things: at runtime reveal_type() prints the actual class (int), while mypy reports the declared type int | None.

Python और mypy अलग चीज़ें देखते हैं: runtime पर reveal_type() असली class (int) print करता है, जबकि mypy घोषित type int | None बताता है।

Python 和 mypy 看到的东西不同：运行时 reveal_type() 打印实际的类（int），而 mypy 报告声明的类型 int | None。

Python 3.12+ syntaxPython 3.12+ syntaxPython 3.12+ 语法

from collections.abc import Sequence
from typing import reveal_type

# Python 3.12+ syntax - no TypeVar import needed
def first[T](items: Sequence[T]) -> T | None:
    return items[0] if items else None

z = first((1.5, 2.5))
reveal_type(z)
print(z)

Protocols — Duck Typing, Verified 🦆Protocols — Duck Typing, जाँचा हुआ 🦆Protocol — 经过验证的鸭子类型 🦆

Python's motto is "if it walks like a duck and quacks like a duck, it is a duck". A Protocol lets mypy check that style: any class with the right method shape is accepted — no inheritance needed.

Python का मूल मंत्र है "अगर वह बत्तख की तरह चलता और बोलता है, तो वह बत्तख है"। Protocol mypy को यह शैली जाँचने देता है: सही method आकार वाली कोई भी class स्वीकार होती है — inheritance की ज़रूरत नहीं।

Python 的信条是"走起来像鸭子、叫起来像鸭子，那就是鸭子"。Protocol 让 mypy 能检查这种风格：任何具有正确方法 形状 的类都会被接受 — 不需要继承。

from typing import Protocol

class SupportsWrite(Protocol):
    def write(self, data: str) -> int: ...

def log(msg: str, sink: SupportsWrite) -> None:
    sink.write(msg + "\n")

# Any object with a matching .write() method is accepted
#   - no inheritance required, no registration required
import sys
log("starting", sys.stdout)             # works - stdout has .write

from io import StringIO
buf = StringIO()
log("buffered", buf)                    # also works - StringIO has .write
print("buffer holds:", repr(buf.getvalue()))

class Silent:
    def write(self, data: str) -> int:
        return len(data)                # our own class also matches

log("via silent", Silent())             # works

class Wrong:
    def write(self, data: bytes) -> int:
        return 0

log("oops", Wrong())                    # wrong method shape

Three unrelated classes passed. Wrong also has a write method, but it takes bytes, so mypy rejected it and showed the expected and actual signatures. Note: at runtime even Wrong ran without error — only mypy noticed.

तीन असंबंधित classes पास हुईं। Wrong में भी write method है, पर वह bytes लेता है, इसलिए mypy ने उसे ठुकराया और अपेक्षित व असली signatures दिखाए। ध्यान दें: runtime पर Wrong भी बिना error चला — सिर्फ़ mypy ने ध्यान दिया।

三个毫不相关的类都通过了。Wrong 也有 write 方法，但它接收的是 bytes，所以 mypy 拒绝了它，并列出了期望的和实际的签名。注意：运行时连 Wrong 都没有报错 — 只有 mypy 发现了问题。

Common Pitfalls (and How to Avoid Them) 🕳️आम ग़लतियाँ (और उनसे कैसे बचें) 🕳️常见陷阱（以及如何避免）🕳️

# WRONG - mutable default
def add_tag_bad(item: str, tags: list[str] = []) -> list[str]:
    tags.append(item)
    return tags        # the SAME list persists across every call!

print(add_tag_bad("a"))
print(add_tag_bad("b"))      # expected ['b']

# RIGHT - None sentinel
def add_tag(item: str, tags: list[str] | None = None) -> list[str]:
    tags = list(tags) if tags is not None else []
    tags.append(item)
    return tags

print(add_tag("a"))
print(add_tag("b"))

🪤 Simulator: The Mutable Default Trap🪤 Simulator: Mutable Default का जाल🪤 模拟器：可变默认值陷阱

Step through four calls. Watch the one default list that Python created when def ran — every call that relies on the default changes the same object. The ids come from a real run.

चार calls step-by-step देखिए। उस एक default list पर नज़र रखिए जो Python ने def चलते समय बनाई — default पर निर्भर हर call उसी object को बदलता है। ids असली run से हैं।

逐步查看四次调用。注意 Python 在执行 def 时创建的那 一个 默认列表 — 每次依赖默认值的调用改的都是同一个对象。id 来自真实运行。

What mypy does catch: a None default and a missing returnmypy क्या पकड़ता है: None default और छूटा returnmypy 能抓到的：None 默认值和缺失的 return

def greet(name: str = None) -> str:      # "None" default on a plain str
    return "Hello " + (name or "guest")

def find(xs: list[int], target: int) -> int:
    for i, x in enumerate(xs):
        if x == target:
            return i
    # forgot: return -1

Real-World Example — Typed Weather API Client 🌦️असली उदाहरण — Typed Weather API Client 🌦️实战示例 — 带类型的天气 API 客户端 🌦️

A small but production-shaped program: fetch weather from an API, turn it into a typed model, and print a report. Every step is annotated. (It talks to a local copy of the Open-Meteo API so the output is repeatable.)

एक छोटा पर production जैसा program: API से मौसम लाइए, उसे typed model में बदलिए, और report print कीजिए। हर step annotated है। (यह Open-Meteo API की local copy से बात करता है ताकि output दोहराया जा सके।)

一个小巧但接近生产环境的程序：从 API 获取天气，转换成带类型的模型，再打印报告。每一步都有注解。（它连接的是 Open-Meteo API 的本地副本，所以输出可复现。）

from __future__ import annotations
from dataclasses import dataclass
from collections.abc import Iterable
from typing import TypedDict
import requests

API = "http://127.0.0.1:8765/v1/forecast"    # local stand-in for api.open-meteo.com

# 1) Raw shape of the API response
class CurrentWeather(TypedDict):
    temperature: float
    windspeed: float
    weathercode: int

class WeatherResponse(TypedDict):
    current_weather: CurrentWeather
    timezone: str

# 2) Domain model - clean, immutable, typed
@dataclass(frozen=True)
class CityWeather:
    city: str
    temp_c: float
    wind_kmh: float
    timezone: str

# 3) Fetch -> parse -> return a typed object
def fetch_weather(city: str, lat: float, lon: float) -> CityWeather | None:
    params = {"latitude": lat, "longitude": lon, "current_weather": "true"}
    r = requests.get(API, params=params, timeout=5)
    if r.status_code != 200:
        return None
    data: WeatherResponse = r.json()
    cw = data["current_weather"]
    return CityWeather(
        city=city,
        temp_c=cw["temperature"],
        wind_kmh=cw["windspeed"],
        timezone=data["timezone"],
    )

# 4) Consume - mypy checks every step
def format_report(entries: Iterable[CityWeather]) -> str:
    lines: list[str] = ["City         Temp     Wind"]
    for e in entries:
        lines.append(f"{e.city:12s} {e.temp_c:5.1f}°C  {e.wind_kmh:4.1f} km/h")
    return "\n".join(lines)

CITIES: list[tuple[str, float, float]] = [
    ("Mumbai",   19.0760,  72.8777),
    ("New York", 40.7128, -74.0060),
    ("London",   51.5074,  -0.1278),
]

results: list[CityWeather] = [
    w for c, lat, lon in CITIES
    if (w := fetch_weather(c, lat, lon)) is not None
]
print(format_report(results))

from __future__ import annotations
from dataclasses import dataclass
from collections.abc import Iterable
from typing import TypedDict
import requests

API = "http://127.0.0.1:8765/v1/forecast"    # local stand-in for api.open-meteo.com

# 1) Raw shape of the API response
class CurrentWeather(TypedDict):
    temperature: float
    windspeed: float
    weathercode: int

class WeatherResponse(TypedDict):
    current_weather: CurrentWeather
    timezone: str

# 2) Domain model - clean, immutable, typed
@dataclass(frozen=True)
class CityWeather:
    city: str
    temp_c: float
    wind_kmh: float
    timezone: str

# 3) Fetch -> parse -> return a typed object
def fetch_weather(city: str, lat: float, lon: float) -> CityWeather | None:
    params: dict[str, float | str] = {"latitude": lat, "longitude": lon, "current_weather": "true"}
    r = requests.get(API, params=params, timeout=5)
    if r.status_code != 200:
        return None
    data: WeatherResponse = r.json()
    cw = data["current_weather"]
    return CityWeather(
        city=city,
        temp_c=cw["temperature"],
        wind_kmh=cw["windspeed"],
        timezone=data["timezone"],
    )

# 4) Consume - mypy checks every step
def format_report(entries: Iterable[CityWeather]) -> str:
    lines: list[str] = ["City         Temp     Wind"]
    for e in entries:
        lines.append(f"{e.city:12s} {e.temp_c:5.1f}°C  {e.wind_kmh:4.1f} km/h")
    return "\n".join(lines)

CITIES: list[tuple[str, float, float]] = [
    ("Mumbai",   19.0760,  72.8777),
    ("New York", 40.7128, -74.0060),
    ("London",   51.5074,  -0.1278),
]

results: list[CityWeather] = [
    w for c, lat, lon in CITIES
    if (w := fetch_weather(c, lat, lon)) is not None
]
print(format_report(results))

When to Use Type Hints — and When to Skip 🧭Type Hints कब लगाएँ — और कब छोड़ें 🧭何时使用类型提示 — 何时可以不用 🧭

Bug Doctor, Golden Rules and Quiz 🏆Bug Doctor, सुनहरे नियम और Quiz 🏆Bug 医生、黄金法则与小测验 🏆

🩺 Simulator: Bug Doctor🩺 Simulator: Bug Doctor🩺 模拟器：Bug 医生

Six real typing mistakes. Buggy code on the left, fixed code on the right, changed lines marked. Each side shows what python printed and what mypy reported.

छह असली typing ग़लतियाँ। बाईं ओर buggy code, दाईं ओर ठीक किया हुआ, बदली lines चिह्नित। हर तरफ़ दिखता है कि python ने क्या print किया और mypy ने क्या बताया।

六个真实的类型错误。左边是有 bug 的代码，右边是修正后的代码，改动的行已标出。每一边都显示 python 打印了什么、mypy 报告了什么。

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题