Niềm vui của Type Annotation: Hướng dẫn hiện đại cho Python

Trong khoa học dữ liệu cũng như trong cuộc sống, việc hiểu rõ mình đang làm việc với cái gì là vô cùng quan trọng. Hệ thống kiểu động (dynamic type system) của Python thoạt nhìn có vẻ làm khó khăn việc này. Một kiểu dữ liệu (type) là một lời hứa về các giá trị mà một đối tượng có thể nắm giữ và các thao tác áp dụng lên nó: một số nguyên có thể được nhân hoặc so sánh, một chuỗi có thể được nối lại, một từ điển có thể được truy xuất bằng khóa. Nhiều ngôn ngữ kiểm tra những lời hứa này trước khi chương trình chạy. Rust và Go bắt các lỗi không khớp kiểu tại thời điểm biên dịch (compile time) và từ chối tạo ra tệp nhị phân nếu thất bại; TypeScript chạy các kiểm tra của nó trong một bước biên dịch riêng biệt. Python mặc định không thực hiện bất kỳ kiểm tra nào, và hậu quả sẽ diễn ra tại thời gian chạy (runtime).

Trong Python, một tên chỉ liên kết với một giá trị. Bản thân cái tên không mang theo cam kết về kiểu của giá trị đó, và phép gán tiếp theo có thể thay thế giá trị bằng một loại hoàn toàn khác. Một hàm sẽ chấp nhận bất cứ thứ gì bạn truyền vào và trả về bất cứ thứ gì thân hàm tạo ra; nếu kiểu của một trong hai không phải là những gì bạn dự định, trình thông dịch sẽ không nói gì. Sự không khớp này chỉ xuất hiện dưới dạng ngoại lệ (exception) sau này, nếu có, khi mã ở hạ tầng thực hiện một thao tác mà kiểu thực tế không hỗ trợ: tính toán trên một chuỗi, gọi phương thức trên sai loại đối tượng, hoặc một so sánh âm thầm đánh giá thành một điều vô nghĩa. Sự khoan dung này thường thực sự là một điểm mạnh: nó phù hợp với việc tạo mẫu nhanh (rapid prototyping) và công việc khám phá dựa trên notebook, nơi hình dạng của một giá trị là thứ bạn khám phá trong quá trình thực hiện. Nhưng trong các quy trình làm việc của máy học và khoa học dữ liệu, nơi các pipeline dài và một kiểu dữ liệu bất ngờ có thể âm thầm phá vỡ một bước hạ nguồn hoặc tạo ra kết quả vô nghĩa, sự linh hoạt đó trở thành một trách nhiệm nghiêm trọng.

Phản hồi của Python hiện đại đối với vấn đề này là type annotation (chú thích kiểu). Được thêm vào Python trong phiên bản 3.5 thông qua PEP 484, annotation là cú pháp để chỉ định các kiểu bạn dự định. Một hàm nhận thông tin kiểu bằng cách đính kèm nó vào các đối số và giá trị trả về bằng dấu hai chấm và mũi tên:

def scale_data(x: float) -> float:
    return x * 2

Annotation này không được thực thi tại thời gian chạy. Việc gọi scale_data("123") không gây ra lỗi trong trình thông dịch; hàm này sẽ nối chuỗi đó với chính nó và trả về "123123". Điều bắt được sự không khớp này là một phần mềm riêng biệt được gọi là static type checker (trình kiểm tra kiểu tĩnh), đọc các annotation và xác minh chúng trước khi mã chạy:

scale_data(x="123")  # Lỗi kiểu! Mong đợi float, lại nhận str

Các trình kiểm tra kiểu tĩnh hiển thị các annotation kiểu trực tiếp trong trình soạn thảo, đánh dấu các sự không khớp khi bạn viết. Cùng với các công cụ đã được thiết lập như mypy và pyright, thế hệ trình kiểm tra mới hơn dựa trên Rust (như ty của Astral, Pyrefly của Meta, và Zuban mã nguồn mở) đang đẩy hiệu suất đi xa hơn, khiến việc phân tích toàn bộ dự án khả thi ngay cả trên các cơ sở mã lớn. Mô hình này được tách biệt có chủ đích khỏi thời gian chạy của Python. Type hints là tùy chọn và việc kiểm tra xảy ra trước khi thực thi thay vì trong quá trình thực thi.

Làm rõ cấu trúc dữ liệu

Từ điển (dictionaries) là "ngựa thồ" của công việc dữ liệu Python. Các hàng từ tập dữ liệu, đối tượng cấu hình, phản hồi API: tất cả thường được biểu diễn dưới dạng các dict với các khóa và kiểu giá trị đã biết. TypedDict (PEP 589) cung cấp một cách nhẹ nhàng để viết schema như vậy:

from typing import TypedDict

class SensorReading(TypedDict):
    timestamp: float
    temperature: float
    pressure: float
    location: str

def process_reading(reading: SensorReading) -> float:
    return reading["temperature"] * 1.8 + 32
    # return reading["temp"]  # Lỗi kiểu: không có khóa nào như vậy

Tại thời gian chạy, SensorReading chỉ là một dict thông thường với chi phí hiệu suất bằng không. Nhưng trình kiểm tra kiểu của bạn bây giờ biết schema, điều này có nghĩa là các lỗi chính tả trong tên khóa sẽ bị bắt ngay lập tức thay vì xuất hiện dưới dạng KeyErrors trong môi trường sản xuất. PEP nhấn mạnh các đối tượng JSON là trường hợp sử dụng điển hình. Đây là một lý do sâu sắc hơn khiến TypedDict quan trọng trong công việc dữ liệu: nó cho phép bạn mô tả hình dạng của dữ liệu mà bạn không sở hữu, chẳng hạn như phản hồi từ API, các hàng đến từ CSV, hoặc tài liệu bạn lấy từ cơ sở dữ liệu, mà không cần bọc chúng trong một lớp trước.

Các giá trị phân loại (categorical values) là một loại kiến thức ngầm định mà mã khoa học dữ liệu luôn mang theo. Các phương pháp tổng hợp, đặc tả đơn vị, tên mô hình, cờ chế độ: những thứ này thường chỉ sống trong các chuỗi tài liệu (docstrings) và nhận xét, nơi trình kiểm tra kiểu không thể tiếp cận chúng. Literal types (PEP 586) làm cho tập hợp các giá trị hợp lệ trở nên rõ ràng:

from typing import Literal

def aggregate_timeseries(
    data: list[float],
    method: Literal["mean", "median", "max", "min"]
) -> float:
    if method == "mean":
        return sum(data) / len(data)
    elif method == "median":
        return sorted(data)[len(data) // 2]
    # v.v.

aggregate_timeseries([1, 2, 3], "mean")     # ổn
aggregate_timeseries([1, 2, 3], "average")  # lỗi kiểu: bắt trước khi chạy

Literal hữu ích nhất sâu trong một pipeline, nơi một lỗi chính tả như "temperture" có thể không gây ra ngoại lệ nhưng sẽ âm thầm tạo ra kết quả sai. Việc giới hạn các giá trị được phép bắt những sai lầm này sớm và làm cho các tùy chọn hợp lệ trở nên rõ ràng. Các IDE cũng có thể tự động hoàn thành chúng, giúp giảm ma sát theo thời gian.

Làm rõ sự lựa chọn

Dữ liệu thực và API thực hiếm khi chỉ cung cấp một kiểu duy nhất. Một hàm có thể chấp nhận tên tệp hoặc một handle tệp đang mở. Một giá trị cấu hình có thể là một số hoặc một chuỗi. Một trường bị thiếu có thể là một giá trị hoặc None. Union types cho phép bạn nói điều đó trực tiếp:

from typing import TextIO

def load_data(source: str | TextIO) -> list[str]:
    if isinstance(source, str):
        with open(source) as f:
            return f.readlines()
    else:
        return source.readlines()

Cú pháp | được thêm vào bởi PEP 604 và có sẵn từ Python 3.10. Mã cũ hơn sử dụng Union[str, TextIO] từ module typing, có nghĩa là chính xác cùng một thứ.

Theo một cách khá lớn, union phổ biến nhất là union mà None là một trong các lựa chọn. Các phép đo thất bại, cảm biến chưa được cài đặt, API trả về phản hồi không hoàn chỉnh, và một hàm trả về kết quả hoặc không có gì là ở khắp nơi trong công việc dữ liệu. Cách viết hiện đại là float | None:

def calculate_efficiency(fuel_consumed: float | None) -> float | None:
    if fuel_consumed is None:
        return None
    return 100.0 / fuel_consumed

Trình kiểm tra kiểu bây giờ sẽ gắn cờ bất kỳ mã nào cố gắng sử dụng giá trị trả về như một float xác định mà không kiểm tra None trước, ngăn chặn một lớp lớn các lỗi TypeError: unsupported operand type(s) sẽ xuất hiện tại thời gian chạy.

Làm rõ hành vi

Công việc dữ liệu liên quan đến việc chuyển các hàm dưới dạng đối số liên tục. GridSearchCV của Scikit-learn nhận một hàm tính điểm (scoring function). Các bộ tối ưu hóa PyTorch nhận bộ lập lịch tốc độ học (learning-rate schedulers). Callable cho phép bạn chỉ định các đối số mà một hàm nhận và những gì nó trả về:

from typing import Callable

# Một bước tiền xử lý: nhận danh sách float, trả về danh sách float
Preprocessor = Callable[[list[float]], list[float]]

def build_pipeline(steps: list[Preprocessor]) -> Preprocessor:
    def pipeline(x: list[float]) -> list[float]:
        for step in steps:
            x = step(x)
        return x
    return pipeline

Duck typing là một trong những thứ khiến Python cảm thấy trôi chảy: nếu một đối tượng có các phương thức đúng, nó có thể được sử dụng trong một ngữ cảnh nhất định bất kể hệ thống phân cấp kế thừa của nó. Vấn đề là sự trôi chảy này biến mất tại chữ ký hàm. Protocol (PEP 544) giải quyết điều này bằng cách gõ kiểu theo cấu trúc (structural) thay vì theo danh nghĩa (nominal). Trình kiểm tra kiểu quyết định xem một đối tượng có thỏa mãn một Protocol hay không bằng cách kiểm tra các phương thức và thuộc tính của nó, không phải bằng đi lên chuỗi kế thừa của nó.

from typing import Protocol

class Summable(Protocol):
    def sum(self) -> float: ...
    def __len__(self) -> int: ...

def calculate_mean(data: Summable) -> float:
    return data.sum() / len(data)

import pandas as pd
import numpy as np

calculate_mean(pd.Series([1, 2, 3]))  # ✓ kiểm tra kiểu
calculate_mean(np.array([1, 2, 3]))   # ✓ kiểm tra kiểu
calculate_mean([1, 2, 3])             # ✗ lỗi kiểu: list không có .sum()

pd.Series không kế thừa từ Summable, và np.ndarray cũng không. Chúng thỏa mãn protocol vì chúng có phương thức sum và hỗ trợ len(). Một danh sách Python thuần túy thì không, vì sum trên danh sách là một hàm tự do chứ không phải phương thức.

Generics: Giữ nguyên thông tin

Khoa học dữ liệu chủ yếu là về các phép biến đổi, và một phép biến đổi được gõ kiểu tốt sẽ bảo toàn thông tin về những gì đang chảy qua nó. Thách thức là diễn đạt "bất kỳ kiểu nào đến, cùng một kiểu đó đi ra" mà không phải dùng đến Any, vốn chỉ đơn giản là tắt trình kiểm tra kiểu cho biến đó. TypeVar là cấu trúc giải quyết vấn đề này:

from typing import TypeVar

T = TypeVar('T')

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

x: int = first_element([1, 2, 3])       # ✓ x là int
y: str = first_element(["a", "b", "c"]) # ✓ y là str
z: str = first_element([1, 2, 3])       # ✗ lỗi kiểu: trả về int, không phải str

T là một biến kiểu: một trình giữ chỗ mà trình kiểm tra giải quyết thành một kiểu cụ thể tại điểm gọi. Việc gọi first_element([1, 2, 3]) liên kết T với int cho cuộc gọi đó, và annotation trả về T được đọc là int tương ứng. Gọi nó với danh sách chuỗi, và T trở thành str. Mối liên kết giữa đầu vào và đầu ra được bảo toàn mà không cam kết hàm với bất kỳ kiểu cụ thể nào.

Các cân nhắc thực tế

Mặc dù có nhiều lợi ích, annotation có những giới hạn. Hệ thống kiểu không thể diễn đạt mọi thứ Python có thể làm: các khung động, decorator thay đổi chữ ký hàm và metaprogramming kiểu ORM đều ngồi không thoải mái trong nó. Annotation cũng thêm chi phí. Trình kiểm tra kiểu đôi khi sẽ không đồng ý với mã bạn biết là đúng, và thời gian dành để thuyết phục nó là thời gian bạn không dành cho vấn đề thực tế.

Một phản ứng hợp lý là chọn trận chiến của bạn. Bắt đầu với các hàm nơi có nhiều sự không chắc chắn nhất về những gì đang đến, chẳng hạn như phản hồi API hoặc bất cứ thứ gì đọc từ cơ sở dữ liệu. Phạm vi bao phủ phát triển từ đó. Đối lập với chi phí là những chiến thắng cụ thể. Một khóa sai trong TypedDict bị bắt tại lần nhấn phím thay vì là KeyError nhiều ngày sau đó. Một chữ ký hàm với các kiểu nói cho người đọc tiếp theo những gì nó mong đợi mà không cần họ phải đọc thân hàm. Biết khi và cách tốt nhất để thêm annotation là một nghề thủ công, và như bất kỳ nghề thủ công nào, nó đền đáp cho việc thực hành. Sử dụng tốt, type annotation biến các giả định về mã của bạn thành những thứ trình kiểm tra có thể xác minh, làm cho cuộc sống của bạn dễ dàng và chắc chắn hơn trong quá trình này. Chúc bạn gõ phím vui vẻ!