Type hint nâng cao trong Python và kiểm tra kiểu bằng mypy
Type hint cho dự án thật: list, dict, Optional, Union, Callable, TypedDict, Literal, Generic, Protocol và chạy mypy bắt lỗi sớm.
Học xong bài này, bạn sẽ
- Viết type hint cho collection, Optional, Union, Callable
- Dùng TypedDict, Literal, Generic, Protocol
- Chạy mypy để bắt lỗi trước khi chạy
Nên học trước: Context manager và câu lệnh with
Nội dung bài viết
Python không bắt bạn khai báo kiểu, và đó là lý do nó dễ học. Nhưng khi dự án lên vài nghìn dòng và có nhiều người cùng sửa, câu hỏi "hàm này nhận gì, trả gì, có thể trả None không?" tốn rất nhiều thời gian. Type hint trả lời câu hỏi đó ngay trong code, và mypy dùng nó để bắt lỗi trước khi chạy. Gần như mọi dự án Python chuyên nghiệp hiện nay đều dùng type hint.
1. Nhắc lại và mở rộng cú pháp cơ bản
from pathlib import Path
ten: str = "An"
diem: list[float] = [8.5, 7.0]
bang_gia: dict[str, int] = {"bút": 5000}
toa_do: tuple[float, float] = (21.03, 105.85)
cac_so: tuple[int, ...] = (1, 2, 3) # tuple độ dài bất kỳ
the_loai: set[str] = {"web", "data"}
def doc_file(p: str | Path, gioi_han: int | None = None) -> list[str]:
dong = Path(p).read_text(encoding="utf-8").splitlines()
return dong if gioi_han is None else dong[:gioi_han]
def ghi_log(thong_diep: str) -> None: # không trả gì: -> None
print(thong_diep)
print(doc_file.__annotations__)
{'p': str | pathlib.Path, 'gioi_han': int | None, 'return': list[str]}
- Từ Python 3.9 dùng thẳng
list[int],dict[str, int]; code cũ hay thấyList,Dictimport từtyping, nay không cần nữa. X | Y(3.10+) nghĩa là "X hoặc Y";int | Nonelà "số nguyên hoặc không có", trước đây viếtOptional[int].- Type hint chỉ là chú thích, lưu trong
__annotations__; Python không kiểm tra khi chạy.
2. mypy: kiểm tra kiểu tĩnh
Cài pip install mypy (hoặc uv add --dev mypy ở chặng 6). Cho file don_hang.py có ba lỗi chưa lộ ra khi đọc lướt:
# (minh họa) don_hang.py: code có lỗi để mypy phát hiện
def tong_tien(gia: list[int], giam_gia: float = 0) -> int:
return round(sum(gia) * (1 - giam_gia))
def tim_khach(ma: str, kho: dict[str, str]) -> str | None:
return kho.get(ma)
tong = tong_tien(["120000", "45000"])
ten = tim_khach("KH01", {"KH01": "An"})
print(ten.upper())
$ mypy don_hang.py
don_hang.py:9: error: List item 0 has incompatible type "str"; expected "int" [list-item]
don_hang.py:9: error: List item 1 has incompatible type "str"; expected "int" [list-item]
don_hang.py:11: error: Item "None" of "str | None" has no attribute "upper" [union-attr]
Found 3 errors in 1 file (checked 1 source file)
Lỗi ở dòng 11 đặc biệt giá trị: chương trình chạy đúng với dữ liệu thử (có khách KH01), nhưng ngày nào đó khách không tồn tại thì sập với AttributeError. mypy buộc bạn xử lý trường hợp None:
def tim_khach(ma: str, kho: dict[str, str]) -> str | None:
return kho.get(ma)
ten = tim_khach("KH99", {"KH01": "An"})
if ten is not None: # sau dòng này mypy biết ten là str
print(ten.upper())
else:
print("Không có khách")
Không có khách
Kỹ thuật này gọi là thu hẹp kiểu (narrowing): sau if ten is not None, isinstance(x, str) hoặc if not ten: return, mypy hiểu kiểu đã hẹp lại. Pylance trong VS Code làm việc tương tự ngay khi bạn gõ (bật Type Checking Mode: standard trong cài đặt).
3. Callable, Literal, TypedDict
from typing import Callable, Literal, TypedDict
class DonHang(TypedDict): # mô tả dict có khóa cố định, ví dụ JSON từ API
ma: str
tong: int
trang_thai: Literal["moi", "dang_giao", "da_giao"]
def loc(ds: list[DonHang], dieu_kien: Callable[[DonHang], bool]) -> list[DonHang]:
return [d for d in ds if dieu_kien(d)]
don: list[DonHang] = [
{"ma": "D1", "tong": 450_000, "trang_thai": "moi"},
{"ma": "D2", "tong": 90_000, "trang_thai": "da_giao"},
]
print([d["ma"] for d in loc(don, lambda d: d["tong"] > 100_000)])
['D1']
Callable[[A, B], R]: hàm nhận tham số kiểu A, B và trả R.Literal["moi", ...]: chỉ chấp nhận đúng các giá trị liệt kê. Gõ"dang giao"(thiếu gạch dưới) thì mypy báoIncompatible types.TypedDict: kiểu cho dict có cấu trúc cố định. Khi dữ liệu là của riêng bạn, dataclass thường tốt hơn; TypedDict hợp với dict đến từ JSON mà bạn không muốn chuyển đổi.
4. Generic: hàm giữ nguyên kiểu đầu vào
from collections.abc import Sequence
from typing import TypeVar
T = TypeVar("T")
def dau_tien(ds: Sequence[T]) -> T | None:
return ds[0] if ds else None
so = dau_tien([3, 1, 2]) # mypy suy ra: int | None
chu = dau_tien("xin chào") # str | None
print(so, chu, dau_tien([]))
3 x None
T là một biến kiểu: "đưa vào dãy các T thì nhận lại T". Từ Python 3.12 có cú pháp gọn hơn, không cần dòng TypeVar: def dau_tien[T](ds: Sequence[T]) -> T | None:. Bài dùng TypeVar vì chạy được trên mọi phiên bản và bạn sẽ gặp nó rất nhiều trong code hiện có. Viết reveal_type(so) trong file và chạy mypy để xem kiểu nó suy ra (Revealed type is "int | None").
Khi khai báo tham số, ưu tiên kiểu trừu tượng từ collections.abc: Sequence (chỉ đọc, có thứ tự), Iterable (duyệt được), Mapping (dict chỉ đọc). Hàm nhận Iterable[str] dùng được với list, tuple, set, generator; hàm nhận list[str] thì chỉ list.
5. Áp dụng vào dự án như thế nào
- Thêm type hint cho chữ ký hàm (tham số, giá trị trả về) là đủ hiệu quả; biến cục bộ mypy tự suy ra.
- Tránh
Any: nó tắt kiểm tra. Khi chưa chắc,objectan toàn hơn. - Bắt đầu với
mypy .mặc định, sau đó bật dần chế độ nghiêm ngặt trongpyproject.toml(chặng 6):
[tool.mypy]
python_version = "3.12"
strict = true # bắt buộc mọi hàm có type hint, cấm Any ngầm định...
exclude = ["build/"]
__annotations__ để làm việc đó. Pydantic (chặng 9) dựa vào type hint để kiểm tra và chuyển đổi dữ liệu từ request: khai báo tuoi: int là API tự từ chối "abc". Viết type hint tốt từ bây giờ là chuẩn bị cho FastAPI.Tóm tắt
list[int],dict[str, int],tuple[int, ...],X | None,-> None.- mypy bắt lỗi kiểu trước khi chạy, nhất là quên xử lý
None; thu hẹp kiểu bằngis not None,isinstance. Callable,Literal,TypedDict,Protocol(chặng 4), generic vớiTypeVarhoặcdef f[T](...)(3.12+).- Tham số dùng
Sequence,Iterable,Mapping; tránhAny.
Bài tập
Bài 1. Đưa dự án chặng 2 qua mypy
Thêm type hint cho mọi hàm trong dự án quản lý chi tiêu, chạy mypy --strict chi_tieu.py và sửa đến khi sạch lỗi.
Xem gợi ý
Lỗi hay gặp nhất với --strict: Missing type parameters for generic type "dict". Mỗi khoản chi là dict có khóa cố định, nên khai báo một TypedDict:
from datetime import date
from typing import TypedDict
class KhoanChi(TypedDict):
ngay: date
so_tien: int
danh_muc: str
ghi_chu: str
def tong(ds: list[KhoanChi]) -> int:
return sum(kc["so_tien"] for kc in ds)
print(tong([{"ngay": date(2026, 10, 1), "so_tien": 45_000, "danh_muc": "ăn uống", "ghi_chu": ""}]))
45000
Thay list[dict] bằng list[KhoanChi] ở mọi hàm. Tham số khoa của tong_theo có kiểu Callable[[KhoanChi], str]. Cách tốt hơn nữa: đổi KhoanChi thành dataclass như chặng 4.
Bài 2. Hàm generic cuối cùng
Viết phan_tu_cuoi(ds: Sequence[T], mac_dinh: T) -> T trả phần tử cuối hoặc giá trị mặc định khi dãy rỗng. Dùng reveal_type kiểm tra mypy suy đúng kiểu.
Xem đáp án
from collections.abc import Sequence
from typing import TypeVar
T = TypeVar("T")
def phan_tu_cuoi(ds: Sequence[T], mac_dinh: T) -> T:
return ds[-1] if ds else mac_dinh
print(phan_tu_cuoi([1, 2, 3], 0), phan_tu_cuoi([], "trống"), phan_tu_cuoi(("a", "b"), ""))
3 trống b
Thêm dòng reveal_type(phan_tu_cuoi([1.5], 0.0)) rồi chạy mypy, kết quả: Revealed type is "float". Không có | None vì luôn có giá trị mặc định. Nhớ xóa reveal_type trước khi chạy bằng Python 3.10 trở về trước (hàm này chỉ có sẵn khi chạy từ Python 3.11).
Nguồn tham khảo: typing: Support for type hints; mypy: Getting started; PEP 695: Type Parameter Syntax.
Bài tập thực hành
- Thêm type hint đầy đủ cho dự án quản lý chi tiêu ở chặng 2 và chạy mypy đến khi không còn lỗi.
- Viết hàm generic dau_tien(ds) trả phần tử đầu hoặc None, kiểm tra mypy suy đúng kiểu.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


