type hint আর mypy — চালানোর আগেই বাগ ধরা

১ · Type hint — মানুষ আর টুলের জন্য লেবেল

পর্ব ০৬-এ দেখেছেন, Python-এ dynamic typing: একটি নাম আজ একটি সংখ্যার দিকে, কাল একটি string-এর দিকে নির্দেশ করতে পারে। এই স্বাধীনতাই Python-কে দ্রুত লেখার ভাষা বানিয়েছে। কিন্তু এর একটি দাম আছে। একটি ফাংশনের def লাইন দেখে বোঝা যায় না সে কী চায়:

def add_vat(price, rate):
    return price + price * rate

price কি টাকার অঙ্ক (সংখ্যা), নাকি একটি ফর্ম থেকে পড়া লেখা (string)? rate কি 15 না 0.15? ফেরত আসে কী? উত্তর জানতে হয় ফাংশনের ভেতর পড়ে, docstring খুঁজে, বা লেখককে জিজ্ঞেস করে। দুই মাস পর লেখক নিজেও হয়তো ভুলে যাবেন। এবার একই ফাংশন type hint দিয়ে:

def add_vat(price: float, rate: float = 0.15) -> float:
    return price + price * rate

এখন def লাইনটিই একটি ছোট চুক্তি: “এই ফাংশন একটি float দাম আর একটি float হার নেয়, আর একটি float ফেরত দেয়”। : float অংশগুলোকে বলে annotation, আর -> float হলো return type-এর annotation. যখন annotation-এ একটি type লেখা হয়, তখন তাকেই আমরা type hint বলি।

তাহলে লেবেলটি পড়ে কারা? তিন পক্ষ:

কথাটি নিজের চোখে দেখুন। নিচের প্রোগ্রামে hint বলছে price একটি float, অথচ আমরা ইচ্ছা করে string আর list পাঠাচ্ছি। চালানোর আগে অনুমান করুন — কোন লাইন চলবে, কোনটি ভাঙবে?

def add_vat(price: float, rate: float = 0.15) -> float:
    return price + price * rate

print(add_vat(500))          # ঠিক type
print(add_vat(500, 2))       # int দিলাম, float চাওয়া ছিল
print(add_vat("500", 2))     # str! Python আপত্তি করে না
print(add_vat([1], 1))       # list!

count: int = "অনেক"           # ভ্যারিয়েবলের hint-ও যাচাই হয় না
print(count, type(count).__name__)

try:
    add_vat("500")           # এবার সত্যিই ভাঙল
except TypeError as e:
    print("TypeError:", e)

২ · mypy — চালানোর আগেই বাগ ধরা

Hint থেকে আসল সুরক্ষা পেতে একটি type checker চালাতে হয়। সবচেয়ে পুরোনো আর বহুল ব্যবহৃত হলো mypy. এটি একটি সাধারণ Python প্যাকেজ — পর্ব ২৩-এর মতো আপনার virtual environment-এ install করুন, তারপর ফাইলের নাম দিয়ে চালান:

pip install mypy
mypy vat.py

mypy আপনার কোড চালায় না. সে ফাইলটি পড়ে, প্রতিটি নাম আর প্রতিটি expression-এর type হিসাব করে, আর যেখানে hint-এর সাথে মেলে না সেখানে error দেখায়। এই ধরনের যাচাইকে বলে static analysis — কোড স্থির অবস্থায় রেখে বিশ্লেষণ। একটি বাস্তব বাগ ধাপে ধাপে দেখুন: একটি দোকানের হিসাব-প্রোগ্রাম দাম পড়ে একটি ফর্ম থেকে, আর ফর্মের সব মান আসে string হিসেবে।

def add_vat(price: float) -> float:
    return round(price * 1.15, 2)

def checkout(form: dict[str, str]) -> None:
    raw = form["price"]          # "500" — একটি str
    ...
    total = add_vat(raw)         # লাইন ৭

Traceback (most recent call last):
  ...
  File "vat.py", line 2, in add_vat
    return round(price * 1.15, 2)
TypeError: can't multiply sequence by non-int of type 'float'

vat.py:7: error: Argument 1 to "add_vat" has incompatible
type "str"; expected "float"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

    total = add_vat(float(raw))

Success: no issues found in 1 source file

    total = add_vat(raw)
                    ~~~
Argument of type "str" cannot be assigned to
parameter "price" of type "float"

mypy-র error বার্তা পড়া

mypy-র প্রতিটি বার্তার একই কাঠামো — ফাইল:লাইন: error: বর্ণনা [কোড]. কয়েকটি সবচেয়ে সাধারণ বার্তা নিচে (সংক্ষেপে, ফাইলের নাম ও লাইন বাদ দিয়ে):

error: Argument 1 to "add_vat" has incompatible type "str"; expected "float"  [arg-type]
error: Incompatible return value type (got "str", expected "float")  [return-value]
error: Incompatible types in assignment (expression has type "str", variable has type "int")  [assignment]
error: Item "None" of "Student | None" has no attribute "name"  [union-attr]
error: "int" has no attribute "upper"  [attr-defined]
error: Missing return statement  [return]
Found 6 errors in 1 file (checked 1 source file)

প্রথমটি ভুল argument, দ্বিতীয়টি ফাংশন যা বলেছিল তার বদলে অন্য কিছু ফেরত দিচ্ছে, তৃতীয়টি একটি int ভ্যারিয়েবলে string বসানো (ঠিক আগের runnable প্রোগ্রামের count), চতুর্থটি None-এর বাগ (অংশ ৪-এ বিস্তারিত), পঞ্চমটি ভুল type-এ method ডাকা, আর ষষ্ঠটি — -> float বলা ফাংশনের কোনো একটি শাখায় return নেই। লক্ষ করুন, প্রতিটিই এমন বাগ যা চালানোর সময় হয়তো অনেক পরে, অনেক দূরে ধরা পড়ত।

৩ · Collection-এর type — list[int] থেকে Callable

শুধু list লিখলে type checker জানে “একটি list”, কিন্তু ভেতরে কী আছে জানে না। ভেতরের type বলতে বর্গ বন্ধনী ব্যবহার করুন। এই ধরনের type — যার ভেতরে আরেকটি type বসানো যায় — তাকে বলে generic type:

marks: list[int] = [78, 91, 64]                  # সব উপাদান int
rates: dict[str, float] = {"USD": 122.5}          # চাবি str, মান float
point: tuple[float, float] = (23.81, 90.41)       # ঠিক দুটি float
scores: tuple[int, ...] = (4, 6, 1, 0)            # যেকোনো সংখ্যক int
tags: set[str] = {"python", "বাংলা"}
matrix: list[list[int]] = [[1, 2], [3, 4]]        # ভেতরে ভেতরে list

tuple-এর নিয়মটি আলাদা, খেয়াল করুন। tuple[float, float] মানে ঠিক দুটি ঘর, প্রতিটির type আলাদাভাবে বলা (পর্ব ১৫-এর রেকর্ডের মতো)। আর tuple[int, ...] — তিনটি বিন্দুসহ — মানে “যত খুশি, সবগুলো int”, list-এর মতো।

ফাংশন যখন argument: Callable

পর্ব ৩৫-এ দেখেছেন, ফাংশনও একটি object, আরেকটি ফাংশনে পাঠানো যায়। তার hint হলো Callable[[argument-এর type], return type], যা আনতে হয় collections.abc থেকে:

from collections.abc import Callable

def apply_all(prices: list[float], rule: Callable[[float], float]) -> list[float]:
    return [rule(p) for p in prices]

apply_all([100, 250], lambda p: p * 0.9)    # ১০% ছাড়

Callable[[float], float] পড়ুন এভাবে: “যাকে একটি float দিয়ে ডাকা যায় আর যে একটি float ফেরত দেয়”। Callable[[int], str] হলে একটি int নিয়ে string দেয় এমন ফাংশন। কেউ যদি দুই argument-এর ফাংশন পাঠায়, mypy আপত্তি করবে।

একটি সূক্ষ্ম নিয়ম — list কেন “অনড়”

আগেই দেখেছেন, float চাওয়া জায়গায় int চলে। তাহলে list[float] চাওয়া জায়গায় list[int] চলবে? অবাক করা উত্তর: না.

def add_fee(prices: list[float]) -> None:
    prices.append(2.5)                  # list[float]-এ float যোগ — বৈধ

counts: list[int] = [1, 2, 3]
add_fee(counts)                         # mypy: error! কেন?

কারণটি ভেতরের লাইনে। add_fee list-টিতে 2.5 যোগ করতে পারে। যদি list[int] পাঠানো চলত, তাহলে counts — যা “সবসময় int” বলে ঘোষিত — তাতে একটি float ঢুকে যেত। তাই বদলানো যায় এমন container-এর ভেতরের type হুবহু মিলতে হয়; একে বলে invariance. mypy-র বার্তাতেই সমাধান লেখা থাকে: যদি ফাংশন শুধু পড়ে, তাহলে list-এর বদলে লিখুন Sequence[float] (বা Iterable[float]), যা শুধু পড়ার চুক্তি — তাতে list[int]-ও চলবে, tuple-ও চলবে। পর্ব ৩৩-এ Iterable[HasArea] লেখার কারণ এটাই। নিয়মটি মনে রাখুন: parameter-এ যতটা সম্ভব উদার type (Sequence, Iterable, Mapping), return-এ যতটা সম্ভব নির্দিষ্ট (list, dict).

Any বনাম object — দুটি “যেকোনো কিছু”, অর্থ উল্টো

Any হলো জরুরি নির্গমন-দরজা। কোনো কিছুর type সত্যিই জানা না থাকলে, বা পুরোনো কোডে ধাপে ধাপে hint যোগ করার সময়, Any বলে “এখানে আপাতত যাচাই কোরো না”। কিন্তু প্রতিটি Any একটি অন্ধ বিন্দু — তার ভেতর দিয়ে যে বাগই যাক, mypy দেখবে না। আর Any সংক্রামক: Any থেকে পাওয়া মানও Any. যেখানে বলতে চান “যেকোনো কিছু নেব, কিন্তু অন্ধ হব না”, সেখানে object লিখুন।

৪ · None — type hint-এর সবচেয়ে বড় শিকার

বাস্তব Python প্রজেক্টে যে বাগটি সবচেয়ে বেশি দেখা যায়, তার একটি হলো এই traceback:

AttributeError: 'NoneType' object has no attribute 'name'

কাহিনি প্রায় সবসময় এক। একটি ফাংশন কিছু খোঁজে — রোল নম্বর দিয়ে ছাত্র, ফোন নম্বর দিয়ে গ্রাহক, আইডি দিয়ে অর্ডার। পেলে ফেরত দেয়, না পেলে None. যে ফাংশনটি ডাকে, সে “না পাওয়ার” সম্ভাবনা ভুলে যায়। পরীক্ষার সময় সব রোল ঠিক ছিল, তাই বাগটি ধরা পড়েনি; প্রথম ভুল রোল আসামাত্র প্রোগ্রাম ভেঙে পড়ল।

Type hint এই সম্ভাবনাটিকে def লাইনে দৃশ্যমান করে। “একটি Student, অথবা None” লেখা হয় Student | None দিয়ে — দুটি type-এর মাঝে খাড়া দাগ মানে “এটা, নয়তো ওটা”। একে বলে union type:

def get_student(roll: int) -> Student | None:
    return students.get(roll)       # dict.get না পেলে None দেয়

X | None লেখা যায় Python 3.10 থেকে (PEP 604). পুরোনো কোডে একই জিনিস দেখবেন Optional[Student] (from typing) হিসেবে — নামটি বিভ্রান্তিকর, কারণ এর অর্থ “argument ঐচ্ছিক” নয়, অর্থ “None-ও হতে পারে”। তাই আধুনিক কোডে Student | None-ই পরিষ্কার। একইভাবে int | str মানে “int অথবা str”, পুরোনো রূপে Union[int, str].

এবার আসল জাদু। get_student-এর ফল যে ব্যবহার করবে, mypy তাকে None সামলাতে বাধ্য করে — আর সামলানোর পর সে বুঝে নেয় যে এখন আর None নেই। এই বুঝে নেওয়াকে বলে type narrowing. প্রতিটি লাইনে type checker-এর চোখে s-এর type কী, ধাপে ধাপে দেখুন:

1def get_student(roll: int) -> Student | None:2    return students.get(roll)34s = get_student(42)5print(s.name)                # ভুলে গেছি!67if s is None:8    print("রোল পাওয়া যায়নি")9else:10    print(s.name)            # নিরাপদ

mypy যে পরীক্ষাগুলো বুঝে type সংকুচিত করে, তার মধ্যে আছে if x is None, if x is not None, if x:, isinstance(x, str), আর পর্ব ১১-এর match-এর case. তাই int | str নেওয়া একটি ফাংশনে if isinstance(value, str):-এর ভেতরে value.upper() বৈধ, বাইরে নয়।

৫ · নিজের type বানানো — alias, TypedDict, Literal, Final

Type alias — লম্বা type-এর একটি নাম

কখনো একই জটিল type বারবার লিখতে হয়, বা একটি সাধারণ type-কে অর্থপূর্ণ নাম দিতে চান। Python 3.12 থেকে (PEP 695) এর জন্য আছে type statement:

type Taka = int                              # পয়সা নয়, টাকা
type RateTable = dict[str, float]            # মুদ্রা → টাকায় দাম
type Handler = Callable[[str], None]

def convert(amount: float, table: RateTable, code: str) -> Taka:
    return round(amount * table[code])

এভাবে বানানো নামকে বলে type alias. লক্ষ করুন, Taka আর int mypy-র চোখে একই — alias শুধু একটি ডাকনাম, নতুন type নয়। তাই একটি সাধারণ int দিলেও mypy আপত্তি করবে না। (পুরোনো কোডে alias লেখা হতো সাধারণ assignment দিয়ে — RateTable = dict[str, float] — বা Python 3.10-এর TypeAlias দিয়ে। আর সত্যিই আলাদা type চাইলে আছে typing.NewType, যেখানে সাধারণ int দিলে mypy আপত্তি করে।)

TypedDict — JSON-এর মতো dict-এর আকার

পর্ব ২৬-এ দেখেছেন, API বা JSON ফাইল থেকে আসা ডেটা Python-এ হয়ে যায় dict. ধরুন একটি বিনিময় হারের API এমন উত্তর দেয়: {"currency": "USD", "bdt": 122.5, "date": "2026-10-18"}. dict[str, float] লেখা যাবে না, কারণ ভেতরের মানগুলো ভিন্ন ভিন্ন type-এর। dict[str, Any] লিখলে mypy অন্ধ হয়ে যায়। সমাধান TypedDict — প্রতিটি চাবির নাম আর তার মানের type আলাদাভাবে লেখা (Python 3.8 থেকে):

from typing import TypedDict, NotRequired

class Rate(TypedDict):
    currency: str
    bdt: float
    date: str
    note: NotRequired[str]          # এই চাবি না-ও থাকতে পারে

def to_taka(amount: float, rate: Rate) -> float:
    return amount * rate["bdt"]     # mypy জানে এটি float
    # rate["bdtt"] লিখলে: error: TypedDict "Rate" has no key "bdtt"

চালানোর সময় Rate একটি সাধারণ dict-ই — নতুন কোনো object তৈরি হয় না, কোনো খরচও নেই। কিন্তু mypy প্রতিটি চাবির বানান আর মানের type যাচাই করে। পর্ব ৩২-এর dataclass আর typing.NamedTuple-ও একই রকম hint দিয়ে লেখা, তবে সেগুলো সত্যিকারের নতুন class বানায়, যার attribute ডট দিয়ে পড়া হয় (rate.bdt). নিয়ম: ডেটা বাইরে থেকে dict হিসেবে আসে আর dict হিসেবেই যায় — TypedDict; নিজের প্রোগ্রামের ভেতরের রেকর্ড — dataclass.

Literal আর Final

from typing import Final, Literal

type Method = Literal["bkash", "nagad", "card"]
VAT_RATE: Final = 0.15

def pay(amount: int, method: Method) -> str:
    return f"{amount} টাকা, {method}"

pay(500, "bkash")     # ঠিক
pay(500, "bkas")      # mypy: incompatible type "Literal['bkas']"
VAT_RATE = 0.2        # mypy: Cannot assign to final name "VAT_RATE"

Literal বলে “শুধু এই নির্দিষ্ট মানগুলোর একটি” — একটি বানান ভুল, যা সাধারণ str hint কখনো ধরত না, এখন চালানোর আগেই ধরা পড়ে। Final বলে “এই নামে আর কখনো নতুন মান বসানো যাবে না” — Python-এ ধ্রুবক (constant) বলে আলাদা কিছু নেই, বড় হাতের নাম শুধু একটি রীতি; Final সেই রীতিকে type checker দিয়ে পাহারা দেয়। দুটিই এসেছে Python 3.8-এ। আর দুটিই শুধু mypy-র নিয়ম — চালানোর সময় VAT_RATE = 0.2 দিব্যি চলবে।

৬ · Generic — def first[T] আর Protocol

একটি ছোট সহায়ক ফাংশন লিখতে চান: যেকোনো list-এর প্রথম উপাদান দেবে। hint কী হবে?

• def first(items: list[str]) -> str — শুধু string-এর list চলবে, int-এর list নয়।
• def first(items: list[Any]) -> Any — সব চলবে, কিন্তু ফল Any; ফেরত পাওয়া মান নিয়ে mypy আর কিছুই যাচাই করবে না।
• def first(items: list[object]) -> object — ফল দিয়ে প্রায় কিছুই করা যাবে না; আর invariance-এর কারণে list[str] পাঠানোও যাবে না।

আসলে আমরা যা বলতে চাই, তা হলো একটি সম্পর্ক: “যে type-এর list দেবে, সেই type-এর একটি মান ফেরত পাবে”। এর জন্য দরকার একটি type variable — type-এর জায়গায় বসানো একটি নাম, যা প্রতিবার ডাকার সময় আসল type দিয়ে পূরণ হয়। Python 3.12 থেকে (PEP 695) লেখা হয় ফাংশনের নামের পরে বর্গ বন্ধনীতে:

def first[T](items: list[T]) -> T:
    return items[0]

# Python 3.11 বা আগের ধরন — একই অর্থ:
from typing import TypeVar
T = TypeVar("T")
def first_old(items: list[T]) -> T:
    return items[0]

[T] অংশটিকে বলে type parameter. ফাংশনের সাধারণ parameter যেমন মান নেয়, type parameter তেমন type নেয় — তবে সেটি আপনাকে বলে দিতে হয় না, mypy argument দেখে নিজেই বের করে। ধাপে ধাপে দেখুন T কীভাবে “প্রবাহিত” হয়:

1def first[T](items: list[T]) -> T:2    return items[0]34cities = ["ঢাকা", "খুলনা"]5c = first(cities)6print(c.upper())7n = first([10, 20])8print(n + 1)9print(n.upper())

একই syntax-এ class-ও generic হতে পারে — class Box[T]: — যেমন Python-এর নিজের list, dict. আর T-কে সীমিত করা যায়: def biggest[T: (int, float)](xs: list[T]) -> T মানে T শুধু int বা float হতে পারে।

Protocol — আকার দিয়ে চুক্তি (পর্ব ৩৩-এর পুনরালোচনা)

পর্ব ৩৩-এ দেখেছেন, Protocol দিয়ে লেখা যায় “যার area() method আছে, সে-ই চলবে” — inheritance ছাড়াই। এটি structural typing, আর এর পুরো যাচাই করে type checker. Generic আর Protocol মিলিয়ে খুব শক্তিশালী চুক্তি লেখা যায়, যেমন def total_area(shapes: Iterable[HasArea]) -> float — “যেকোনো iterable, যার প্রতিটি উপাদানের area আছে”। Python-এর নিজের Iterable, Sized, Callable-কেও type checker Protocol-এর মতো দেখে, তাই __iter__ আছে এমন যেকোনো নিজের class Iterable হিসেবে গৃহীত হয়। এভাবে type hint Python-এর duck typing-কে বাতিল করে না — লিখিত রূপ দেয়।

৭ · বাস্তব প্রজেক্টে mypy — reveal_type, strict আর ধাপে ধাপে গ্রহণ

reveal_type — mypy কী ভাবছে, জিজ্ঞেস করা

mypy যখন অবাক করা error দেয়, প্রথম প্রশ্ন: “এই লাইনে সে এই নামের type কী ভাবছে?” উত্তর জানতে কোডে লিখুন reveal_type(x), তারপর mypy চালান — সে একটি “note” দিয়ে বলে দেবে। (reveal_type Python 3.11 থেকে typing-এ একটি সাধারণ ফাংশনও, চালালে type ছেপে মান ফেরত দেয়; তবে আসল ব্যবহার mypy-র সাথে, আর কাজ শেষে লাইনটি মুছে ফেলুন।) JSON থেকে পড়া বিনিময় হারের উদাহরণে দেখুন:

1data = json.loads(text)2reveal_type(data)3data["bdt"].uper()           # বানান ভুল!45rate: Rate = json.loads(text)6reveal_type(rate)7reveal_type(rate["bdt"])8rate["bdt"].uper()

Strict mode আর কনফিগারেশন

সাধারণ অবস্থায় mypy বেশ উদার। সবচেয়ে গুরুত্বপূর্ণ উদারতা: যে ফাংশনে কোনো hint নেই, তার ভেতরের কোড mypy যাচাই করে না — সব parameter ধরে নেয় Any. এটি ইচ্ছাকৃত, পুরোনো কোডে hint ছাড়া অংশ যেন হাজারো error না দেয়। নতুন প্রজেক্টে বা পুরো hint দেওয়া module-এ চাই কঠোরতা:

mypy --strict src/

Strict mode একসাথে অনেকগুলো কঠোর নিয়ম চালু করে — hint ছাড়া ফাংশন নিষেধ, অকারণ Any ফেরত দিলে সতর্কতা, অপ্রয়োজনীয় # type: ignore থাকলে সতর্কতা, ইত্যাদি। নিয়মগুলো প্রতিবার কমান্ডে না লিখে পর্ব ২৩-এর pyproject.toml-এ রাখা যায়:

[tool.mypy]
python_version = "3.12"
check_untyped_defs = true

[[tool.mypy.overrides]]
module = "shop.billing.*"
strict = true

পুরোনো প্রজেক্টে ধাপে ধাপে

পঞ্চাশ হাজার লাইনের একটি পুরোনো প্রজেক্টে একদিনে সব hint লেখা অসম্ভব। দরকারও নেই — এখানেই gradual typing-এর শক্তি: hint দেওয়া আর না দেওয়া কোড পাশাপাশি থাকতে পারে, আর Any দুই জগতের সেতু। একটি পরীক্ষিত পথ:

1. প্রথম দিন: mypy সাধারণ অবস্থায় চালান। hint ছাড়া ফাংশনগুলো সে এড়িয়ে যাবে, তাই error হবে অল্প — আর যা আসবে, তা প্রায়ই সত্যিকারের বাগ।
2. সীমানা থেকে শুরু: সবচেয়ে বেশি ব্যবহৃত ফাংশন, public API, আর যে module সবচেয়ে বেশি বাগ দেয় — সেখানে আগে hint দিন। একটি ফাংশনের hint তার সব caller-কে যাচাইয়ের আওতায় আনে।
3. পুরোনো error আপাতত চাপা: যে লাইন এখনই ঠিক করা সম্ভব নয়, সেখানে # type: ignore[arg-type] — কোডসহ, যাতে শুধু ওই error চাপা পড়ে। পরে এগুলো খুঁজে খুঁজে সারান।
4. module ধরে কঠোরতা বাড়ানো: একটি module পুরো hint পেলে overrides-এ তাকে strict করুন — সে আর পিছিয়ে যেতে পারবে না।
5. CI-তে বসানো: প্রতিটি pull request-এ mypy চলুক (পর্ব ৩৯-এ টেস্টের সাথে)। তাহলে নতুন কোড কখনো পুরোনো মানের নিচে নামে না।

বাইরের লাইব্রেরির hint কোথা থেকে আসে? অনেক লাইব্রেরি নিজেই hint দেয়। যারা দেয় না, তাদের জন্য আলাদা stub file (.pyi) থাকে — শুধু সংজ্ঞা আর hint, শরীর ছাড়া। Python-এর standard library-র stub থাকে typeshed নামের একটি সম্প্রদায়-চালিত প্রজেক্টে, যা mypy আর pyright দুজনেই ব্যবহার করে; অনেক জনপ্রিয় লাইব্রেরির stub পাওয়া যায় types-requests-এর মতো প্যাকেজে।

৮ · চালানোর সময় hint — __annotations__, lazy evaluation, pydantic

Python hint যাচাই করে না, কিন্তু ফেলেও দেয় না। প্রতিটি ফাংশন, class আর module-এর annotation জমা থাকে একটি dict-এ, যার নাম __annotations__. যেকোনো প্রোগ্রাম চালানোর সময় এটি পড়তে পারে — এক ধরনের introspection. পড়ার সবচেয়ে নির্ভরযোগ্য উপায় typing.get_type_hints(), যা string আকারে লেখা hint-কেও আসল type-এ বদলে দেয়।

Python 3.14 — annotation এখন অলস

পুরোনো একটি ঝামেলা দিয়ে শুরু করি। ধরুন get_student ফাংশনটি ফাইলের ওপরে, আর Student class নিচে। Python 3.13 পর্যন্ত def get_student(roll: int) -> Student | None: লেখামাত্র NameError হতো — কারণ def চলার মুহূর্তেই annotation হিসাব হতো, আর তখনো Student তৈরি হয়নি। সমাধান ছিল দুটি: hint-কে string বানানো (-> "Student | None"; একে বলে forward reference), অথবা ফাইলের শুরুতে from __future__ import annotations (Python 3.7 থেকে, PEP 563), যা সব annotation-কে নিঃশব্দে string বানিয়ে রাখে।

Python 3.14-এ (PEP 649 আর PEP 749) নিয়ম বদলেছে: annotation আর def বা class চলার সময় হিসাব হয় না। Python একটি ছোট ফাংশনে সেগুলো মুড়ে রাখে, আর প্রথমবার কেউ __annotations__ চাইলে তখন হিসাব করে — এটি lazy evaluation. ফলে পরে সংজ্ঞায়িত class-এর নাম quote ছাড়াই লেখা যায়, আর যে প্রোগ্রাম annotation পড়েই না, সে তা হিসাবের খরচও দেয় না। (তবে নাম তখনো না থাকলে __annotations__ পড়ার মুহূর্তে NameError আসবে; নতুন annotationlib module সেই অবস্থাতেও পড়ার উপায় দেয়।) from __future__ import annotations 3.14-এও কাজ করে, তবে নতুন কোডে আর দরকার নেই।

নিচের প্রোগ্রামটি Python 3.14-এ চলে। লক্ষ করুন, get_student-এর hint-এ Student ব্যবহার হয়েছে তার সংজ্ঞার আগেই:

from typing import TypedDict, get_type_hints

def get_student(roll: int) -> Student | None:    # Student এখনো নেই!
    return students.get(roll)

class Student:
    def __init__(self, name: str) -> None:
        self.name = name

class Rate(TypedDict):
    currency: str
    bdt: float

def first[T](items: list[T]) -> T:
    return items[0]

students = {7: Student("রিনা")}
print(get_type_hints(get_student))
print(Rate.__annotations__)
r: Rate = {"currency": "USD", "bdt": "অনেক"}      # ভুল type, তবু চলে
print(type(r).__name__, r["bdt"])
print(first.__type_params__, first(["ঢাকা", "খুলনা"]), get_student(8))

যে টুলগুলো চালানোর সময় hint ব্যবহার করে

যেহেতু hint পড়া যায়, কিছু লাইব্রেরি এগুলো দিয়ে সত্যিকারের কাজ করে:

• dataclasses: পর্ব ৩২-এর @dataclass class-এর __annotations__ পড়েই জানে কোন কোন field আছে, আর সেই অনুযায়ী __init__ লেখে। তবে type যাচাই করে না — Point(x="ক") দিব্যি চলে।
• pydantic: একটি জনপ্রিয় তৃতীয় পক্ষের লাইব্রেরি, যা hint অনুযায়ী চালানোর সময় ডেটা যাচাই আর রূপান্তর করে। bdt: float লেখা model-এ "122.5" এলে সে float বানায়, "অনেক" এলে স্পষ্ট error দেয়। বাইরের ডেটার সীমানায় ঠিক এটাই দরকার।
• FastAPI: pydantic-এর ওপর গড়া একটি ওয়েব ফ্রেমওয়ার্ক। ফাংশনের hint দেখে সে ঠিক করে request থেকে কী পড়বে, কীভাবে যাচাই করবে, আর API-র documentation নিজেই বানায়। পর্ব ৪৮-এ এর সাথে হাতে-কলমে পরিচয় হবে।
• functools.singledispatch: প্রথম argument-এর hint দেখে ঠিক করে কোন সংস্করণ চলবে (পর্ব ৩৮-এ functools-এর অন্য হাতিয়ারগুলো)।

কোথায় hint সবচেয়ে কাজের — আর কোথায় বাড়াবাড়ি

Hint-এর লাভ সবচেয়ে বেশি যেখানে কোড অনেক মানুষ পড়ে, অনেক দিন বাঁচে, আর অনেক জায়গা থেকে ডাকা হয়: লাইব্রেরির public ফাংশন, বড় কোডবেস, দলের প্রজেক্ট, আর যে কোড প্রায়ই refactor হয়। লাভ সবচেয়ে কম এক বিকেলের একটি ছোট স্ক্রিপ্টে, Jupyter notebook-এর পরীক্ষা-নিরীক্ষায়, বা এমন কোডে যা কাল মুছে যাবে।

বাড়াবাড়ির লক্ষণও চিনুন: x: int = 5 বা names: list[str] = []-এর বাইরে প্রতিটি local ভ্যারিয়েবলে hint (mypy ডান পাশ দেখেই বোঝে); তিন স্তরের dict[str, list[tuple[int, dict[str, Any]]]] — যা আসলে বলছে “এখানে একটি dataclass বা TypedDict দরকার”; আর hint সন্তুষ্ট করতে কোড অকারণ জটিল করা। Hint সহায়ক, শাসক নয়।

৯ · AI-এর যুগে — AI-এর লেখা hint যাচাই করা

AI কোড লিখলে প্রায় সবসময় hint দেয় — দেখতে পেশাদার লাগে। কিন্তু hint ভুল হলে তা hint না থাকার চেয়েও খারাপ: পাঠক মিথ্যা লেবেল বিশ্বাস করে, আর type checker ভুল জিনিস যাচাই করে। AI-এর প্রশিক্ষণের ডেটায় Python 3.5–3.8 যুগের কোড প্রচুর, তাই কিছু ভুল বারবার দেখা যায়:

AI-এর লেখা কোড পেলে — যাচাইয়ের চেকলিস্ট

• নিজে mypy --strict (বা pyright) চালিয়েছি — AI-এর “কোনো error নেই” দাবি বিশ্বাস করিনি
• Any, type: ignore আর cast খুঁজেছি (Ctrl+F); প্রতিটির কারণ বুঝেছি
• প্রতিটি “খোঁজার” ফাংশন (get, find, search) None দিতে পারে কি না দেখেছি, আর hint-এ তা আছে কি না মিলিয়েছি
• typing.List, Optional-এর মতো পুরোনো ধরন আধুনিক রূপে বদলাতে বলেছি
• বাইরে থেকে আসা ডেটা (JSON, ফর্ম, ফাইল) চালানোর সময় যাচাই হচ্ছে কি না দেখেছি — শুধু hint যথেষ্ট নয়
• একটি ভুল type-এর call ইচ্ছা করে লিখে দেখেছি mypy সত্যিই ধরে কি না
• hint অকারণ জটিল হলে (তিন স্তরের dict) dataclass বা TypedDict দিয়ে সরল করতে বলেছি