`typing` --- Hỗ trợ gợi ý loại¶

Added in version 3.5.

Ghi chú

Thời gian chạy Python không thực thi các chú thích hàm và kiểu biến. Chúng có thể được sử dụng bởi các công cụ của bên thứ ba như type checkers, IDE, linters, v.v.

Mô-đun này cung cấp hỗ trợ thời gian chạy cho các gợi ý loại.

Hãy xem xét hàm dưới đây:

def surface_area_of_cube(edge_length: float) -> str:
    return f"Diện tích bề mặt của hình lập phương là {6 * edge_length ** 2}."

Hàm surface_area_of_cube nhận một đối số dự kiến là một phiên bản của float, như được biểu thị bằng type hint edge_length: float. Hàm dự kiến sẽ trả về một phiên bản của str, như được biểu thị bằng gợi ý -> str.

Mặc dù gợi ý loại có thể là các lớp đơn giản như float hoặc str nhưng chúng cũng có thể phức tạp hơn. Mô-đun typing cung cấp vốn từ vựng gồm các gợi ý loại nâng cao hơn.

Các tính năng mới thường xuyên được thêm vào mô-đun typing. Gói typing_extensions cung cấp bản sao lưu các tính năng mới này cho các phiên bản Python cũ hơn.

Xem thêm

Typing cheat sheet: Tổng quan nhanh về gợi ý loại (được lưu trữ tại tài liệu mypy)
Gõ phần System Reference của the mypy docs: Hệ thống gõ Python được chuẩn hóa thông qua PEP, vì vậy tài liệu tham khảo này sẽ được áp dụng rộng rãi cho hầu hết các trình kiểm tra kiểu Python. (Một số phần có thể vẫn dành riêng cho mypy.)
Static Typing with Python: Tài liệu về trình kiểm tra kiểu-bất khả tri được viết bởi cộng đồng nêu chi tiết các tính năng của hệ thống kiểu, các công cụ hữu ích liên quan đến việc gõ và các phương pháp hay nhất về cách gõ.

Đặc điểm kỹ thuật cho hệ thống kiểu Python¶

Bạn có thể tìm thấy thông số kỹ thuật chuẩn, cập nhật của hệ thống kiểu Python tại Specification for the Python type system.

Nhập bí danh¶

Bí danh loại được xác định bằng câu lệnh type, câu lệnh này tạo ra một phiên bản của TypeAliasType. Trong ví dụ này, Vector và list[float] sẽ được xử lý tương đương bởi trình kiểm tra loại tĩnh:

gõ Vector = danh sách [float]

tỉ lệ def(vô hướng: float, vector: Vector) -> Vector:
    trả về [vô hướng * num cho num trong vector]

kiểm tra loại # passes; một danh sách các số float đủ điều kiện là một Vector.
new_vector = tỷ lệ (2.0, [1.0, -4.2, 5.4])

Bí danh loại rất hữu ích để đơn giản hóa chữ ký loại phức tạp. Ví dụ:

từ Trình tự nhập bộ sưu tập.abc

gõ ConnectionOptions = dict[str, str]
gõ Địa chỉ = tuple[str, int]
gõ Máy chủ = tuple[Địa chỉ, Tùy chọn kết nối]

def Broadcast_message(message: str, server: Sequence[Server]) -> None:
    ...

Trình kiểm tra kiểu tĩnh # The sẽ coi chữ ký kiểu trước đó là
# being chính xác tương đương với cái này.
chắc chắn Broadcast_message(
    tin nhắn: str,
    máy chủ: Sequence[tuple[tuple[str, int], dict[str, str]]]
) -> Không có:
    ...

Câu lệnh type là câu lệnh mới trong Python 3.12. Để tương thích ngược, bí danh loại cũng có thể được tạo thông qua phép gán đơn giản

Vector = danh sách[float]

Hoặc được đánh dấu bằng TypeAlias để làm rõ rằng đây là bí danh loại, không phải phép gán biến thông thường

từ việc nhập import TypeAlias

Vector: TypeAlias = list[float]

Loại mới¶

Sử dụng trình trợ giúp NewType để tạo các loại riêng biệt:

từ việc gõ nhập NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

Trình kiểm tra kiểu tĩnh sẽ xử lý kiểu mới như thể nó là một lớp con của kiểu ban đầu. Điều này rất hữu ích trong việc giúp bắt lỗi logic:

def get_user_name(user_id: UserId) -> str:
    ...

kiểm tra loại # passes
user_a = get_user_name(UserId(42351))

kiểm tra loại # fails; int không phải là UserId
user_b = get_user_name(-1)

Bạn vẫn có thể thực hiện tất cả các thao tác int trên một biến loại UserId, nhưng kết quả sẽ luôn thuộc loại int. Điều này cho phép bạn chuyển UserId vào bất cứ nơi nào có thể mong đợi int, nhưng sẽ ngăn bạn vô tình tạo UserId theo cách không hợp lệ:

# 'đầu ra' thuộc loại 'int', không phải 'UserId'
đầu ra = UserId(23413) + UserId(54341)

Lưu ý rằng những kiểm tra này chỉ được thực thi bởi trình kiểm tra kiểu tĩnh. Trong thời gian chạy, câu lệnh Derived = NewType('Derived', Base) sẽ biến Derived thành một lệnh gọi có thể trả về ngay lập tức bất kỳ tham số nào bạn truyền vào. Điều đó có nghĩa là biểu thức Derived(some_value) không tạo ra một lớp mới hoặc đưa ra nhiều chi phí ngoài lệnh gọi hàm thông thường.

Chính xác hơn, biểu thức some_value is Derived(some_value) luôn đúng trong thời gian chạy.

Việc tạo một kiểu con của Derived:: là không hợp lệ.

từ việc gõ nhập NewType

UserId = NewType('UserId', int)

# Fails khi chạy và không vượt qua được việc kiểm tra loại
lớp AdminUserId(UserId): vượt qua

Tuy nhiên, có thể tạo NewType dựa trên NewType 'có nguồn gốc':

từ việc gõ nhập NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

và việc kiểm tra đánh máy cho ProUserId sẽ hoạt động như mong đợi.

Xem PEP 484 để biết thêm chi tiết.

Ghi chú

Hãy nhớ lại rằng việc sử dụng bí danh loại sẽ khai báo hai loại là equivalent với nhau. Thực hiện type Alias = Original sẽ khiến trình kiểm tra loại tĩnh coi Alias là exactly equivalent đến Original trong mọi trường hợp. Điều này hữu ích khi bạn muốn đơn giản hóa các chữ ký kiểu phức tạp.

Ngược lại, NewType tuyên bố một loại là subtype của loại khác. Thực hiện Derived = NewType('Derived', Original) sẽ khiến trình kiểm tra loại tĩnh coi Derived là subclass của Original, nghĩa là không thể sử dụng giá trị loại Original ở những nơi dự kiến có giá trị loại Derived. Điều này hữu ích khi bạn muốn ngăn chặn lỗi logic với chi phí thời gian chạy tối thiểu.

Added in version 3.5.2.

Thay đổi trong phiên bản 3.10: NewType bây giờ là một lớp chứ không phải là một hàm. Do đó, sẽ có thêm một số chi phí thời gian chạy khi gọi NewType qua một hàm thông thường.

Thay đổi trong phiên bản 3.11: Hiệu suất gọi NewType đã được khôi phục về mức cũ trong Python 3.9.

Chú thích các đối tượng có thể gọi được¶

Các hàm -- hoặc các đối tượng callable khác -- có thể được chú thích bằng collections.abc.Callable hoặc typing.Callable không được dùng nữa. Callable[[int], str] biểu thị một hàm nhận một tham số duy nhất thuộc loại int và trả về str.

Ví dụ:

từ bộ sưu tập.abc nhập Có thể gọi được, có thể chờ đợi

bộ nạp def(get_next_item: Callable[[], str]) -> Không có:
    ... # Body

def async_query(on_success: Có thể gọi được[[int], None],
                on_error: Có thể gọi được[[int, Ngoại lệ], Không có]) -> Không có:
    ... # Body

async def on_update(value: str) -> Không có:
    ... # Body

gọi lại: Có thể gọi được[[str], Đang chờ [None]] = on_update

Cú pháp đăng ký phải luôn được sử dụng với chính xác hai giá trị: danh sách đối số và kiểu trả về. Danh sách đối số phải là danh sách các loại, ParamSpec, Concatenate hoặc dấu chấm lửng (...). Kiểu trả về phải là một kiểu duy nhất.

Nếu một dấu chấm lửng ... theo nghĩa đen được đưa ra làm danh sách đối số, nó chỉ ra rằng một lệnh có thể gọi được với bất kỳ danh sách tham số tùy ý nào sẽ được chấp nhận:

def concat(x: str, y: str) -> str:
    trả về x + y

x: Có thể gọi được[..., str]
x = str # OK
x = concat # Also OK

Callable không thể biểu thị các chữ ký phức tạp như các hàm lấy số lượng đối số thay đổi, overloaded functions hoặc các hàm chỉ có tham số từ khóa. Tuy nhiên, những chữ ký này có thể được biểu thị bằng cách định nghĩa lớp Protocol bằng phương thức __call__():

từ bộ sưu tập.abc nhập Có thể lặp lại
từ việc nhập Giao thức nhập

Trình kết hợp lớp (Giao thức):
    def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...

def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> byte:
    cho mục trong dữ liệu:
        ...

def good_cb(*vals: byte, maxlen: int | None = None) -> list[byte]:
    ...
def bad_cb(*vals: byte, maxitems: int | None) -> list[byte]:
    ...

batch_proc([], good_cb) # OK
batch_proc([], bad_cb) # Error! Đối số 2 có loại không tương thích vì
                         tên và loại # different trong cuộc gọi lại

Các lệnh gọi lấy các lệnh gọi khác làm đối số có thể chỉ ra rằng các loại tham số của chúng phụ thuộc lẫn nhau bằng cách sử dụng ParamSpec. Ngoài ra, nếu lệnh gọi đó thêm hoặc xóa đối số khỏi các lệnh gọi khác, toán tử Concatenate có thể được sử dụng. Chúng có dạng Callable[ParamSpecVariable, ReturnType] và Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType] tương ứng.

Thay đổi trong phiên bản 3.10: Callable hiện hỗ trợ ParamSpec và Concatenate. Xem PEP 612 để biết thêm chi tiết.

Xem thêm

Tài liệu dành cho ParamSpec và Concatenate cung cấp các ví dụ về cách sử dụng trong Callable.

Thuốc gốc¶

Do thông tin loại về các đối tượng được lưu giữ trong vùng chứa không thể được suy ra tĩnh theo cách chung, nên nhiều lớp vùng chứa trong thư viện tiêu chuẩn hỗ trợ đăng ký để biểu thị các loại phần tử vùng chứa dự kiến.

từ bộ sưu tập.abc nhập Ánh xạ, Trình tự

Nhân viên lớp: ...

# Sequence[Employee] chỉ ra rằng tất cả các phần tử trong chuỗi
# must là phiên bản của "Nhân viên".
# Mapping[str, str] chỉ ra rằng tất cả các khóa và tất cả các giá trị trong ánh xạ
# must là chuỗi.
def thông báo_by_email(nhân viên: Trình tự[Nhân viên],
                    ghi đè: Ánh xạ[str, str]) -> Không có: ...

Các hàm và lớp chung có thể được tham số hóa bằng cách sử dụng type parameter syntax:

từ Trình tự nhập bộ sưu tập.abc

def first[T](l: Sequence[T]) -> T: # Function là chung trên TypeVar "T"
    trả lại l[0]

Hoặc bằng cách sử dụng trực tiếp nhà máy TypeVar

từ Trình tự nhập bộ sưu tập.abc
từ việc gõ nhập TypeVar

U = Biến loại TypeVar('U') # Declare "U"

def giây(l: Sequence[U]) -> U: # Function là chung trên TypeVar "U"
    trả lại l[1]

Thay đổi trong phiên bản 3.12: Hỗ trợ cú pháp cho generics là tính năng mới trong Python 3.12.

Chú thích các bộ dữ liệu¶

Đối với hầu hết các vùng chứa trong Python, hệ thống gõ giả định rằng tất cả các phần tử trong vùng chứa sẽ có cùng loại. Ví dụ:

từ bộ sưu tập.abc nhập bản đồ

Trình kiểm tra # Type sẽ suy ra rằng tất cả các phần tử trong ``x`` đều có nghĩa là int
x: danh sách[int] = []

Lỗi trình kiểm tra # Type: ``list`` chỉ chấp nhận một đối số loại duy nhất:
y: list[int, str] = [1, 'foo']

Trình kiểm tra # Type sẽ suy ra rằng tất cả các khóa trong ``z`` đều là chuỗi,
# and rằng tất cả các giá trị trong ``z`` đều có nghĩa là chuỗi hoặc số nguyên
z: Ánh xạ[str, str | int] = {}

list chỉ chấp nhận một đối số loại, do đó trình kiểm tra loại sẽ phát ra lỗi khi gán y ở trên. Tương tự, Mapping chỉ chấp nhận hai đối số loại: đối số thứ nhất cho biết loại khóa và đối số thứ hai cho biết loại giá trị.

Tuy nhiên, không giống như hầu hết các bộ chứa Python khác, thông thường trong mã Python thông thường các bộ dữ liệu có các phần tử không cùng loại. Vì lý do này, các bộ dữ liệu được đặt cách đặc biệt trong hệ thống gõ của Python. tuple chấp nhận any number của các đối số kiểu:

# OK: ``x`` được gán cho một bộ có độ dài 1 trong đó phần tử duy nhất là int
x: bộ [int] = (5,)

# OK: ``y`` được gán cho một bộ có độ dài 2;
# element 1 là int, phần tử 2 là str
y: tuple[int, str] = (5, "foo")

# Error: chú thích kiểu biểu thị một bộ có độ dài 1,
# but ``z`` đã được gán cho một bộ có độ dài 3
z: bộ[int] = (1, 2, 3)

Để biểu thị một bộ có thể có độ dài any và trong đó tất cả các phần tử có cùng loại T, hãy sử dụng dấu chấm lửng ...: tuple[T, ...]. Để biểu thị một bộ trống, hãy sử dụng tuple[()]. Sử dụng tuple đơn giản làm chú thích tương đương với việc sử dụng tuple[Any, ...]:

x: tuple[int, ...] = (1, 2)
Việc gán lại # These đều được: ``tuple[int, ...]`` biểu thị x có thể có độ dài bất kỳ
x = (1, 2, 3)
x = ()
Việc gán lại # This là một lỗi: tất cả các phần tử trong ``x`` phải là số nguyên
x = ("foo", "thanh")

# zz002zz chỉ có thể được gán cho một bộ dữ liệu trống
y: bộ [()] = ()

z: tuple = ("foo", "bar")
Việc gán lại # These đều ổn: ``tuple`` đơn giản tương đương với ``tuple[Any, ...]``
z = (1, 2, 3)
z = ()

Kiểu đối tượng của lớp¶

Một biến được chú thích bằng C có thể chấp nhận giá trị thuộc loại C. Ngược lại, một biến được chú thích bằng type[C] (hoặc typing.Type[C] không được dùng nữa) có thể chấp nhận các giá trị là các lớp -- cụ thể, nó sẽ chấp nhận class object của C. Ví dụ:

a = 3 # Has loại ``int``
b = int # Has gõ ``type[int]``
c = loại(a) # Also có loại ``type[int]``

Lưu ý rằng type[C] là hiệp biến:

Người dùng lớp: ...
lớp ProUser(Người dùng): ...
lớp TeamUser(Người dùng): ...

def make_new_user(user_class: type[User]) -> Người dùng:
    # ...
    trả về user_class()

make_new_user(Người dùng) # OK
make_new_user(ProUser) # Also OK: ``type[ProUser]`` là một kiểu con của ``type[User]``
make_new_user(TeamUser) # Still ổn
make_new_user(User()) # Error: mong đợi ``type[User]`` nhưng lại nhận được ``User``
make_new_user(int) # Error: ``type[int]`` không phải là kiểu con của ``type[User]``

Các tham số pháp lý duy nhất cho type là các lớp, Any, type variables và các liên kết thuộc bất kỳ loại nào trong số này. Ví dụ:

def new_non_team_user(user_class: type[BasicUser | ProUser]): ...

new_non_team_user(Người dùng cơ bản) # OK
new_non_team_user(ProUser) # OK
new_non_team_user(TeamUser) # Error: ``type[TeamUser]`` không phải là một kiểu con
                              # of ``type[BasicUser | ProUser]``
new_non_team_user(User) # Also bị lỗi

type[Any] tương đương với type, là gốc của metaclass hierarchy của Python.

Trình tạo chú thích và coroutine¶

Trình tạo có thể được chú thích bằng loại chung Generator[YieldType, SendType, ReturnType]. Ví dụ:

def echo_round() -> Generator[int, float, str]:
    đã gửi = năng suất 0
    trong khi gửi >= 0:
        đã gửi = vòng lợi nhuận (đã gửi)
    trả về 'Xong'

Lưu ý rằng không giống như nhiều lớp chung khác trong thư viện chuẩn, SendType của Generator hoạt động trái ngược, không hiệp biến hoặc bất biến.

Các tham số SendType và ReturnType mặc định là None:

def vô hạn_stream (bắt đầu: int) -> Trình tạo [int]:
    trong khi Đúng:
        bắt đầu năng suất
        bắt đầu += 1

Cũng có thể đặt các loại này một cách rõ ràng

def vô hạn_stream (bắt đầu: int) -> Trình tạo [int, Không, Không]:
    trong khi Đúng:
        bắt đầu năng suất
        bắt đầu += 1

Các trình tạo đơn giản chỉ mang lại giá trị cũng có thể được chú thích là có kiểu trả về là Iterable[YieldType] hoặc Iterator[YieldType]:

def vô hạn_stream(bắt đầu: int) -> Iterator[int]:
    trong khi Đúng:
        bắt đầu năng suất
        bắt đầu += 1

Trình tạo không đồng bộ được xử lý theo cách tương tự, nhưng đừng mong đợi đối số loại ReturnType (AsyncGenerator[YieldType, SendType]). Đối số SendType mặc định là None, vì vậy các định nghĩa sau đây là tương đương:

async def vô hạn_stream(bắt đầu: int) -> AsyncGenerator[int]:
    trong khi Đúng:
        bắt đầu năng suất
        bắt đầu = chờ tăng(bắt đầu)

async def vô hạn_stream(start: int) -> AsyncGenerator[int, None]:
    trong khi Đúng:
        bắt đầu năng suất
        bắt đầu = chờ tăng(bắt đầu)

Như trong trường hợp đồng bộ, AsyncIterable[YieldType] và AsyncIterator[YieldType] cũng có sẵn:

async def vô hạn_stream(bắt đầu: int) -> AsyncIterator[int]:
    trong khi Đúng:
        bắt đầu năng suất
        bắt đầu = chờ tăng(bắt đầu)

Coroutine có thể được chú thích bằng Coroutine[YieldType, SendType, ReturnType]. Các đối số chung tương ứng với các đối số của Generator, ví dụ:

từ bộ sưu tập.abc nhập Coroutine
c: Coroutine[list[str], str, int] # Some coroutine được xác định ở nơi khác
x = c.send('hi') # Inferred loại 'x' là list[str]
thanh def async() -> Không có:
    y = đang chờ c # Inferred loại 'y' là int

Các loại chung do người dùng xác định¶

Một lớp do người dùng định nghĩa có thể được định nghĩa là một lớp chung.

từ ghi nhật ký nhập nhập Trình ghi nhật ký

lớp LoggedVar[T]:
    def __init__(self, value: T, name: str, logger: Logger) -> Không có:
        self.name = tên
        self.logger = người ghi nhật ký
        self.value = giá trị

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = mới

    chắc chắn get(self) -> T:
        self.log('Nhận ' + repr(self.value))
        trả về self.value

    def log(self, message: str) -> Không có:
        self.logger.info('%s: %s', self.name, tin nhắn)

Cú pháp này chỉ ra rằng lớp LoggedVar được tham số hóa xung quanh một type variable T duy nhất. Điều này cũng làm cho T hợp lệ như một loại trong nội dung lớp.

Các lớp generic kế thừa ngầm từ Generic. Để tương thích với Python 3.11 trở xuống, cũng có thể kế thừa rõ ràng từ Generic để chỉ ra một lớp chung

từ việc gõ nhập TypeVar, Generic

T = TypeVar('T')

lớp LoggedVar(Chung[T]):
    ...

Các lớp chung có các phương thức __class_getitem__(), nghĩa là chúng có thể được tham số hóa trong thời gian chạy (ví dụ: LoggedVar[int] bên dưới):

từ bộ sưu tập.abc nhập Có thể lặp lại

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> Không có:
    cho var trong vars:
        var.set(0)

Một kiểu generic có thể có bất kỳ số lượng biến kiểu nào. Tất cả các loại TypeVar đều được phép làm tham số cho loại chung:

từ việc nhập nhập TypeVar, Generic, Sequence

class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
    ...

OldT = TypeVar('OldT', contravariant=True)
OldB = TypeVar('OldB',bound=Sequence[bytes], covariant=True)
OldS = TypeVar('OldS', int, str)

lớp OldWeirdTrio(Chung[OldT, OldB, OldS]):
    ...

Mỗi đối số biến loại cho Generic phải khác biệt. Do đó, điều này không hợp lệ:

từ việc gõ nhập TypeVar, Generic
...

cặp lớp [M, M]: # SyntaxError
    ...

T = TypeVar('T')

Cặp lớp(Chung[T, T]): # INVALID
    ...

Các lớp chung cũng có thể kế thừa từ các lớp khác:

từ nhập vào bộ sưu tập.abc

lớp LinkedList[T](Có kích thước):
    ...

Khi kế thừa từ các lớp chung, một số tham số loại có thể được sửa

từ bộ sưu tập.abc nhập bản đồ

lớp MyDict[T](Ánh xạ[str, T]):
    ...

Trong trường hợp này MyDict có một tham số duy nhất là T.

Việc sử dụng một lớp chung mà không chỉ định tham số loại sẽ giả định Any cho từng vị trí. Trong ví dụ sau, MyIterable không phải là chung chung mà được kế thừa ngầm từ Iterable[Any]:

từ bộ sưu tập.abc nhập Có thể lặp lại

lớp MyIterable(Iterable): # Same as Iterable[Any]
    ...

Bí danh loại chung do người dùng xác định cũng được hỗ trợ. Ví dụ:

từ bộ sưu tập.abc nhập Có thể lặp lại

gõ Phản hồi [S] = Có thể lặp lại [S] | int

loại # Return ở đây giống với Iterable[str] | int
phản hồi def(truy vấn: str) -> Phản hồi[str]:
    ...

gõ Vec[T] = Iterable[tuple[T, T]]

def inproduct[T: (int, float, complex)](v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]]
    trả về tổng(x*y cho x, y trong v)

Để tương thích ngược, các bí danh loại chung cũng có thể được tạo thông qua một phép gán đơn giản

từ bộ sưu tập.abc nhập Có thể lặp lại
từ việc gõ nhập TypeVar

S = TypeVar("S")
Phản hồi = Có thể lặp lại [S] | int

Thay đổi trong phiên bản 3.7: Generic không còn có siêu dữ liệu tùy chỉnh nữa.

Thay đổi trong phiên bản 3.12: Hỗ trợ cú pháp cho các bí danh chung và loại là tính năng mới trong phiên bản 3.12. Trước đây, các lớp chung phải kế thừa rõ ràng từ Generic hoặc chứa biến kiểu ở một trong các cơ sở của chúng.

Các tổng quát do người dùng định nghĩa cho các biểu thức tham số cũng được hỗ trợ thông qua các biến đặc tả tham số ở dạng [**P]. Hành vi này nhất quán với các biến loại' được mô tả ở trên vì các biến đặc tả tham số được mô-đun typing xử lý như một biến loại chuyên biệt. Một ngoại lệ đối với điều này là danh sách các loại có thể được sử dụng để thay thế ParamSpec:

>>> lớp Z[T, **P]: ... # T là một TypeVar; P là một ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]

Các lớp chung trên ParamSpec cũng có thể được tạo bằng cách sử dụng tính kế thừa rõ ràng từ Generic. Trong trường hợp này, ** không được sử dụng:

từ việc gõ nhập ParamSpec, Generic

P = ParamSpec('P')

lớp Z(Chung[P]):
    ...

Một điểm khác biệt giữa TypeVar và ParamSpec là một biến chung chỉ có một biến thông số tham số sẽ chấp nhận danh sách tham số ở dạng X[[Type1, Type2, ...]] và cả X[Type1, Type2, ...] vì lý do thẩm mỹ. Trong nội bộ, cái sau được chuyển đổi thành cái trước, vì vậy những cái sau là tương đương

>>> lớp X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]

Lưu ý rằng các generic có ParamSpec có thể không có __parameters__ chính xác sau khi thay thế trong một số trường hợp vì chúng chủ yếu nhằm mục đích kiểm tra kiểu tĩnh.

Thay đổi trong phiên bản 3.10: Generic hiện có thể được tham số hóa qua các biểu thức tham số. Xem ParamSpec và PEP 612 để biết thêm chi tiết.

Một lớp chung do người dùng định nghĩa có thể có ABC làm lớp cơ sở mà không có xung đột siêu dữ liệu. Siêu dữ liệu chung không được hỗ trợ. Kết quả của việc tham số hóa tổng quát được lưu vào bộ nhớ đệm và hầu hết các loại trong mô-đun typing đều là hashable và có thể so sánh được về đẳng thức.

Loại `Any`¶

Một loại đặc biệt là Any. Trình kiểm tra loại tĩnh sẽ coi mọi loại là tương thích với Any và Any là tương thích với mọi loại.

Điều này có nghĩa là có thể thực hiện bất kỳ thao tác hoặc lệnh gọi phương thức nào trên giá trị thuộc loại Any và gán nó cho bất kỳ biến nào:

từ việc nhập nhập Bất kỳ

a: Bất kỳ = Không có
a = [] # OK
a = 2 # OK

s: str = ''
s = a # OK

def foo(item: Any) -> int:
    kiểm tra loại # Passes; 'mục' có thể là bất kỳ loại nào,
    # and loại đó có thể có phương thức 'bar'
    item.bar()
    ...

Lưu ý rằng không có kiểm tra loại nào được thực hiện khi gán giá trị loại Any cho loại chính xác hơn. Ví dụ: trình kiểm tra loại tĩnh không báo cáo lỗi khi gán a cho s mặc dù s được khai báo là loại str và nhận giá trị int khi chạy!

Hơn nữa, tất cả các hàm không có kiểu trả về hoặc kiểu tham số sẽ mặc định sử dụng Any:

def di sản_parser(văn bản):
    ...
    trả về dữ liệu

Trình kiểm tra kiểu tĩnh # A sẽ xử lý vấn đề trên
# as có cùng chữ ký với:
def Legacy_parser(text: Any) -> Any:
    ...
    trả về dữ liệu

Hành vi này cho phép Any được sử dụng làm escape hatch khi bạn cần kết hợp mã được nhập động và tĩnh.

So sánh hành vi của Any với hành vi của object. Tương tự như Any, mỗi loại đều là một loại con của object. Tuy nhiên, không giống như Any, điều ngược lại không đúng: object là not một kiểu con của mọi kiểu khác.

Điều đó có nghĩa là khi loại giá trị là object, trình kiểm tra loại sẽ từ chối hầu hết mọi thao tác trên nó và gán nó cho một biến (hoặc sử dụng nó làm giá trị trả về) của loại chuyên biệt hơn là một lỗi loại. Ví dụ:

def hash_a(item: object) -> int:
    kiểm tra loại # Fails; một đối tượng không có phương thức 'ma thuật'.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    kiểm tra loại # Passes
    item.magic()
    ...

Kiểm tra kiểu # Passes, vì ints và strs là các lớp con của đối tượng
hàm băm_a(42)
hash_a("foo")

kiểm tra loại # Passes, vì Any tương thích với tất cả các loại
hàm băm_b(42)
hash_b("foo")

Sử dụng object để chỉ ra rằng một giá trị có thể là bất kỳ loại nào theo cách an toàn về kiểu. Sử dụng Any để chỉ ra rằng một giá trị được nhập động.

Phân nhóm danh nghĩa và cấu trúc¶

Ban đầu PEP 484 định nghĩa hệ thống kiểu tĩnh Python là sử dụng nominal subtyping. Điều này có nghĩa là một lớp A được cho phép trong đó một lớp B được mong đợi khi và chỉ khi A là lớp con của B.

Yêu cầu này trước đây cũng được áp dụng cho các lớp cơ sở trừu tượng, chẳng hạn như Iterable. Vấn đề với cách tiếp cận này là một lớp phải được đánh dấu rõ ràng để hỗ trợ chúng, điều này không giống với Python và không giống như những gì người ta thường làm trong mã Python được gõ động theo thành ngữ. Ví dụ: điều này tuân theo PEP 484:

từ bộ sưu tập.abc nhập Có kích thước, có thể lặp lại, Iterator

Nhóm lớp (Có kích thước, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

PEP 544 giải quyết vấn đề này bằng cách cho phép người dùng viết mã ở trên mà không cần các lớp cơ sở rõ ràng trong định nghĩa lớp, cho phép Bucket được ngầm coi là một kiểu con của cả Sized và Iterable[int] bởi trình kiểm tra kiểu tĩnh. Điều này được gọi là structural subtyping (hoặc gõ vịt tĩnh):

từ bộ sưu tập.abc nhập Iterator, Iterable

Nhóm lớp: # Note: không có lớp cơ sở
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def thu thập(items: Iterable[int]) -> int: ...
kết quả = thu thập (Bucket()) kiểm tra loại # Passes

Hơn nữa, bằng cách phân lớp một lớp đặc biệt Protocol, người dùng có thể xác định các giao thức tùy chỉnh mới để tận hưởng đầy đủ phân nhóm cấu trúc (xem ví dụ bên dưới).

Nội dung mô-đun¶

Mô-đun typing xác định các lớp, hàm và trang trí sau.

Kiểu gõ đặc biệt¶

Các loại đặc biệt¶

Chúng có thể được sử dụng làm loại trong chú thích. Họ không hỗ trợ đăng ký bằng [].

typing.Any¶

Loại đặc biệt cho biết loại không bị ràng buộc.

Mọi loại đều tương thích với Any.
Any tương thích với mọi loại.

Thay đổi trong phiên bản 3.11: Any hiện có thể được sử dụng làm lớp cơ sở. Điều này có thể hữu ích để tránh các lỗi kiểm tra kiểu với các lớp có thể gõ nhẹ ở bất kỳ đâu hoặc có tính năng động cao.

typing.AnyStr¶

Một constrained type variable.

định nghĩa:

AnyStr = TypeVar('AnyStr', str, byte)

AnyStr được sử dụng cho các hàm có thể chấp nhận đối số str hoặc bytes nhưng không thể cho phép cả hai kết hợp với nhau.

Ví dụ:

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    trả về a + b

concat("foo", "bar") # OK, đầu ra có kiểu 'str'
concat(b"foo", b"bar") # OK, đầu ra có loại 'byte'
concat("foo", b"bar") # Error, không thể trộn str và byte

Lưu ý rằng, mặc dù tên của nó, AnyStr không liên quan gì đến loại Any, cũng không có nghĩa là "bất kỳ chuỗi nào". Đặc biệt, AnyStr và str | bytes khác nhau và có các trường hợp sử dụng khác nhau:

# Invalid sử dụng AnyStr:
Biến loại # The chỉ được sử dụng một lần trong chữ ký hàm,
# so không thể được "giải quyết" bằng trình kiểm tra loại
def hello_bad(cond: bool) -> AnyStr:
    quay lại "chào bạn!" nếu có điều kiện khác b"xin chào!"

# The cách chú thích chức năng này tốt hơn:
def hello_proper(cond: bool) -> str | byte:
    quay lại "chào bạn!" nếu có điều kiện khác b"xin chào!"

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.18: Không được dùng nữa để ủng hộ type parameter syntax mới. Sử dụng class A[T: (str, bytes)]: ... thay vì nhập AnyStr. Xem PEP 695 để biết thêm chi tiết.

Trong Python 3.16, AnyStr sẽ bị xóa khỏi typing.__all__ và cảnh báo không dùng nữa sẽ được đưa ra trong thời gian chạy khi nó được truy cập hoặc nhập từ typing. AnyStr sẽ bị xóa khỏi typing trong Python 3.18.

typing.LiteralString¶

Loại đặc biệt chỉ bao gồm các chuỗi ký tự.

Bất kỳ chuỗi ký tự nào cũng tương thích với LiteralString, cũng như một LiteralString khác. Tuy nhiên, một đối tượng được gõ chỉ là str thì không. Một chuỗi được tạo bằng cách soạn các đối tượng được gõ LiteralString cũng được chấp nhận là LiteralString.

Ví dụ:

def run_query(sql: LiteralString) -> Không có:
    ...

người gọi def(arbitrary_string: str, Literal_string: LiteralString) -> Không có:
    run_query("SELECT * FROM sinh viên") # OK
    run_query(literal_string) # OK
    run_query("SELECT * FROM " + Literal_string) # OK
    lỗi trình kiểm tra run_query(arbitrary_string) # type
    run_query(lỗi kiểm tra # type
        f"SELECT * FROM học sinh WHERE tên = {arbitrary_string}"
    )

LiteralString rất hữu ích cho các API nhạy cảm trong đó các chuỗi do người dùng tạo tùy ý có thể gây ra sự cố. Ví dụ: hai trường hợp trên tạo ra lỗi kiểm tra loại có thể dễ bị tấn công chèn SQL.

Xem PEP 675 để biết thêm chi tiết.

Added in version 3.11.

typing.Never¶

typing.NoReturn¶

Never và NoReturn đại diện cho bottom type, một loại không có thành viên.

Chúng có thể được sử dụng để chỉ ra rằng một hàm không bao giờ trả về, chẳng hạn như sys.exit():

từ việc nhập nhập Không bao giờ # or NoReturn

def stop() -> Không bao giờ:
    tăng RuntimeError('không thể nào')

Hoặc để xác định một hàm không bao giờ được gọi vì không có đối số hợp lệ, chẳng hạn như assert_never():

từ việc nhập nhập Không bao giờ # or NoReturn

def never_call_me(arg: Never) -> Không có:
    vượt qua

def int_or_str(arg: int | str) -> Không có:
    lỗi trình kiểm tra never_call_me(arg) # type
    trận đấu đối số:
        trường hợp int():
            print("Đó là int")
        trường hợp str():
            print("Đó là một str")
        trường hợp _:
            never_call_me(arg) # OK, arg thuộc loại Never (hoặc NoReturn)

Never và NoReturn có cùng ý nghĩa trong hệ thống loại và trình kiểm tra loại tĩnh xử lý cả hai như nhau.

Added in version 3.6.2: Đã thêm NoReturn.

Added in version 3.11: Đã thêm Never.

typing.Self¶

Loại đặc biệt để đại diện cho lớp kèm theo hiện tại.

Ví dụ:

từ việc gõ nhập Tự, Reveal_type

lớp Foo:
    def return_self(self) -> Self:
        ...
        tự trở về

lớp SubclassOfFoo(Foo): vượt qua

Reveal_type(Foo().return_self()) loại # Revealed là "Foo"
Reveal_type(SubclassOfFoo().return_self()) loại # Revealed là "SubclassOfFoo"

Chú thích này về mặt ngữ nghĩa tương đương với chú thích sau, mặc dù theo cách ngắn gọn hơn:

từ việc gõ nhập TypeVar

Self = TypeVar("Tự", giới hạn="Foo")

lớp Foo:
    def return_self(self: Self) -> Self:
        ...
        tự trở về

Nói chung, nếu thứ gì đó trả về self, như trong các ví dụ trên, bạn nên sử dụng Self làm chú thích trả về. Nếu Foo.return_self được chú thích là trả về "Foo" thì trình kiểm tra loại sẽ suy ra đối tượng được trả về từ SubclassOfFoo.return_self là thuộc loại Foo chứ không phải SubclassOfFoo.

Các trường hợp sử dụng phổ biến khác bao gồm:

classmethods được sử dụng làm hàm tạo thay thế và trả về các phiên bản của tham số cls.
Chú thích một phương thức __enter__() trả về self.

Bạn không nên sử dụng Self làm chú thích trả về nếu phương thức này không được đảm bảo trả về một phiên bản của lớp con khi lớp đó được phân lớp

Trứng lớp:
    # Self sẽ là chú thích trả lại không chính xác ở đây,
    # as đối tượng được trả về luôn là một phiên bản của Trứng,
    # even trong các lớp con
    def return_eggs(self) -> "Trứng":
        trả về Trứng()

Xem PEP 673 để biết thêm chi tiết.

Added in version 3.11.

typing.TypeAlias¶

Chú thích đặc biệt để khai báo rõ ràng type alias.

Ví dụ:

từ việc nhập import TypeAlias

Hệ số: TypeAlias = list[int]

TypeAlias đặc biệt hữu ích trên các phiên bản Python cũ hơn để chú thích các bí danh sử dụng các tham chiếu chuyển tiếp, vì trình kiểm tra loại khó có thể phân biệt chúng với các phép gán biến thông thường:

từ việc nhập nhập Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Hộp" chưa tồn tại,
# so chúng tôi phải sử dụng dấu ngoặc kép để tham chiếu chuyển tiếp trên Python <3.12.
# Using ``TypeAlias`` cho bộ kiểm tra kiểu biết rằng đây là khai báo bí danh kiểu,
# not gán biến cho một chuỗi.
BoxOfStrings: TypeAlias = "Box[str]"

Hộp lớp(Chung[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

Xem PEP 613 để biết thêm chi tiết.

Added in version 3.10.

Sắp loại bỏ từ phiên bản 3.12: TypeAlias không được dùng nữa vì câu lệnh type, câu lệnh này tạo ra các phiên bản của TypeAliasType và vốn hỗ trợ các tham chiếu chuyển tiếp. Lưu ý rằng mặc dù TypeAlias và TypeAliasType phục vụ các mục đích tương tự và có tên giống nhau, nhưng chúng khác biệt và TypeAliasType không phải là loại trước đây. Việc loại bỏ TypeAlias hiện chưa được lên kế hoạch nhưng người dùng được khuyến khích chuyển sang câu lệnh type.

Các hình thức đặc biệt¶

Chúng có thể được sử dụng làm loại trong chú thích. Tất cả đều hỗ trợ đăng ký bằng [], nhưng mỗi cái đều có một cú pháp riêng.

class typing.Union¶

loại công đoàn; Union[X, Y] tương đương với X | Y và có nghĩa là X hoặc Y.

Để xác định một liên minh, hãy sử dụng ví dụ: Union[int, str] hoặc viết tắt int | str. Nên sử dụng cách viết tắt đó. Chi tiết:

Các đối số phải là loại và phải có ít nhất một loại.
Công đoàn của các công đoàn bị san phẳng, ví dụ:
```
Union[Union[int, str], float] == Union[int, str, float]
```
Tuy nhiên, điều này không áp dụng cho các kết hợp được tham chiếu thông qua bí danh loại, để tránh buộc phải đánh giá TypeAliasType:: cơ bản.
```
gõ A = Union[int, str]
Union[A, float] != Union[int, str, float]
```
Sự kết hợp của một đối số duy nhất biến mất, ví dụ:
```
Union[int] == hàm tạo int # The thực sự trả về int
```

Các đối số dư thừa được bỏ qua, ví dụ:

Union[int, str, int] == Union[int, str] == int | str

Khi so sánh các công đoàn, thứ tự đối số bị bỏ qua, ví dụ::
```
Union[int, str] == Union[str, int]
```
Bạn không thể phân lớp hoặc khởi tạo Union.
Bạn không thể viết Union[X][Y].

Thay đổi trong phiên bản 3.7: Đừng xóa các lớp con rõ ràng khỏi các hợp nhất trong thời gian chạy.

Thay đổi trong phiên bản 3.10: Công đoàn bây giờ có thể được viết là X | Y. Xem union type expressions.

Thay đổi trong phiên bản 3.14: types.UnionType hiện là bí danh của Union và cả Union[int, str] và int | str đều tạo các phiên bản của cùng một lớp. Để kiểm tra xem một đối tượng có phải là Union khi chạy hay không, hãy sử dụng isinstance(obj, Union). Để tương thích với các phiên bản Python trước đó, hãy sử dụng get_origin(obj) is typing.Union or get_origin(obj) is types.UnionType.

typing.Optional¶

Optional[X] tương đương với X | None (hoặc Union[X, None]).

Lưu ý rằng đây không phải là khái niệm giống như đối số tùy chọn, đối số có giá trị mặc định. Đối số tùy chọn có giá trị mặc định không yêu cầu bộ định tính Optional trên chú thích loại của nó chỉ vì nó là tùy chọn. Ví dụ:

def foo(arg: int = 0) -> Không có:
    ...

Mặt khác, nếu cho phép một giá trị rõ ràng là None thì việc sử dụng Optional là phù hợp, cho dù đối số có phải là tùy chọn hay không. Ví dụ:

def foo(arg: Tùy chọn[int] = Không) -> Không:
    ...

Thay đổi trong phiên bản 3.10: Tùy chọn bây giờ có thể được viết là X | None. Xem union type expressions.

typing.Concatenate¶

Hình thức đặc biệt để chú thích các hàm bậc cao hơn.

Concatenate có thể được sử dụng kết hợp với Callable và ParamSpec để chú thích một lệnh gọi có thứ tự cao hơn nhằm thêm, xóa hoặc chuyển đổi các tham số của một lệnh gọi khác. Cách sử dụng có dạng Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]. Concatenate hiện chỉ hợp lệ khi được sử dụng làm đối số đầu tiên cho Callable. Tham số cuối cùng của Concatenate phải là ParamSpec hoặc dấu chấm lửng (...).

Ví dụ: để chú thích một trình trang trí with_lock cung cấp threading.Lock cho hàm được trang trí, Concatenate có thể được sử dụng để chỉ ra rằng with_lock mong đợi một lệnh gọi có thể lấy Lock làm đối số đầu tiên và trả về một lệnh gọi có chữ ký loại khác. Trong trường hợp này, ParamSpec chỉ ra rằng các loại tham số của đối tượng có thể gọi được trả về phụ thuộc vào loại tham số của đối tượng có thể gọi được truyền vào

từ bộ sưu tập.abc nhập Có thể gọi được
từ Khóa nhập luồng
từ cách nhập nhập Ghép nối

# Use khóa này để đảm bảo rằng chỉ có một luồng đang thực thi một chức năng
# at bất cứ lúc nào.
my_lock = Khóa()

def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''Một loại trang trí an toàn có khóa.'''
    def bên trong(*args: P.args, **kwargs: P.kwargs) -> R:
        # Provide khóa làm đối số đầu tiên.
        trả về f(my_lock, *args, **kwargs)
    trở lại bên trong

@with_lock
def sum_threadsafe(lock: Lock, number: list[float]) -> float:
    '''Thêm danh sách các số lại với nhau theo cách an toàn theo chuỗi.'''
    có khóa:
        trả về tổng(số)

# We không cần phải tự mình mở khóa nhờ người trang trí.
sum_threadsafe([1.1, 2.2, 3.3])

Added in version 3.10.

Xem thêm

PEP 612 -- Các biến đặc tả tham số (PEP đã giới thiệu ParamSpec và Concatenate)
ParamSpec
Chú thích các đối tượng có thể gọi được

typing.Literal¶

Biểu mẫu gõ đặc biệt để xác định "loại chữ".

Literal có thể được sử dụng để chỉ ra cho bộ kiểm tra loại rằng đối tượng được chú thích có giá trị tương đương với một trong các giá trị bằng chữ được cung cấp.

Ví dụ:

def xác thực_simple(data: Any) -> Literal[True]: # always trả về True
    ...

gõ Chế độ = Nghĩa đen['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: Mode) -> str:
    ...

open_helper('/some/path', 'r') kiểm tra loại # Passes
open_helper('/other/path', 'typo') # Error trong trình kiểm tra loại

Literal[...] không thể được phân lớp. Trong thời gian chạy, một giá trị tùy ý được phép làm đối số loại cho Literal[...], nhưng trình kiểm tra loại có thể áp đặt các hạn chế. Xem PEP 586 để biết thêm chi tiết về các loại chữ.

Chi tiết bổ sung:

Các đối số phải là giá trị bằng chữ và phải có ít nhất một giá trị.
Các loại Literal lồng nhau được làm phẳng, ví dụ:
```
khẳng định Literal[Literal[1, 2], 3] == Literal[1, 2, 3]
```
Tuy nhiên, điều này không áp dụng cho các loại Literal được tham chiếu thông qua bí danh loại, để tránh buộc phải đánh giá TypeAliasType:: cơ bản.
```
loại A = Nghĩa đen [1, 2]
khẳng định Literal[A, 3] != Literal[1, 2, 3]
```

Các đối số dư thừa được bỏ qua, ví dụ:

khẳng định Nghĩa đen[1, 2, 1] == Nghĩa đen[1, 2]

Khi so sánh các chữ, thứ tự đối số sẽ bị bỏ qua, ví dụ::
```
khẳng định Nghĩa đen[1, 2] == Nghĩa đen[2, 1]
```
Bạn không thể phân lớp hoặc khởi tạo Literal.
Bạn không thể viết Literal[X][Y].

Added in version 3.8.

Thay đổi trong phiên bản 3.9.1: Literal hiện đã loại bỏ các tham số trùng lặp. So sánh đẳng thức của các đối tượng Literal không còn phụ thuộc vào thứ tự nữa. Các đối tượng Literal giờ đây sẽ đưa ra ngoại lệ TypeError trong quá trình so sánh đẳng thức nếu một trong các tham số của chúng không phải là hashable.

typing.ClassVar¶

Cấu trúc kiểu đặc biệt để đánh dấu các biến lớp.

Như đã giới thiệu trong PEP 526, chú thích biến được bao bọc trong ClassVar chỉ ra rằng một thuộc tính nhất định được dự định sử dụng làm biến lớp và không nên đặt trên các phiên bản của lớp đó. Cách sử dụng:

lớp phi thuyền:
    số liệu thống kê: ClassVar[dict[str, int]] = {} biến # class
    sát thương: int = 10 biến # instance

ClassVar chỉ chấp nhận các loại và không thể đăng ký thêm.

ClassVar bản thân nó không phải là một lớp và không nên được sử dụng với isinstance() hoặc issubclass(). ClassVar không thay đổi hành vi thời gian chạy của Python nhưng nó có thể được sử dụng bởi trình kiểm tra loại của bên thứ ba. Ví dụ: trình kiểm tra loại có thể gắn cờ mã sau đây là lỗi

Enterprise_d = Phi thuyền(3000)
Enterprise_d.stats = {} # Error, đặt biến lớp trên ví dụ
Starship.stats = {} # This được rồi

Added in version 3.5.3.

Thay đổi trong phiên bản 3.13: ClassVar hiện có thể được lồng trong Final và ngược lại.

typing.Final¶

Cấu trúc gõ đặc biệt để chỉ ra tên cuối cùng của bộ kiểm tra kiểu.

Tên cuối cùng không thể được gán lại trong bất kỳ phạm vi nào. Tên cuối cùng được khai báo trong phạm vi lớp không thể bị ghi đè trong các lớp con.

Ví dụ:

MAX_SIZE: Cuối cùng = 9000
MAX_SIZE += 1 # Error được báo cáo bởi trình kiểm tra loại

Kết nối lớp:
    TIMEOUT: Cuối cùng[int] = 10

lớp FastConnector (Kết nối):
    TIMEOUT = 1 # Error được báo cáo bởi trình kiểm tra loại

Không có kiểm tra thời gian chạy của các thuộc tính này. Xem PEP 591 để biết thêm chi tiết.

Added in version 3.8.

Thay đổi trong phiên bản 3.13: Final hiện có thể được lồng trong ClassVar và ngược lại.

typing.Required¶

Cấu trúc gõ đặc biệt để đánh dấu phím TypedDict theo yêu cầu.

Điều này chủ yếu hữu ích cho TypedDicts total=False. Xem TypedDict và PEP 655 để biết thêm chi tiết.

Added in version 3.11.

typing.NotRequired¶

Cấu trúc gõ đặc biệt để đánh dấu phím TypedDict có khả năng bị thiếu.

Xem TypedDict và PEP 655 để biết thêm chi tiết.

Added in version 3.11.

typing.ReadOnly¶

Cấu trúc gõ đặc biệt để đánh dấu một mục của TypedDict là chỉ đọc.

Ví dụ:

lớp Phim(TypedDict):
   tiêu đề: ReadOnly[str]
   năm: int

def mutate_movie(m: Movie) -> None:
   m["năm"] = 1999 # allowed
   m["title"] = Lỗi "Ma trận" # typechecker

Không có kiểm tra thời gian chạy cho thuộc tính này.

Xem TypedDict và PEP 705 để biết thêm chi tiết.

Added in version 3.13.

typing.Annotated¶

Biểu mẫu gõ đặc biệt để thêm siêu dữ liệu theo ngữ cảnh cụ thể vào chú thích.

Thêm siêu dữ liệu x vào loại T nhất định bằng cách sử dụng chú thích Annotated[T, x]. Siêu dữ liệu được thêm bằng Annotated có thể được sử dụng bởi các công cụ phân tích tĩnh hoặc trong thời gian chạy. Khi chạy, siêu dữ liệu được lưu trữ trong thuộc tính __metadata__.

Nếu thư viện hoặc công cụ gặp chú thích Annotated[T, x] và không có logic đặc biệt cho siêu dữ liệu thì nó sẽ bỏ qua siêu dữ liệu và chỉ coi chú thích là T. Như vậy, Annotated có thể hữu ích cho mã muốn sử dụng chú thích cho các mục đích bên ngoài hệ thống gõ tĩnh của Python.

Việc sử dụng Annotated[T, x] làm chú thích vẫn cho phép kiểm tra kiểu tĩnh của T, vì trình kiểm tra loại sẽ đơn giản bỏ qua siêu dữ liệu x. Theo cách này, Annotated khác với trình trang trí @no_type_check, trình trang trí này cũng có thể được sử dụng để thêm các chú thích bên ngoài phạm vi của hệ thống gõ nhưng hoàn toàn vô hiệu hóa tính năng kiểm tra kiểu chữ cho một hàm hoặc lớp.

Trách nhiệm về cách diễn giải siêu dữ liệu thuộc về công cụ hoặc thư viện gặp phải chú thích Annotated. Một công cụ hoặc thư viện gặp loại Annotated có thể quét qua các thành phần siêu dữ liệu để xác định xem chúng có đáng quan tâm hay không (ví dụ: sử dụng isinstance()).

Annotated[<type>, <metadata>]

Dưới đây là ví dụ về cách bạn có thể sử dụng Annotated để thêm siêu dữ liệu để nhập chú thích nếu bạn đang thực hiện phân tích phạm vi:

@dataclass
Giá trị lớp:
    lo: int
    xin chào: int

T1 = Đã chú thích[int, ValueRange(-10, 5)]
T2 = Đã chú thích[T1, ValueRange(-20, 3)]

Đối số đầu tiên của Annotated phải là loại hợp lệ. Nhiều phần tử siêu dữ liệu có thể được cung cấp vì Annotated hỗ trợ các đối số biến đổi. Thứ tự của các thành phần siêu dữ liệu được giữ nguyên và quan trọng đối với việc kiểm tra tính bằng nhau:

@dataclass
lớp ctype:
     loại: str

a1 = Chú thích[int, ValueRange(3, 10), ctype("char")]
a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]

khẳng định a1 != a2 # Order có vấn đề

Công cụ sử dụng chú thích sẽ quyết định xem ứng dụng khách có được phép thêm nhiều thành phần siêu dữ liệu vào một chú thích hay không và cách hợp nhất các chú thích đó.

Các loại Annotated lồng nhau được làm phẳng. Thứ tự của các thành phần siêu dữ liệu bắt đầu bằng chú thích trong cùng:

khẳng định Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]

Tuy nhiên, điều này không áp dụng cho các loại Annotated được tham chiếu thông qua bí danh loại, để tránh buộc phải đánh giá TypeAliasType:: cơ bản.

gõ From3To10[T] = Đã chú thích[T, ValueRange(3, 10)]
khẳng định Đã chú thích[From3To10[int], ctype("char")] != Đã chú thích[
   int, ValueRange(3, 10), ctype("char")
]

Các phần tử siêu dữ liệu trùng lặp không bị xóa:

khẳng định Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]

Annotated có thể được sử dụng với các bí danh lồng nhau và chung:

@dataclass
lớp MaxLen:
    giá trị: int

gõ Vec[T] = Chú thích[danh sách[tuple[T, T]], MaxLen(10)]

# When được sử dụng trong chú thích loại, trình kiểm tra loại sẽ xử lý "V" giống như
# zz000zz:
gõ V = Vec[int]

Annotated không thể được sử dụng với TypeVarTuple đã giải nén:

loại Variadic[*Ts] = Annotated[*Ts, Ann1] = Đã chú thích[T1, T2, T3, ..., Ann1] # NOT hợp lệ

trong đó T1, T2, ... là TypeVars. Điều này không hợp lệ vì chỉ có một loại được chuyển đến Chú thích.

Theo mặc định, get_type_hints() loại bỏ siêu dữ liệu khỏi chú thích. Vượt qua include_extras=True để bảo toàn siêu dữ liệu:

>>> từ cách nhập nhập Chú thích, get_type_hints
>>> def func(x: Annotated[int, "metadata"]) -> None: pass
...
>>> get_type_hints(func)
{'x': <class 'int'>, 'return': <class 'NoneType'>}
>>> get_type_hints(func, include_extras=True)
{'x': type.Annotated[int, 'siêu dữ liệu'], 'return': <class 'NoneType'>}

Trong thời gian chạy, siêu dữ liệu được liên kết với loại Annotated có thể được truy xuất thông qua thuộc tính __metadata__:

>>> từ cách nhập nhập Đã chú thích
>>> X = Chú thích[int, "rất", "quan trọng", "siêu dữ liệu"]
>>> X
đang gõ.Annotated[int, 'rất', 'quan trọng', 'siêu dữ liệu']
>>> X.__siêu dữ liệu__
('rất', 'quan trọng', 'siêu dữ liệu')

Nếu bạn muốn truy xuất loại gốc được bao bọc bởi Annotated, hãy sử dụng thuộc tính __origin__:

>>> từ cách nhập nhập Chú thích, get_origin
>>> Mật khẩu = Đã chú thích[str, "bí mật"]
>>> Mật khẩu.__origin__
<lớp 'str'>

Lưu ý rằng việc sử dụng get_origin() sẽ tự trả về Annotated:

>>> get_origin(Mật khẩu)
đánh máy.Chú thích

Xem thêm

PEP 593 - Chức năng linh hoạt và chú thích biến: Zz001zz giới thiệu Annotated với thư viện chuẩn.

Added in version 3.9.

typing.TypeIs¶

Cấu trúc gõ đặc biệt để đánh dấu các hàm vị ngữ kiểu do người dùng xác định.

TypeIs có thể được sử dụng để chú thích kiểu trả về của hàm vị ngữ kiểu do người dùng xác định. TypeIs chỉ chấp nhận một đối số loại duy nhất. Trong thời gian chạy, các hàm được đánh dấu theo cách này sẽ trả về một giá trị boolean và nhận ít nhất một đối số vị trí.

TypeIs nhằm mục đích mang lại lợi ích cho type narrowing -- một kỹ thuật được sử dụng bởi trình kiểm tra kiểu tĩnh để xác định loại biểu thức chính xác hơn trong luồng mã của chương trình. Thông thường, việc thu hẹp loại được thực hiện bằng cách phân tích luồng mã có điều kiện và áp dụng việc thu hẹp cho một khối mã. Biểu thức điều kiện ở đây đôi khi được gọi là "vị ngữ loại":

def is_str(val: str | float):
    # vị từ loại "isinstance"
    nếu isinstance(val, str):
        # Type của ``val`` được thu hẹp thành ``str``
        ...
    khác:
        # Else, loại ``val`` được thu hẹp thành ``float``.
        ...

Đôi khi sẽ thuận tiện hơn khi sử dụng hàm boolean do người dùng định nghĩa làm vị từ kiểu. Hàm như vậy nên sử dụng TypeIs[...] hoặc TypeGuard làm kiểu trả về để cảnh báo người kiểm tra kiểu tĩnh về ý định này. TypeIs thường có hành vi trực quan hơn TypeGuard, nhưng không thể sử dụng nó khi loại đầu vào và đầu ra không tương thích (ví dụ: list[object] với list[int]) hoặc khi hàm không trả về True cho tất cả các phiên bản của loại thu hẹp.

Việc sử dụng -> TypeIs[NarrowedType] sẽ cho trình kiểm tra kiểu tĩnh biết rằng đối với một hàm nhất định:

Giá trị trả về là một boolean.
Nếu giá trị trả về là True, loại đối số của nó là giao điểm của loại ban đầu của đối số và NarrowedType.
Nếu giá trị trả về là False thì loại đối số của nó sẽ được thu hẹp để loại trừ NarrowedType.

Ví dụ:

từ cách gõ import khẳng định_type, cuối cùng, TypeIs

lớp cha mẹ: vượt qua
lớp Con(Parent): đạt
@cuối cùng
lớp Không liên quan: vượt qua

def is_parent(val: object) -> TypeIs[Parent]:
    trả về isinstance(val, Parent)

def run(arg: Child | Không liên quan):
    nếu is_parent(arg):
        # Type của ``arg`` bị thu hẹp đến giao lộ
        # of ``Parent`` và ``Child``, tương đương với
        # zz003zz.
        khẳng định_type(arg, Con)
    khác:
        # Type của ``arg`` được thu hẹp để loại trừ ``Parent``,
        # so chỉ còn lại ``Unrelated``.
        khẳng định_type(arg, Không liên quan)

Kiểu bên trong TypeIs phải nhất quán với kiểu đối số của hàm; nếu không, trình kiểm tra kiểu tĩnh sẽ phát sinh lỗi. Hàm TypeIs được viết không chính xác có thể dẫn đến hoạt động không đúng đắn trong hệ thống loại; trách nhiệm của người dùng là viết các hàm đó theo cách an toàn về kiểu.

Nếu hàm TypeIs là một lớp hoặc phương thức phiên bản thì loại trong TypeIs sẽ ánh xạ tới loại của tham số thứ hai (sau cls hoặc self).

Nói tóm lại, dạng def foo(arg: TypeA) -> TypeIs[TypeB]: ..., có nghĩa là nếu foo(arg) trả về True thì arg là một phiên bản của TypeB và nếu nó trả về False thì đó không phải là một phiên bản của TypeB.

TypeIs cũng hoạt động với các biến loại. Để biết thêm thông tin, hãy xem PEP 742 (Thu hẹp các loại với TypeIs).

Added in version 3.13.

typing.TypeGuard¶

Cấu trúc gõ đặc biệt để đánh dấu các hàm vị ngữ kiểu do người dùng xác định.

Hàm vị ngữ kiểu là các hàm do người dùng định nghĩa trả về xem đối số của chúng có phải là một thể hiện của một kiểu cụ thể hay không. TypeGuard hoạt động tương tự như TypeIs, nhưng có những tác động khác nhau một chút đến hành vi kiểm tra loại (xem bên dưới).

Việc sử dụng -> TypeGuard sẽ cho trình kiểm tra kiểu tĩnh biết rằng đối với một hàm nhất định:

Giá trị trả về là một boolean.
Nếu giá trị trả về là True thì kiểu đối số của nó là kiểu bên trong TypeGuard.

TypeGuard cũng hoạt động với các biến kiểu. Xem PEP 647 để biết thêm chi tiết.

Ví dụ:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''Xác định xem tất cả các đối tượng trong danh sách có phải là chuỗi hay không'''
    trả về tất cả(isinstance(x, str) cho x in val)

def func1(val: list[object]):
    nếu is_str_list(val):
        # Type của ``val`` được thu hẹp thành ``list[str]``.
        print(" ".join(val))
    khác:
        # Type của ``val`` vẫn là ``list[object]``.
        print("Không phải là danh sách các chuỗi!")

TypeIs và TypeGuard khác nhau ở những điểm sau:

TypeIs yêu cầu loại thu hẹp phải là loại phụ của loại đầu vào, trong khi TypeGuard thì không. Lý do chính là để cho phép những thứ như thu hẹp list[object] thành list[str] mặc dù cái sau không phải là một kiểu con của cái trước, vì list là bất biến.
Khi hàm TypeGuard trả về True, bộ kiểm tra loại sẽ thu hẹp loại biến thành loại TypeGuard chính xác. Khi hàm TypeIs trả về True, trình kiểm tra loại có thể suy ra một loại chính xác hơn bằng cách kết hợp loại biến đã biết trước đó với loại TypeIs. (Về mặt kỹ thuật, đây được gọi là loại giao lộ.)
Khi hàm TypeGuard trả về False, trình kiểm tra loại không thể thu hẹp loại biến. Khi hàm TypeIs trả về False, trình kiểm tra loại có thể thu hẹp loại biến để loại trừ loại TypeIs.

Added in version 3.10.

typing.Unpack¶

Toán tử gõ để đánh dấu một cách khái niệm một đối tượng là đã được giải nén.

Ví dụ: sử dụng toán tử giải nén * trên type variable tuple tương đương với việc sử dụng Unpack để đánh dấu bộ biến kiểu là đã được giải nén:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# Effectively thực hiện:
tup: tuple[Giải nén[Ts]]

Trên thực tế, Unpack có thể được sử dụng thay thế cho nhau với * trong bối cảnh loại typing.TypeVarTuple và builtins.tuple. Bạn có thể thấy Unpack được sử dụng rõ ràng trong các phiên bản Python cũ hơn, trong đó * không thể được sử dụng ở một số nơi nhất định:

# In phiên bản cũ hơn của Python, TypeVarTuple và Unpack
# are nằm trong gói backport `typing_extensions`.
từ type_extensions nhập TypeVarTuple, Giải nén

Ts = TypeVarTuple('Ts')
tup: lỗi tuple[*Ts] # Syntax trên Python <= 3.10!
tup: tuple[Unpack[Ts]] # Semantically tương đương và tương thích ngược

Unpack cũng có thể được sử dụng cùng với typing.TypedDict để nhập **kwargs vào chữ ký hàm:

từ việc nhập nhập TypedDict, Giải nén

lớp Phim(TypedDict):
    tên: str
    năm: int

Hàm # This yêu cầu hai đối số từ khóa - `name` thuộc loại `str`
# and `year` thuộc loại `int`.
def foo(**kwargs: Unpack[Phim]): ...

Xem PEP 692 để biết thêm chi tiết về cách sử dụng Unpack để gõ **kwargs.

Added in version 3.11.

Xây dựng các loại chung và bí danh loại¶

Các lớp sau không nên được sử dụng trực tiếp làm chú thích. Mục đích dự định của họ là xây dựng các khối để tạo các loại chung và bí danh loại.

Những đối tượng này có thể được tạo thông qua cú pháp đặc biệt (type parameter lists và câu lệnh type). Để tương thích với Python 3.11 trở về trước, chúng cũng có thể được tạo mà không cần cú pháp chuyên dụng, như được ghi lại bên dưới.

class typing.Generic¶

Lớp cơ sở trừu tượng cho các loại chung.

Loại chung thường được khai báo bằng cách thêm danh sách các tham số loại sau tên lớp

Ánh xạ lớp [KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

Một lớp như vậy kế thừa ngầm từ Generic. Ngữ nghĩa thời gian chạy của cú pháp này được thảo luận trong Language Reference.

Lớp này sau đó có thể được sử dụng như sau:

def lookup_name[X, Y](ánh xạ: Ánh xạ[X, Y], key: X, mặc định: Y) -> Y:
    thử:
        trả về ánh xạ [khóa]
    ngoại trừ KeyError:
        trả về mặc định

Ở đây dấu ngoặc sau tên hàm biểu thị generic function.

Để tương thích ngược, các lớp chung cũng có thể được khai báo bằng cách kế thừa rõ ràng từ Generic. Trong trường hợp này, các tham số kiểu phải được khai báo riêng:

KT = TypeVar('KT')
VT = TypeVar('VT')

Ánh xạ lớp (Chung [KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)¶

Loại biến.

Cách ưa thích để xây dựng một biến loại là thông qua cú pháp dành riêng cho generic functions, generic classes và generic type aliases:

Trình tự lớp [T]: # T là TypeVar
    ...

Cú pháp này cũng có thể được sử dụng để tạo các biến kiểu giới hạn và ràng buộc:

class StrSequence[S: str]: # S là TypeVar có giới hạn trên `str`;
    ... # we có thể nói rằng S bị "giới hạn bởi `str`"


lớp StrOrBytesSequence[A: (str, byte)]: # A là một TypeVar bị ràng buộc ở str hoặc byte
    ...

Tuy nhiên, nếu muốn, các biến loại có thể sử dụng lại cũng có thể được tạo thủ công, như sau:

T = TypeVar('T') # Can là bất cứ thứ gì
S = TypeVar('S',bound=str) # Can là bất kỳ kiểu con nào của str
A = TypeVar('A', str, bytes) # Must chính xác là str hoặc byte

Các biến kiểu tồn tại chủ yếu vì lợi ích của trình kiểm tra kiểu tĩnh. Chúng đóng vai trò là tham số cho các kiểu chung cũng như cho các định nghĩa bí danh kiểu và hàm chung. Xem Generic để biết thêm thông tin về các loại chung. Các hàm chung hoạt động như sau:

def lặp lại [T](x: T, n: int) -> Chuỗi [T]:
    """Trả về danh sách chứa n tham chiếu đến x."""
    trả về [x]*n


def print_capitalized[S: str](x: S) -> S:
    """In x viết hoa và trả về x."""
    print(x.capitalize())
    trả lại x


def concatenate[A: (str, byte)](x: A, y: A) -> A:
    """Thêm hai đối tượng chuỗi hoặc byte lại với nhau."""
    trả về x + y

Lưu ý rằng các biến loại có thể là bounded, constrained hoặc không loại nào, nhưng không thể bị ràng buộc cả hai and.

Phương sai của các biến loại được bộ kiểm tra loại suy ra khi chúng được tạo thông qua type parameter syntax hoặc khi infer_variance=True được truyền. Các biến loại được tạo thủ công có thể được đánh dấu rõ ràng là hiệp biến hoặc trái ngược bằng cách chuyển covariant=True hoặc contravariant=True. Theo mặc định, các biến kiểu được tạo thủ công là bất biến. Xem PEP 484 và PEP 695 để biết thêm chi tiết.

Các biến kiểu bị ràng buộc và các biến kiểu bị ràng buộc có ngữ nghĩa khác nhau theo một số cách quan trọng. Sử dụng biến loại bounded có nghĩa là TypeVar sẽ được giải quyết bằng cách sử dụng loại cụ thể nhất có thể:

x = print_capitalized('một chuỗi')
Reveal_type(x) # revealed loại là str

lớp StringSubclass(str):
    vượt qua

y = print_capitalized(StringSubclass('chuỗi khác'))
loại tiết lộ_type(y) # revealed là StringSubclass

z = print_capitalized(45) # error: int không phải là kiểu con của str

Giới hạn trên của biến loại có thể là loại cụ thể, loại trừu tượng (ABC hoặc Giao thức) hoặc thậm chí là sự kết hợp của các loại:

# Can có thể là bất kỳ thứ gì có phương thức __abs__
def print_abs[T: SupportAbs](arg: T) -> Không có:
    print("Giá trị tuyệt đối:", abs(arg))

U = TypeVar('U', giới hạn=str|bytes)  # Can be any subtype of the union str|bytes
V = TypeVar('V',bound=SupportsAbs) # Can là bất kỳ thứ gì có phương thức __abs__

Tuy nhiên, việc sử dụng biến loại constrained có nghĩa là TypeVar chỉ có thể được giải quyết chính xác như một trong những ràng buộc được đưa ra

a = nối ('một', 'hai')
Reveal_type(a) # revealed loại là str

b = nối (StringSubclass('one'), StringSubclass('two'))
Reveal_type(b) # revealed loại là str, mặc dù StringSubclass được truyền vào

c = concatenate('one', b'two') # error: biến loại 'A' có thể là str hoặc byte trong lệnh gọi hàm, nhưng không phải cả hai

Khi chạy, isinstance(x, T) sẽ tăng TypeError.

__name__¶: Tên của biến loại.

__covariant__¶: Liệu loại var đã được đánh dấu rõ ràng là hiệp biến hay chưa.

__contravariant__¶: Liệu loại var đã được đánh dấu rõ ràng là chống biến thể hay chưa.

__infer_variance__¶: Liệu phương sai của biến loại có nên được suy ra bởi bộ kiểm tra loại hay không.

Added in version 3.12.

__bound__¶: Giới hạn trên của biến loại, nếu có.

Thay đổi trong phiên bản 3.12: Đối với các biến loại được tạo thông qua type parameter syntax, giới hạn chỉ được đánh giá khi thuộc tính được truy cập chứ không phải khi biến loại được tạo (xem Đánh giá lười biếng).

evaluate_bound()¶: Một evaluate function tương ứng với thuộc tính __bound__. Khi được gọi trực tiếp, phương thức này chỉ hỗ trợ định dạng VALUE, tương đương với việc truy cập trực tiếp vào thuộc tính __bound__, nhưng đối tượng phương thức có thể được chuyển tới annotationlib.call_evaluate_function() để đánh giá giá trị ở định dạng khác.

Added in version 3.14.

__constraints__¶: Một bộ chứa các ràng buộc của biến kiểu, nếu có.

Thay đổi trong phiên bản 3.12: Đối với các biến loại được tạo thông qua type parameter syntax, các ràng buộc chỉ được đánh giá khi thuộc tính được truy cập chứ không phải khi biến loại được tạo (xem Đánh giá lười biếng).

evaluate_constraints()¶: Một evaluate function tương ứng với thuộc tính __constraints__. Khi được gọi trực tiếp, phương thức này chỉ hỗ trợ định dạng VALUE, tương đương với việc truy cập trực tiếp vào thuộc tính __constraints__, nhưng đối tượng phương thức có thể được chuyển tới annotationlib.call_evaluate_function() để đánh giá giá trị ở định dạng khác.

Added in version 3.14.

__default__¶: Giá trị mặc định của biến loại hoặc typing.NoDefault nếu nó không có giá trị mặc định.

Added in version 3.13.

evaluate_default()¶: Một evaluate function tương ứng với thuộc tính __default__. Khi được gọi trực tiếp, phương thức này chỉ hỗ trợ định dạng VALUE, tương đương với việc truy cập trực tiếp vào thuộc tính __default__, nhưng đối tượng phương thức có thể được chuyển tới annotationlib.call_evaluate_function() để đánh giá giá trị ở định dạng khác.

Added in version 3.14.

has_default()¶: Trả về xem biến loại có giá trị mặc định hay không. Điều này tương đương với việc kiểm tra xem __default__ có phải là typing.NoDefault singleton hay không, ngoại trừ việc nó không bắt buộc phải đánh giá giá trị mặc định lazily evaluated.

Added in version 3.13.

Thay đổi trong phiên bản 3.12: Giờ đây, các biến loại có thể được khai báo bằng cú pháp type parameter do PEP 695 giới thiệu. Tham số infer_variance đã được thêm vào.

Thay đổi trong phiên bản 3.13: Hỗ trợ cho các giá trị mặc định đã được thêm vào.

class typing.TypeVarTuple(name, *, default=typing.NoDefault)¶

Nhập tuple biến. Một dạng type variable chuyên biệt cho phép tạo ra các generic variadic.

Loại bộ dữ liệu biến có thể được khai báo bằng type parameter lists bằng cách sử dụng một dấu hoa thị (*) trước tên:

def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    trả về (*tup[1:], tup[0])

Hoặc bằng cách gọi hàm tạo TypeVarTuple một cách rõ ràng:

T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    trả về (*tup[1:], tup[0])

Một biến loại bình thường cho phép tham số hóa với một loại duy nhất. Ngược lại, một bộ biến loại arbitrary cho phép tham số hóa với số lượng loại arbitrary bằng cách hoạt động giống như số lượng biến loại arbitrary được gói trong một bộ dữ liệu. Ví dụ:

# T được liên kết với int, Ts được liên kết với ()
Giá trị # Return là (1,), có kiểu tuple[int]
move_first_element_to_last(tup=(1,))

# T được liên kết với int, Ts được liên kết với (str,)
Giá trị # Return là ('spam', 1), có kiểu tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))

# T được liên kết với int, Ts được liên kết với (str, float)
Giá trị # Return là ('spam', 3.0, 1), có kiểu tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))

# This không gõ được kiểm tra (và bị lỗi khi chạy)
# because tuple[()] không tương thích với tuple[T, *Ts]
# (bắt buộc phải có ít nhất một phần tử)
move_first_element_to_last(tup=())

Lưu ý việc sử dụng toán tử giải nén * trong tuple[T, *Ts]. Về mặt khái niệm, bạn có thể coi Ts như một bộ biến kiểu (T1, T2, ...). tuple[T, *Ts] sau đó sẽ trở thành tuple[T, *(T1, T2, ...)], tương đương với tuple[T, T1, T2, ...]. (Lưu ý rằng trong các phiên bản Python cũ hơn, bạn có thể thấy phần này được viết bằng Unpack thay vào đó là Unpack[Ts].)

Loại bộ dữ liệu biến phải always được giải nén. Điều này giúp phân biệt các bộ biến kiểu với các biến kiểu thông thường:

x: Ts # Not hợp lệ
x: tuple[Ts] # Not hợp lệ
x: tuple[*Ts] # The cách làm đúng

Các bộ biến kiểu có thể được sử dụng trong cùng ngữ cảnh với các biến kiểu thông thường. Ví dụ: trong định nghĩa lớp, đối số và kiểu trả về

Mảng lớp [*Hình dạng]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Mảng[*Hình dạng]": ...
    def get_shape(self) -> tuple[*Shape]: ...

Các bộ biến kiểu có thể được kết hợp một cách vui vẻ với các biến kiểu thông thường:

Mảng lớp [DType, *Shape]: # This vẫn ổn
    vượt qua

class Array2[*Shape, DType]: # This cũng sẽ ổn thôi
    vượt qua

Chiều cao lớp: ...
Chiều rộng lớp: ...

float_array_1d: Mảng[float, Height] = Array() # Totally ổn
int_array_2d: Mảng[int, Chiều cao, Chiều rộng] = Array() # Yup, cũng được

Tuy nhiên, lưu ý rằng nhiều nhất một bộ biến kiểu có thể xuất hiện trong một danh sách các đối số kiểu hoặc tham số kiểu

x: tuple[*Ts, *Ts] # Not hợp lệ
Mảng lớp [*Shape, *Shape]: # Not hợp lệ
    vượt qua

Cuối cùng, một bộ biến kiểu đã giải nén có thể được sử dụng làm chú thích kiểu của *args:

chắc chắn call_soon[*Ts](
    gọi lại: Có thể gọi được[[*Ts], Không có],
    *args: *Ts
) -> Không có:
    ...
    gọi lại(*args)

Ngược lại với các chú thích chưa được giải nén của *args - ví dụ: *args: int, sẽ chỉ định rằng các đối số all là int - *args: *Ts cho phép tham chiếu đến các loại đối số individual trong *args. Ở đây, điều này cho phép chúng tôi đảm bảo các loại *args được chuyển đến call_soon khớp với các loại đối số (vị trí) của callback.

Xem PEP 646 để biết thêm chi tiết về các bộ biến kiểu.

__name__¶: Tên của biến kiểu tuple.

__default__¶: Giá trị mặc định của biến kiểu tuple hoặc typing.NoDefault nếu nó không có giá trị mặc định.

Added in version 3.13.

evaluate_default()¶: Một evaluate function tương ứng với thuộc tính __default__. Khi được gọi trực tiếp, phương thức này chỉ hỗ trợ định dạng VALUE, tương đương với việc truy cập trực tiếp vào thuộc tính __default__, nhưng đối tượng phương thức có thể được chuyển tới annotationlib.call_evaluate_function() để đánh giá giá trị ở định dạng khác.

Added in version 3.14.

has_default()¶: Trả về xem biến kiểu tuple có giá trị mặc định hay không. Điều này tương đương với việc kiểm tra xem __default__ có phải là typing.NoDefault singleton hay không, ngoại trừ việc nó không bắt buộc phải đánh giá giá trị mặc định lazily evaluated.

Added in version 3.13.

Added in version 3.11.

Thay đổi trong phiên bản 3.12: Giờ đây, bạn có thể khai báo các bộ dữ liệu biến bằng cách sử dụng cú pháp type parameter do PEP 695 giới thiệu.

Thay đổi trong phiên bản 3.13: Hỗ trợ cho các giá trị mặc định đã được thêm vào.

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False, default=typing.NoDefault)¶

Biến đặc tả tham số. Một phiên bản chuyên dụng của type variables.

Trong type parameter lists, thông số kỹ thuật tham số có thể được khai báo bằng hai dấu hoa thị (**):

gõ IntFunc[**P] = Có thể gọi được[P, int]

Để tương thích với Python 3.11 trở về trước, các đối tượng ParamSpec cũng có thể được tạo như sau

P = ParamSpec('P')

Các biến đặc tả tham số tồn tại chủ yếu vì lợi ích của trình kiểm tra kiểu tĩnh. Chúng được sử dụng để chuyển tiếp các loại tham số của một loại có thể gọi sang một loại có thể gọi khác -- một mẫu thường thấy trong các hàm và trang trí bậc cao hơn. Chúng chỉ hợp lệ khi được sử dụng trong Concatenate hoặc làm đối số đầu tiên cho Callable hoặc làm tham số cho Generics do người dùng xác định. Xem Generic để biết thêm thông tin về các loại chung.

Ví dụ: để thêm tính năng ghi nhật ký cơ bản vào một hàm, người ta có thể tạo trình trang trí add_logging để ghi nhật ký các lệnh gọi hàm. Biến đặc tả tham số cho trình kiểm tra kiểu biết rằng đối tượng có thể gọi được chuyển vào bộ trang trí và đối tượng có thể gọi mới được nó trả về có các tham số loại phụ thuộc lẫn nhau:

từ bộ sưu tập.abc nhập Có thể gọi được
nhập nhật ký

def add_logging[T, **P](f: Có thể gọi được [P, T]) -> Có thể gọi được [P, T]:
    '''Một công cụ trang trí an toàn kiểu để thêm tính năng ghi nhật ký vào một hàm.'''
    def bên trong(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} đã được gọi')
        trả về f(*args, **kwargs)
    trở lại bên trong

@add_logging
def add_two(x: float, y: float) -> float:
    '''Cộng hai số lại với nhau.'''
    trả về x + y

Nếu không có ParamSpec, cách đơn giản nhất để chú thích điều này trước đây là sử dụng TypeVar với giới hạn trên Callable[..., Any]. Tuy nhiên điều này gây ra hai vấn đề:

Trình kiểm tra loại không thể gõ kiểm tra chức năng inner vì *args và **kwargs phải được gõ Any.
cast() có thể được yêu cầu trong phần nội dung của trình trang trí add_logging khi trả về hàm inner hoặc phải yêu cầu trình kiểm tra loại tĩnh bỏ qua return inner.

args¶

kwargs¶: Vì ParamSpec nắm bắt cả thông số vị trí và từ khóa, nên P.args và P.kwargs có thể được sử dụng để chia ParamSpec thành các thành phần của nó. P.args đại diện cho bộ tham số vị trí trong một lệnh gọi nhất định và chỉ nên được sử dụng để chú thích *args. P.kwargs thể hiện việc ánh xạ các tham số từ khóa tới các giá trị của chúng trong một lệnh gọi nhất định và chỉ nên được sử dụng để chú thích **kwargs. Cả hai thuộc tính đều yêu cầu tham số được chú thích phải nằm trong phạm vi. Khi chạy, P.args và P.kwargs lần lượt là các phiên bản của ParamSpecArgs và ParamSpecKwargs.

__name__¶: Tên của thông số kỹ thuật.

__default__¶: Giá trị mặc định của thông số tham số hoặc typing.NoDefault nếu nó không có giá trị mặc định.

Added in version 3.13.

evaluate_default()¶: Một evaluate function tương ứng với thuộc tính __default__. Khi được gọi trực tiếp, phương thức này chỉ hỗ trợ định dạng VALUE, tương đương với việc truy cập trực tiếp vào thuộc tính __default__, nhưng đối tượng phương thức có thể được chuyển tới annotationlib.call_evaluate_function() để đánh giá giá trị ở định dạng khác.

Added in version 3.14.

has_default()¶: Trả về xem đặc tả tham số có giá trị mặc định hay không. Điều này tương đương với việc kiểm tra xem __default__ có phải là typing.NoDefault singleton hay không, ngoại trừ việc nó không bắt buộc phải đánh giá giá trị mặc định lazily evaluated.

Added in version 3.13.

Các biến đặc tả tham số được tạo bằng covariant=True hoặc contravariant=True có thể được sử dụng để khai báo các kiểu chung chung hiệp biến hoặc chống biến thể. Đối số bound cũng được chấp nhận, tương tự như TypeVar. Tuy nhiên, ngữ nghĩa thực sự của những từ khóa này vẫn chưa được quyết định.

Added in version 3.10.

Thay đổi trong phiên bản 3.12: Hiện tại, thông số kỹ thuật của tham số có thể được khai báo bằng cú pháp type parameter do PEP 695 giới thiệu.

Thay đổi trong phiên bản 3.13: Hỗ trợ cho các giá trị mặc định đã được thêm vào.

Ghi chú

Chỉ các biến đặc tả tham số được xác định trong phạm vi toàn cầu mới có thể được chọn.

Xem thêm

PEP 612 -- Các biến đặc tả tham số (PEP đã giới thiệu ParamSpec và Concatenate)
Concatenate
Chú thích các đối tượng có thể gọi được

typing.ParamSpecArgs¶

typing.ParamSpecKwargs¶

Đối số và thuộc tính đối số từ khóa của ParamSpec. Thuộc tính P.args của ParamSpec là một phiên bản của ParamSpecArgs và P.kwargs là một phiên bản của ParamSpecKwargs. Chúng nhằm mục đích xem xét nội tâm thời gian chạy và không có ý nghĩa đặc biệt nào đối với trình kiểm tra kiểu tĩnh.

Gọi get_origin() trên một trong hai đối tượng này sẽ trả về ParamSpec ban đầu:

>>> từ cách nhập nhập ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) là P
đúng
>>> get_origin(P.kwargs) là P
đúng

Added in version 3.10.

class typing.TypeAliasType(name, value, *, type_params=())¶

Loại bí danh được tạo thông qua câu lệnh type.

Ví dụ:

>>> gõ Bí danh = int
>>> loại (Bí danh)
<class 'typing.TypeAliasType'>

Added in version 3.12.

__name__¶

Tên của bí danh loại:

>>> gõ Bí danh = int
>>> Bí danh.__name__
'Bí danh'

__module__¶

Tên của mô-đun trong đó bí danh loại được xác định:

>>> gõ Bí danh = int
>>> Bí danh.__module__
'__chính__'

__type_params__¶

Các tham số loại của bí danh loại hoặc một bộ trống nếu bí danh không chung chung:

>>> gõ ListOrSet[T] = list[T] | đặt [T]
>>> ListOrSet.__type_params__
(T,)
>>> gõ NotGeneric = int
>>> NotGeneric.__type_params__
()

__value__¶

Giá trị của bí danh loại. Đây là lazily evaluated, vì vậy các tên được sử dụng trong định nghĩa bí danh sẽ không được giải quyết cho đến khi thuộc tính __value__ được truy cập:

>>> gõ lẫn nhau = đệ quy
>>> gõ đệ quy = Tương hỗ
>>> Cùng nhau
lẫn nhau
>>> Đệ quy
đệ quy
>>> Tương hỗ.__value__
đệ quy
>>> Đệ quy.__value__
lẫn nhau

evaluate_value()¶

Một evaluate function tương ứng với thuộc tính __value__. Khi được gọi trực tiếp, phương thức này chỉ hỗ trợ định dạng VALUE, tương đương với việc truy cập trực tiếp vào thuộc tính __value__, nhưng đối tượng phương thức có thể được chuyển tới annotationlib.call_evaluate_function() để đánh giá giá trị ở định dạng khác:

>>> gõ Bí danh = không xác định
>>> Bí danh.__value__
Traceback (cuộc gọi gần đây nhất):
...
NameError: tên 'không xác định' không được xác định
>>> từ Định dạng nhập chú thíchlib, call_evaluate_function
>>> Bí danh.evaluate_value(Format.VALUE)
Traceback (cuộc gọi gần đây nhất):
...
NameError: tên 'không xác định' không được xác định
>>> call_evaluate_function(Bí danh.evaluate_value, Format.FORWARDREF)
ForwardRef('không xác định')

Added in version 3.14.

Giải nén

Nhập bí danh hỗ trợ giải nén dấu sao bằng cú pháp *Alias. Điều này tương đương với việc sử dụng Unpack[Alias] trực tiếp:

>>> gõ Bí danh = tuple[int, str]
>>> gõ Unpacked = tuple[bool, *Bí danh]
>>> Giải nén.__value__
tuple[bool, đánh máy.Unpack[Bí danh]]

Added in version 3.14.

Các chỉ thị đặc biệt khác¶

Các hàm và lớp này không nên được sử dụng trực tiếp làm chú thích. Mục đích dự định của chúng là xây dựng các khối để tạo và khai báo các kiểu.

class typing.NamedTuple¶

Phiên bản đánh máy của collections.namedtuple().

Cách sử dụng:

Nhân viên lớp (NamedTuple):
    tên: str
    id: int

Điều này tương đương với:

Nhân viên = bộ sưu tập.namedtuple('Nhân viên', ['tên', 'id'])

Để cung cấp cho một trường một giá trị mặc định, bạn có thể gán cho trường đó trong nội dung lớp

Nhân viên lớp (NamedTuple):
    tên: str
    mã số: int = 3

nhân viên = Nhân viên('Guido')
khẳng định nhân viên.id == 3

Các trường có giá trị mặc định phải đứng sau bất kỳ trường nào không có giá trị mặc định.

Lớp kết quả có một thuộc tính bổ sung __annotations__ đưa ra một lệnh ánh xạ tên trường với các loại trường. (Tên trường nằm trong thuộc tính _fields và các giá trị mặc định nằm trong thuộc tính _field_defaults, cả hai đều là một phần của namedtuple() API.)

Các lớp con NamedTuple cũng có thể có các chuỗi tài liệu và phương thức

Nhân viên lớp (NamedTuple):
    """Đại diện cho một nhân viên."""
    tên: str
    mã số: int = 3

    def __repr__(self) -> str:
        return f'<Nhân viên {self.name}, id={self.id}>'

Các lớp con NamedTuple có thể chung chung:

Nhóm lớp [T](NamedTuple):
    chìa khóa: T
    nhóm: danh sách[T]

Cách sử dụng tương thích ngược:

# For tạo NamedTuple chung trên Python 3.11
T = TypeVar("T")

Nhóm lớp(NamedTuple, Generic[T]):
    chìa khóa: T
    nhóm: danh sách[T]

Cú pháp chức năng # A cũng được hỗ trợ
Nhân viên = NamedTuple('Nhân viên', [('name', str), ('id', int)])

Thay đổi trong phiên bản 3.6: Đã thêm hỗ trợ cho cú pháp chú thích biến PEP 526.

Thay đổi trong phiên bản 3.6.1: Đã thêm hỗ trợ cho các giá trị, phương thức và chuỗi tài liệu mặc định.

Thay đổi trong phiên bản 3.8: Các thuộc tính _field_types và __annotations__ hiện là từ điển thông thường thay vì các phiên bản của OrderedDict.

Thay đổi trong phiên bản 3.9: Đã xóa thuộc tính _field_types để thay thế bằng thuộc tính __annotations__ tiêu chuẩn hơn có cùng thông tin.

Thay đổi trong phiên bản 3.9: NamedTuple bây giờ là một hàm chứ không phải một lớp. Nó vẫn có thể được sử dụng làm lớp cơ sở, như được mô tả ở trên.

Thay đổi trong phiên bản 3.11: Đã thêm hỗ trợ cho các bộ tên chung.

Thay đổi trong phiên bản 3.14: Việc sử dụng super() (và __class__ closure variable) trong các phương thức của lớp con NamedTuple không được hỗ trợ và gây ra lỗi TypeError.

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Cú pháp đối số từ khóa không có giấy tờ để tạo các lớp NamedTuple (NT = NamedTuple("NT", x=int)) không được dùng nữa và sẽ không được phép trong phiên bản 3.15. Thay vào đó hãy sử dụng cú pháp dựa trên lớp hoặc cú pháp chức năng.

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Khi sử dụng cú pháp hàm để tạo lớp NamedTuple, việc không chuyển giá trị cho tham số 'trường' (NT = NamedTuple("NT")) sẽ không được dùng nữa. Việc truyền None tới tham số 'fields' (NT = NamedTuple("NT", None)) cũng không được dùng nữa. Cả hai sẽ không được phép trong Python 3.15. Để tạo lớp NamedTuple có 0 trường, hãy sử dụng class NT(NamedTuple): pass hoặc NT = NamedTuple("NT", []).

class typing.NewType(name, tp)¶

Lớp trợ giúp để tạo distinct types có chi phí thấp.

Một NewType được máy đánh chữ coi là một loại riêng biệt. Tuy nhiên, trong thời gian chạy, việc gọi NewType sẽ trả về đối số của nó không thay đổi.

Cách sử dụng:

UserId = NewType('UserId', int) # Declare NewType "UserId"
first_user = UserId(1) # "UserId" trả về đối số không thay đổi khi chạy

__module__¶: Tên của mô-đun trong đó loại mới được xác định.

__name__¶: Tên của loại mới.

__supertype__¶: Loại mà loại mới dựa trên.

Added in version 3.5.2.

Thay đổi trong phiên bản 3.10: NewType bây giờ là một lớp chứ không phải là một hàm.

class typing.Protocol(Generic)¶

Lớp cơ sở cho các lớp giao thức.

Các lớp giao thức được định nghĩa như sau:

lớp Proto(Giao thức):
    def meth(self) -> int:
        ...

Các lớp như vậy chủ yếu được sử dụng với các trình kiểm tra kiểu tĩnh nhận dạng kiểu con cấu trúc (gõ vịt tĩnh), ví dụ:

lớp C:
    def meth(self) -> int:
        trở về 0

def func(x: Proto) -> int:
    trả về x.meth()

kiểm tra kiểu tĩnh func(C()) # Passes

Xem PEP 544 để biết thêm chi tiết. Các lớp giao thức được trang trí bằng runtime_checkable() (được mô tả sau) hoạt động như các giao thức thời gian chạy có đầu óc đơn giản, chỉ kiểm tra sự hiện diện của các thuộc tính nhất định, bỏ qua các chữ ký loại của chúng. Các lớp giao thức không có trình trang trí này không thể được sử dụng làm đối số thứ hai cho isinstance() hoặc issubclass().

Các lớp giao thức có thể chung chung, ví dụ:

lớp GenProto[T](Giao thức):
    def meth(self) -> T:
        ...

Trong mã cần tương thích với Python 3.11 trở lên, các Giao thức chung có thể được viết như sau

T = TypeVar("T")

lớp GenProto(Giao thức[T]):
    def meth(self) -> T:
        ...

Added in version 3.8.

@typing.runtime_checkable¶

Đánh dấu một lớp giao thức là giao thức thời gian chạy.

Giao thức như vậy có thể được sử dụng với isinstance() và issubclass(). Điều này cho phép kiểm tra cấu trúc đơn giản, rất giống với "one trick ponies" trong collections.abc chẳng hạn như Iterable. Ví dụ:

@runtime_checkable
lớp có thể đóng (Giao thức):
    def đóng (tự): ...

khẳng định isinstance(open('/some/file'), Có thể đóng)

@runtime_checkable
lớp được đặt tên (Giao thức):
    tên: str

nhập luồng
khẳng định isinstance(threading.Thread(name='Bob'), Named)

Trình trang trí này tăng TypeError khi áp dụng cho lớp không có giao thức.

Ghi chú

runtime_checkable() sẽ chỉ kiểm tra sự hiện diện của các phương thức hoặc thuộc tính được yêu cầu chứ không phải chữ ký loại hoặc loại của chúng. Ví dụ: ssl.SSLObject là một lớp, do đó nó vượt qua kiểm tra issubclass() đối với Callable. Tuy nhiên, phương thức ssl.SSLObject.__init__ chỉ tồn tại để đưa ra một TypeError với một thông báo nhiều thông tin hơn, do đó không thể gọi (khởi tạo) ssl.SSLObject.

Ghi chú

Việc kiểm tra isinstance() đối với giao thức có thể kiểm tra thời gian chạy có thể chậm một cách đáng ngạc nhiên so với kiểm tra isinstance() đối với lớp không có giao thức. Hãy cân nhắc sử dụng các thành ngữ thay thế, chẳng hạn như lệnh gọi hasattr() để kiểm tra cấu trúc trong mã nhạy cảm với hiệu suất.

Added in version 3.8.

Thay đổi trong phiên bản 3.12: Việc triển khai nội bộ của isinstance() kiểm tra các giao thức có thể kiểm tra thời gian chạy hiện sử dụng inspect.getattr_static() để tra cứu các thuộc tính (trước đây, hasattr() đã được sử dụng). Do đó, một số đối tượng từng được coi là phiên bản của giao thức có thể kiểm tra thời gian chạy có thể không còn được coi là phiên bản của giao thức đó trên Python 3.12+ và ngược lại. Hầu hết người dùng khó có thể bị ảnh hưởng bởi sự thay đổi này.

Thay đổi trong phiên bản 3.12: Các thành viên của giao thức có thể kiểm tra thời gian chạy hiện được coi là "đóng băng" khi chạy ngay khi lớp được tạo. Các thuộc tính vá khỉ trên giao thức có thể kiểm tra thời gian chạy sẽ vẫn hoạt động nhưng sẽ không có tác động đến việc kiểm tra isinstance() so sánh các đối tượng với giao thức. Xem What's new in Python 3.12 để biết thêm chi tiết.

class typing.TypedDict(dict)¶

Cấu trúc đặc biệt để thêm gợi ý loại vào từ điển. Khi chạy "phiên bản TypedDict" chỉ đơn giản là dicts.

TypedDict khai báo một loại từ điển yêu cầu tất cả các phiên bản của nó có một bộ khóa nhất định, trong đó mỗi khóa được liên kết với một giá trị của một loại nhất quán. Kỳ vọng này không được kiểm tra trong thời gian chạy mà chỉ được thực thi bởi trình kiểm tra loại. Cách sử dụng:

lớp Point2D(TypedDict):
    x: int
    y: int
    nhãn: str

a: Point2D = {'x': 1, 'y': 2, 'nhãn': 'tốt'} # OK
b: Point2D = {'z': 3, 'nhãn': 'xấu'} kiểm tra loại # Fails

khẳng định Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')

Một cách khác để tạo TypedDict là sử dụng cú pháp gọi hàm. Đối số thứ hai phải là dict:

Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})

Cú pháp chức năng này cho phép xác định các khóa không hợp lệ identifiers, ví dụ vì chúng là từ khóa hoặc chứa dấu gạch nối hoặc khi tên khóa không được là mangled như tên riêng thông thường:

# raises Lỗi cú pháp
lớp Point2D(TypedDict):
    in: int # 'in' là một từ khóa
    x-y: int # name có dấu gạch nối

Định nghĩa lớp (TypedDict):
    __lược đồ: str # mangled đến `_Definition__schema`

# OK, cú pháp chức năng
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})
Định nghĩa = TypedDict('Definition', {'__schema': str}) # not đọc sai

Theo mặc định, tất cả các khóa phải có trong TypedDict. Có thể đánh dấu các khóa riêng lẻ là không bắt buộc bằng cách sử dụng NotRequired:

lớp Point2D(TypedDict):
    x: int
    y: int
    nhãn: Không bắt buộc[str]

cú pháp # Alternative
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

Điều này có nghĩa là Point2D TypedDict có thể bỏ qua khóa label.

Theo mặc định, cũng có thể đánh dấu tất cả các khóa là không bắt buộc bằng cách chỉ định tổng cộng False:

lớp Point2D(TypedDict, Total=False):
    x: int
    y: int

cú pháp # Alternative
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, Total=False)

Điều này có nghĩa là Point2D TypedDict có thể bỏ qua bất kỳ phím nào. Trình kiểm tra loại chỉ được yêu cầu hỗ trợ False hoặc True theo nghĩa đen làm giá trị của đối số total. True là mặc định và bắt buộc phải có tất cả các mục được xác định trong nội dung lớp.

Các khóa riêng lẻ của total=False TypedDict có thể được đánh dấu theo yêu cầu bằng cách sử dụng Required:

lớp Point2D(TypedDict, Total=False):
    x: Bắt buộc[int]
    y: Bắt buộc[int]
    nhãn: str

cú pháp # Alternative
Point2D = TypedDict('Point2D', {
    'x': Bắt buộc[int],
    'y': Bắt buộc[int],
    'nhãn': str
}, tổng=Sai)

Loại TypedDict có thể kế thừa từ một hoặc nhiều loại TypedDict khác bằng cách sử dụng cú pháp dựa trên lớp. Cách sử dụng:

lớp Point3D(Point2D):
    z: int

Point3D có ba mục: x, y và z. Nó tương đương với định nghĩa này:

lớp Point3D(TypedDict):
    x: int
    y: int
    z: int

Một TypedDict không thể kế thừa từ một lớp không phải``TypedDict``, ngoại trừ Generic. Ví dụ:

lớp X (TypedDict):
    x: int

lớp Y (TypedDict):
    y: int

lớp Z(đối tượng): vượt qua lớp # A không phải TypedDict

lớp XY(X, Y): đạt # OK

lớp Hz(X, Z): vượt qua # raises TypeError

Một TypedDict có thể chung chung:

Nhóm lớp [T](TypedDict):
    chìa khóa: T
    nhóm: danh sách[T]

Để tạo một TypedDict chung tương thích với Python 3.11 trở xuống, hãy kế thừa rõ ràng từ Generic:

T = TypeVar("T")

Nhóm lớp(TypedDict, Generic[T]):
    chìa khóa: T
    nhóm: danh sách[T]

Một TypedDict có thể được xem xét nội tâm thông qua các chú thích (xem Các phương pháp hay nhất về chú thích để biết thêm thông tin về các phương pháp hay nhất về chú thích), __total__, __required_keys__ và __optional_keys__.

__total__¶

Point2D.__total__ đưa ra giá trị của đối số total. Ví dụ:

>>> từ cách nhập nhập TypedDict
>>> lớp Point2D(TypedDict): đạt
>>> Point2D.__total__
đúng
>>> lớp Point2D(TypedDict, Total=False): đạt
>>> Point2D.__total__
sai
>>> lớp Point3D(Point2D): đậu
>>> Point3D.__total__
đúng

Thuộc tính này phản ánh only giá trị của đối số total đối với lớp TypedDict hiện tại, chứ không phải liệu lớp đó có tổng thể về mặt ngữ nghĩa hay không. Ví dụ: một TypedDict có __total__ được đặt thành True có thể có các khóa được đánh dấu bằng NotRequired hoặc nó có thể kế thừa từ một TypedDict khác có total=False. Vì vậy, nhìn chung tốt hơn nên sử dụng __required_keys__ và __optional_keys__ để xem xét nội tâm.

__required_keys__¶: Added in version 3.9.

__optional_keys__¶

Point2D.__required_keys__ và Point2D.__optional_keys__ trả về các đối tượng frozenset chứa các khóa bắt buộc và không bắt buộc tương ứng.

Các phím được đánh dấu bằng Required sẽ luôn xuất hiện trong __required_keys__ và các phím được đánh dấu bằng NotRequired sẽ luôn xuất hiện trong __optional_keys__.

Để tương thích ngược với Python 3.10 trở xuống, cũng có thể sử dụng tính kế thừa để khai báo cả khóa bắt buộc và khóa không bắt buộc trong cùng một TypedDict. Điều này được thực hiện bằng cách khai báo một TypedDict với một giá trị cho đối số total và sau đó kế thừa từ nó trong một TypedDict khác với một giá trị khác cho total:

>>> lớp Point2D(TypedDict, Total=False):
... x: int
... y: int
...
>>> lớp Point3D(Point2D):
... z: int
...
>>> Point3D.__required_keys__ == Frozenset({'z'})
đúng
>>> Point3D.__Optional_keys__ == Frozenset({'x', 'y'})
đúng

Added in version 3.9.

Ghi chú

Nếu from __future__ import annotations được sử dụng hoặc nếu chú thích được cung cấp dưới dạng chuỗi thì chú thích sẽ không được đánh giá khi TypedDict được xác định. Do đó, quá trình xem xét nội bộ thời gian chạy mà __required_keys__ và __optional_keys__ dựa vào có thể không hoạt động bình thường và giá trị của các thuộc tính có thể không chính xác.

Hỗ trợ cho ReadOnly được phản ánh trong các thuộc tính sau:

__readonly_keys__¶: Một frozenset chứa tên của tất cả các khóa chỉ đọc. Các khóa ở chế độ chỉ đọc nếu chúng mang vòng loại ReadOnly.

Added in version 3.13.

__mutable_keys__¶: Một frozenset chứa tên của tất cả các khóa có thể thay đổi. Các khóa có thể thay đổi nếu chúng không mang vòng loại ReadOnly.

Added in version 3.13.

Xem phần TypedDict trong tài liệu đánh máy để biết thêm ví dụ và quy tắc chi tiết.

Added in version 3.8.

Thay đổi trong phiên bản 3.9: TypedDict bây giờ là một hàm chứ không phải một lớp. Nó vẫn có thể được sử dụng làm lớp cơ sở, như được mô tả ở trên.

Thay đổi trong phiên bản 3.11: Đã thêm hỗ trợ đánh dấu các phím riêng lẻ là Required hoặc NotRequired. Xem PEP 655.

Thay đổi trong phiên bản 3.11: Đã thêm hỗ trợ cho TypedDicts chung.

Thay đổi trong phiên bản 3.13: Đã xóa hỗ trợ cho phương thức đối số từ khóa để tạo TypedDicts.

Thay đổi trong phiên bản 3.13: Hỗ trợ cho vòng loại ReadOnly đã được thêm vào.

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Khi sử dụng cú pháp chức năng để tạo lớp TypedDict, việc không chuyển giá trị cho tham số 'trường' (TD = TypedDict("TD")) sẽ không được dùng nữa. Việc truyền None tới tham số 'fields' (TD = TypedDict("TD", None)) cũng không được dùng nữa. Cả hai sẽ không được phép trong Python 3.15. Để tạo lớp TypedDict có 0 trường, hãy sử dụng class TD(TypedDict): pass hoặc TD = TypedDict("TD", {}).

Giao thức¶

Các giao thức sau được cung cấp bởi mô-đun typing. Tất cả đều được trang trí bằng @runtime_checkable.

class typing.SupportsAbs¶: Một ABC với một phương thức trừu tượng __abs__ có kiểu trả về hiệp biến.

class typing.SupportsBytes¶: Một ABC với một phương thức trừu tượng __bytes__.

class typing.SupportsComplex¶: Một ABC với một phương thức trừu tượng __complex__.

class typing.SupportsFloat¶: Một ABC với một phương thức trừu tượng __float__.

class typing.SupportsIndex¶: Một ABC với một phương thức trừu tượng __index__.

Added in version 3.8.

class typing.SupportsInt¶: Một ABC với một phương thức trừu tượng __int__.

class typing.SupportsRound¶: Một ABC với một phương thức trừu tượng __round__ có kiểu trả về hiệp biến.

ABC và các giao thức để làm việc với I/O¶

class typing.IO[AnyStr]¶
class typing.TextIO¶
class typing.BinaryIO¶: Lớp chung IO[AnyStr] và các lớp con TextIO(IO[str]) và BinaryIO(IO[bytes]) của nó đại diện cho các loại luồng I/O như được trả về bởi open(). Xin lưu ý rằng các lớp này không phải là giao thức và giao diện của chúng khá rộng.

Các giao thức io.Reader và io.Writer cung cấp một giải pháp thay thế đơn giản hơn cho các loại đối số, khi chỉ truy cập các phương thức read() hoặc write() tương ứng:

def read_and_write(reader: Reader[str], writer: Writer[byte]):
    dữ liệu = reader.read()
    writer.write(data.encode())

Ngoài ra, hãy cân nhắc sử dụng collections.abc.Iterable để lặp qua các dòng của luồng đầu vào

def read_config(stream: Iterable[str]):
    cho dòng trong luồng:
        ...

Chức năng và trang trí¶

typing.cast(typ, val)¶

Truyền một giá trị cho một loại.

Điều này trả về giá trị không thay đổi. Đối với trình kiểm tra kiểu, điều này báo hiệu rằng giá trị trả về có kiểu được chỉ định, nhưng trong thời gian chạy, chúng tôi cố tình không kiểm tra bất kỳ thứ gì (chúng tôi muốn việc này nhanh nhất có thể).

typing.assert_type(val, typ, /)¶

Hãy yêu cầu trình kiểm tra loại tĩnh để xác nhận rằng val có loại typ được suy ra.

Trong thời gian chạy, điều này không làm gì cả: nó trả về đối số đầu tiên không thay đổi mà không có kiểm tra hoặc tác dụng phụ, bất kể loại đối số thực tế là gì.

Khi trình kiểm tra kiểu tĩnh gặp lệnh gọi tới assert_type(), nó sẽ phát ra lỗi nếu giá trị không thuộc loại được chỉ định

def hello(name: str) -> Không có:
    khẳng định_type(name, str) # OK, loại `name` suy ra là `str`
    lỗi kiểm tra khẳng định_type(name, int) # type

Chức năng này hữu ích để đảm bảo sự hiểu biết của người kiểm tra loại về tập lệnh phù hợp với ý định của nhà phát triển:

def complex_function(arg: object):
    # Do một số logic thu hẹp loại phức tạp,
    # after mà chúng tôi hy vọng loại được suy ra sẽ là `int`
    ...
    # Test liệu trình kiểm tra loại có hiểu chính xác chức năng của chúng tôi không
    khẳng định_type(arg, int)

Added in version 3.11.

typing.assert_never(arg, /)¶

Yêu cầu người kiểm tra loại tĩnh xác nhận rằng một dòng mã không thể truy cập được.

Ví dụ:

def int_or_str(arg: int | str) -> Không có:
    trận đấu đối số:
        trường hợp int():
            print("Đó là int")
        trường hợp str():
            print("Đó là một str")
        trường hợp _ là không thể truy cập được:
            khẳng định_never (không thể truy cập)

Ở đây, các chú thích cho phép trình kiểm tra loại suy ra rằng trường hợp cuối cùng không bao giờ có thể thực thi, bởi vì arg là int hoặc str và cả hai tùy chọn đều được bao gồm trong các trường hợp trước đó.

Nếu trình kiểm tra loại phát hiện thấy có thể truy cập được lệnh gọi tới assert_never(), nó sẽ phát ra lỗi. Ví dụ: nếu chú thích loại cho arg thay vào đó là int | str | float, trình kiểm tra loại sẽ phát ra lỗi chỉ ra rằng unreachable thuộc loại float. Để lệnh gọi tới assert_never vượt qua quá trình kiểm tra loại, loại đối số được suy ra được truyền vào phải là loại dưới cùng, Never và không có gì khác.

Trong thời gian chạy, điều này sẽ đưa ra một ngoại lệ khi được gọi.

Xem thêm

Unreachable Code and Exhaustiveness Checking có thêm thông tin về việc kiểm tra tính toàn diện bằng cách gõ tĩnh.

Added in version 3.11.

typing.reveal_type(obj, /)¶

Yêu cầu trình kiểm tra kiểu tĩnh để tìm ra kiểu biểu thức được suy ra.

Khi trình kiểm tra kiểu tĩnh gặp lệnh gọi hàm này, nó sẽ đưa ra chẩn đoán với kiểu đối số được suy ra. Ví dụ:

x: int = 1
Reveal_type(x) # Revealed loại là "buildins.int"

Điều này có thể hữu ích khi bạn muốn gỡ lỗi cách trình kiểm tra loại của bạn xử lý một đoạn mã cụ thể.

Khi chạy, hàm này in kiểu thời gian chạy của đối số của nó thành sys.stderr và trả về đối số không thay đổi (cho phép lệnh gọi được sử dụng trong một biểu thức):

x = Reveal_type(1) # prints "Loại thời gian chạy là int"
print(x) # prints "1"

Lưu ý rằng loại thời gian chạy có thể khác với (cụ thể hơn hoặc ít hơn) loại được bộ kiểm tra loại suy ra tĩnh.

Hầu hết các trình kiểm tra loại đều hỗ trợ reveal_type() ở mọi nơi, ngay cả khi tên không được nhập từ typing. Tuy nhiên, việc nhập tên từ typing cho phép mã của bạn chạy mà không gặp lỗi thời gian chạy và truyền đạt ý định rõ ràng hơn.

Added in version 3.11.

@typing.dataclass_transform(*, eq_default=True, order_default=False, kw_only_default=False, frozen_default=False, field_specifiers=(), **kwargs)¶

Công cụ trang trí để đánh dấu một đối tượng có hành vi giống dataclass.

dataclass_transform có thể được sử dụng để trang trí một lớp, siêu dữ liệu hoặc một hàm mà bản thân nó là một công cụ trang trí. Sự hiện diện của @dataclass_transform() cho trình kiểm tra kiểu tĩnh biết rằng đối tượng được trang trí thực hiện "ma thuật" thời gian chạy để biến đổi một lớp theo cách tương tự như @dataclasses.dataclass.

Ví dụ sử dụng với chức năng trang trí:

@dataclass_transform()
def create_model[T](cls: type[T]) -> type[T]:
    ...
    trả lại cl

@create_model
lớp Model khách hàng:
    id: int
    tên: str

Trên một lớp cơ sở:

@dataclass_transform()
lớp ModelBase: ...

lớp Khách hàngModel(ModelBase):
    id: int
    tên: str

Trên siêu dữ liệu

@dataclass_transform()
lớp ModelMeta(loại): ...

lớp ModelBase(metaclass=ModelMeta): ...

lớp Khách hàngModel(ModelBase):
    id: int
    tên: str

Các lớp CustomerModel được xác định ở trên sẽ được xử lý bằng trình kiểm tra loại tương tự như các lớp được tạo bằng @dataclasses.dataclass. Ví dụ: trình kiểm tra kiểu sẽ cho rằng các lớp này có các phương thức __init__ chấp nhận id và name.

Lớp, siêu dữ liệu hoặc hàm được trang trí có thể chấp nhận các đối số bool sau đây mà trình kiểm tra loại sẽ cho rằng có tác dụng tương tự như chúng có trên trình trang trí @dataclasses.dataclass: init, eq, order, unsafe_hash, frozen, match_args, kw_only và slots. Giá trị của các đối số này (True hoặc False) phải được đánh giá tĩnh.

Các đối số cho trình trang trí dataclass_transform có thể được sử dụng để tùy chỉnh các hành vi mặc định của lớp, siêu dữ liệu hoặc hàm được trang trí:

Tham số:

eq_default (bool) -- Cho biết tham số eq được coi là True hay False nếu nó bị người gọi bỏ qua. Mặc định là True.
order_default (bool) -- Cho biết tham số order được coi là True hay False nếu nó bị người gọi bỏ qua. Mặc định là False.
kw_only_default (bool) -- Cho biết tham số kw_only được coi là True hay False nếu nó bị người gọi bỏ qua. Mặc định là False.
frozen_default (bool) -- Cho biết tham số frozen được coi là True hay False nếu nó bị người gọi bỏ qua. Mặc định là False. .. phiên bản đã thêm:: 3.12
field_specifiers (tuple[Callable[..., Any], ...]) -- Chỉ định danh sách tĩnh các lớp hoặc hàm được hỗ trợ mô tả các trường, tương tự như dataclasses.field(). Mặc định là ().
**kwargs (Any) -- Các đối số từ khóa tùy ý khác được chấp nhận để cho phép mở rộng trong tương lai.

Trình kiểm tra loại nhận ra các tham số tùy chọn sau trên bộ xác định trường:

**Recognised parameters for field specifiers**¶
Tên tham số	Mô tả
`init`	Cho biết liệu trường có nên được đưa vào phương pháp `__init__` tổng hợp hay không. Nếu không được chỉ định, `init` mặc định là `True`.
`default`	Cung cấp giá trị mặc định cho trường này.
`default_factory`	Cung cấp lệnh gọi lại thời gian chạy trả về giá trị mặc định cho trường. Nếu cả `default` và `default_factory` đều không được chỉ định thì trường này được coi là không có giá trị mặc định và phải được cung cấp một giá trị khi lớp được khởi tạo.
`factory`	Bí danh cho tham số `default_factory` trên bộ chỉ định trường.
`kw_only`	Cho biết liệu trường này có nên được đánh dấu là chỉ có từ khóa hay không. Nếu `True`, trường sẽ chỉ có từ khóa. Nếu `False`, nó sẽ không chỉ có từ khóa. Nếu không được chỉ định, giá trị của tham số `kw_only` trên đối tượng được trang trí bằng `dataclass_transform` sẽ được sử dụng hoặc nếu giá trị đó không được chỉ định, giá trị của `kw_only_default` trên `dataclass_transform` sẽ được sử dụng.
`alias`	Cung cấp tên thay thế cho trường này. Tên thay thế này được sử dụng trong phương pháp `__init__` tổng hợp.

Trong thời gian chạy, trình trang trí này ghi lại các đối số của nó trong thuộc tính __dataclass_transform__ trên đối tượng được trang trí. Nó không có hiệu ứng thời gian chạy khác.

Xem PEP 681 để biết thêm chi tiết.

Added in version 3.11.

@typing.overload¶

Công cụ trang trí để tạo các hàm và phương thức quá tải.

Trình trang trí @overload cho phép mô tả các hàm và phương thức hỗ trợ nhiều tổ hợp loại đối số khác nhau. Một loạt các định nghĩa được trang trí bằng @overload phải được theo sau bởi chính xác một định nghĩa không được trang trí bằng @overload (cho cùng một hàm/phương thức).

Các định nghĩa được trang trí bằng @overload chỉ nhằm mục đích phục vụ lợi ích của trình kiểm tra loại vì chúng sẽ bị ghi đè bởi định nghĩa không được trang trí bằng @overload. Trong khi đó, định nghĩa không được trang trí bằng @overload sẽ được sử dụng trong thời gian chạy nhưng sẽ bị trình kiểm tra loại bỏ qua. Trong thời gian chạy, việc gọi trực tiếp hàm được trang trí @overload sẽ tăng NotImplementedError.

Một ví dụ về tình trạng quá tải cung cấp một loại chính xác hơn mức có thể được biểu thị bằng cách sử dụng biến kết hợp hoặc biến loại:

@overload
quá trình def (phản hồi: Không) -> Không:
    ...
@overload
quá trình def(phản hồi: int) -> tuple[int, str]:
    ...
@overload
quá trình def(phản hồi: byte) -> str:
    ...
quá trình def (phản hồi):
    ... triển khai # actual ở đây

Xem PEP 484 để biết thêm chi tiết và so sánh với các ngữ nghĩa gõ khác.

Thay đổi trong phiên bản 3.11: Giờ đây, các hàm quá tải có thể được xem xét nội bộ trong thời gian chạy bằng get_overloads().

typing.get_overloads(func)¶

Trả về một chuỗi các định nghĩa được trang trí bằng @overload cho func.

func là đối tượng hàm để thực hiện hàm quá tải. Ví dụ: với định nghĩa về process trong tài liệu dành cho @overload, get_overloads(process) sẽ trả về một chuỗi gồm ba đối tượng hàm cho ba tình trạng quá tải được xác định. Nếu được gọi trên một hàm không bị quá tải, get_overloads() sẽ trả về một chuỗi trống.

get_overloads() có thể được sử dụng để xem xét một hàm bị quá tải trong thời gian chạy.

Added in version 3.11.

typing.clear_overloads()¶

Xóa tất cả tình trạng quá tải đã đăng ký trong sổ đăng ký nội bộ.

Điều này có thể được sử dụng để lấy lại bộ nhớ được cơ quan đăng ký sử dụng.

Added in version 3.11.

@typing.final¶

Trang trí để chỉ ra các phương thức cuối cùng và các lớp cuối cùng.

Việc trang trí một phương thức bằng @final cho trình kiểm tra loại biết rằng phương thức đó không thể bị ghi đè trong một lớp con. Trang trí một lớp bằng @final chỉ ra rằng nó không thể được phân lớp.

Ví dụ:

lớp cơ sở:
    @cuối cùng
    def done(self) -> Không có:
        ...
lớp phụ (Cơ sở):
    def done(self) -> Không có: # Error được báo cáo bởi trình kiểm tra loại
        ...

@cuối cùng
Lá lớp:
    ...
lớp Khác(Lá): # Error được báo cáo bởi trình kiểm tra loại
    ...

Không có kiểm tra thời gian chạy của các thuộc tính này. Xem PEP 591 để biết thêm chi tiết.

Added in version 3.8.

Thay đổi trong phiên bản 3.11: Trình trang trí bây giờ sẽ cố gắng đặt thuộc tính __final__ thành True trên đối tượng được trang trí. Do đó, một kiểm tra như if getattr(obj, "__final__", False) có thể được sử dụng trong thời gian chạy để xác định xem một đối tượng obj có được đánh dấu là cuối cùng hay không. Nếu đối tượng được trang trí không hỗ trợ cài đặt thuộc tính, trình trang trí sẽ trả về đối tượng không thay đổi mà không đưa ra ngoại lệ.

@typing.no_type_check¶

Trang trí để chỉ ra rằng các chú thích không phải là gợi ý về loại.

Điều này hoạt động như một lớp hoặc hàm decorator. Với một lớp, nó áp dụng đệ quy cho tất cả các phương thức và lớp được định nghĩa trong lớp đó (nhưng không áp dụng cho các phương thức được định nghĩa trong các siêu lớp hoặc lớp con của nó). Trình kiểm tra loại sẽ bỏ qua tất cả các chú thích trong một hàm hoặc lớp với trình trang trí này.

@no_type_check làm thay đổi đối tượng được trang trí tại chỗ.

@typing.no_type_check_decorator¶

Công cụ trang trí để cung cấp cho một công cụ trang trí khác hiệu ứng no_type_check().

Điều này bao bọc bộ trang trí bằng thứ gì đó bao bọc chức năng được trang trí trong no_type_check().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Chưa có trình kiểm tra loại nào hỗ trợ thêm cho @no_type_check_decorator. Do đó, nó không được dùng nữa và sẽ bị xóa trong Python 3.15.

@typing.override¶

Công cụ trang trí để chỉ ra rằng một phương thức trong lớp con nhằm mục đích ghi đè một phương thức hoặc thuộc tính trong lớp cha.

Trình kiểm tra loại sẽ phát ra lỗi nếu một phương thức được trang trí bằng @override trên thực tế không ghi đè bất kỳ thứ gì. Điều này giúp ngăn ngừa các lỗi có thể xảy ra khi lớp cơ sở được thay đổi mà không có thay đổi tương đương với lớp con.

Ví dụ:

lớp cơ sở:
    def log_status(self) -> Không có:
        ...

lớp phụ (Cơ sở):
    @override
    def log_status(self) -> Không có: # Okay: ghi đè Base.log_status
        ...

    @override
    def done(self) -> Không có: # Error được báo cáo bởi trình kiểm tra loại
        ...

Không có kiểm tra thời gian chạy của thuộc tính này.

Trình trang trí sẽ cố gắng đặt thuộc tính __override__ thành True trên đối tượng được trang trí. Do đó, một kiểm tra như if getattr(obj, "__override__", False) có thể được sử dụng trong thời gian chạy để xác định xem một đối tượng obj có được đánh dấu là ghi đè hay không. Nếu đối tượng được trang trí không hỗ trợ cài đặt thuộc tính, trình trang trí sẽ trả về đối tượng không thay đổi mà không đưa ra ngoại lệ.

Xem PEP 698 để biết thêm chi tiết.

Added in version 3.12.

@typing.type_check_only¶

Công cụ trang trí để đánh dấu một lớp hoặc hàm là không khả dụng khi chạy.

Bản thân trang trí này không có sẵn trong thời gian chạy. Nó chủ yếu nhằm mục đích đánh dấu các lớp được định nghĩa trong các tệp sơ khai kiểu nếu việc triển khai trả về một thể hiện của một lớp riêng

@type_check_only
Phản hồi của lớp: # private hoặc không có sẵn khi chạy
    Mã số: int
    def get_header(self, name: str) -> str: ...

def tìm nạp_response() -> Phản hồi: ...

Lưu ý rằng không nên trả lại các phiên bản của lớp riêng. Thông thường nên công khai các lớp như vậy.

Người giúp đỡ nội tâm¶

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)¶

Trả về một từ điển chứa gợi ý kiểu cho một hàm, phương thức, mô-đun, đối tượng lớp hoặc đối tượng có thể gọi khác.

Điều này thường giống với obj.__annotations__, nhưng chức năng này thực hiện những thay đổi sau đối với từ điển chú thích:

Các tham chiếu chuyển tiếp được mã hóa dưới dạng chuỗi ký tự hoặc đối tượng ForwardRef được xử lý bằng cách đánh giá chúng trong không gian tên type parameter của globalns, localns và (nếu có). Nếu globalns hoặc localns không được cung cấp, từ điển không gian tên thích hợp sẽ được suy ra từ obj.
None được thay thế bằng types.NoneType.
Nếu @no_type_check đã được áp dụng cho obj, một từ điển trống sẽ được trả về.
Nếu obj là một lớp C, thì hàm trả về một từ điển hợp nhất trực tiếp các chú thích từ các lớp cơ sở của C với các chú thích trên C. Điều này được thực hiện bằng cách duyệt qua C.__mro__ và kết hợp lặp đi lặp lại các từ điển __annotations__. Chú thích trên các lớp xuất hiện trước đó trong method resolution order luôn được ưu tiên hơn các chú thích trên các lớp xuất hiện sau theo thứ tự phân giải phương thức.
Hàm này thay thế đệ quy tất cả các lần xuất hiện của Annotated[T, ...], Required[T], NotRequired[T] và ReadOnly[T] bằng T, trừ khi include_extras được đặt thành True (xem Annotated để biết thêm thông tin).

Xem thêm annotationlib.get_annotations(), một hàm cấp thấp hơn trả về các chú thích trực tiếp hơn.

Cảnh báo

Hàm này có thể thực thi mã tùy ý có trong chú thích. Xem Ý nghĩa bảo mật của các chú thích nội tâm để biết thêm thông tin.

Ghi chú

Nếu bất kỳ tham chiếu chuyển tiếp nào trong chú thích của obj không thể phân giải được hoặc không phải là mã Python hợp lệ, thì hàm này sẽ đưa ra một ngoại lệ, chẳng hạn như NameError. Ví dụ: điều này có thể xảy ra với type aliases đã nhập bao gồm các tham chiếu chuyển tiếp hoặc với các tên được nhập theo if TYPE_CHECKING.

Ghi chú

Gọi get_type_hints() trên một phiên bản không được hỗ trợ. Để truy xuất các chú thích cho một phiên bản, thay vào đó hãy gọi get_type_hints() trên lớp của phiên bản đó (ví dụ: get_type_hints(type(obj))).

Thay đổi trong phiên bản 3.9: Đã thêm tham số include_extras như một phần của PEP 593. Xem tài liệu trên Annotated để biết thêm thông tin.

Thay đổi trong phiên bản 3.11: Trước đây, Optional[t] đã được thêm vào cho các chú thích hàm và phương thức nếu giá trị mặc định bằng None được đặt. Bây giờ chú thích được trả về không thay đổi.

Thay đổi trong phiên bản 3.14: Gọi get_type_hints() trên các phiên bản không còn được hỗ trợ. Một số trường hợp đã được chấp nhận trong các phiên bản trước dưới dạng chi tiết triển khai không có giấy tờ.

typing.get_origin(tp)¶

Lấy phiên bản chưa được đăng ký của một loại: đối với đối tượng gõ có dạng X[Y, Z, ...] trả về X.

Nếu X là bí danh mô-đun gõ cho lớp dựng sẵn hoặc collections, thì nó sẽ được chuẩn hóa thành lớp ban đầu. Nếu X là một phiên bản của ParamSpecArgs hoặc ParamSpecKwargs, hãy trả về ParamSpec cơ bản. Trả về None cho các đối tượng không được hỗ trợ.

Ví dụ:

khẳng định get_origin(str) là Không có
khẳng định get_origin(Dict[str, int]) là dict
khẳng định get_origin(Union[int, str]) là Union
khẳng định get_origin(Annotated[str, "metadata"]) được chú thích
P = ParamSpec('P')
khẳng định get_origin(P.args) là P
khẳng định get_origin(P.kwargs) là P

Added in version 3.8.

typing.get_args(tp)¶

Nhận đối số kiểu với tất cả các thay thế được thực hiện: đối với đối tượng gõ có dạng X[Y, Z, ...] trả về (Y, Z, ...).

Nếu X là một liên kết hoặc Literal chứa trong một loại chung khác, thì thứ tự của (Y, Z, ...) có thể khác với thứ tự của các đối số ban đầu [Y, Z, ...] do loại bộ nhớ đệm. Trả về () cho các đối tượng không được hỗ trợ.

Ví dụ:

khẳng định get_args(int) == ()
khẳng định get_args(Dict[int, str]) == (int, str)
khẳng định get_args(Union[int, str]) == (int, str)

Added in version 3.8.

typing.get_protocol_members(tp)¶

Trả về tập hợp các thành viên được xác định trong Protocol.

>>> từ việc nhập Giao thức nhập, get_protocol_members
>>> lớp P(Giao thức):
... def a(self) -> str: ...
... b: int
>>> get_protocol_members(P) == Frozenset({'a', 'b'})
đúng

Tăng TypeError cho các đối số không phải là Giao thức.

Added in version 3.13.

typing.is_protocol(tp)¶

Xác định xem một loại có phải là Protocol hay không.

Ví dụ:

lớp P (Giao thức):
    def a(self) -> str: ...
    b: int

is_protocol(P) # => Đúng
is_protocol(int) # => Sai

Added in version 3.13.

typing.is_typeddict(tp)¶

Kiểm tra xem loại có phải là TypedDict không.

Ví dụ:

Lớp phim (TypedDict):
    tiêu đề: str
    năm: int

khẳng định is_typeddict(Phim)
khẳng định không phải is_typeddict(list | str)

# TypedDict là một nhà máy để tạo các ký tự đã nhập,
# not một bản chính tả được gõ
khẳng định không phải is_typeddict(TypedDict)

Added in version 3.10.

class typing.ForwardRef¶

Lớp được sử dụng để biểu diễn kiểu gõ nội bộ của các tham chiếu chuyển tiếp chuỗi.

Ví dụ: List["SomeClass"] được ngầm chuyển thành List[ForwardRef("SomeClass")]. Người dùng không nên khởi tạo ForwardRef nhưng có thể được sử dụng bởi các công cụ xem xét nội tâm.

Ghi chú

PEP 585 các loại chung như list["SomeClass"] sẽ không được chuyển hoàn toàn thành list[ForwardRef("SomeClass")] và do đó sẽ không tự động phân giải thành list[SomeClass].

Added in version 3.7.4.

Thay đổi trong phiên bản 3.14: Đây hiện là bí danh của annotationlib.ForwardRef. Một số hành vi không có giấy tờ của lớp này đã được thay đổi; ví dụ: sau khi ForwardRef được đánh giá, giá trị được đánh giá không còn được lưu vào bộ nhớ đệm nữa.

typing.evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE)¶

Đánh giá annotationlib.ForwardRef là type hint.

Điều này tương tự như cách gọi annotationlib.ForwardRef.evaluate(), nhưng không giống như phương pháp đó, evaluate_forward_ref() cũng đánh giá đệ quy các tham chiếu chuyển tiếp được lồng trong gợi ý loại.

Xem tài liệu về annotationlib.ForwardRef.evaluate() để biết ý nghĩa của các tham số owner, globals, locals, type_params và format.

Cảnh báo

Hàm này có thể thực thi mã tùy ý có trong chú thích. Xem Ý nghĩa bảo mật của các chú thích nội tâm để biết thêm thông tin.

Added in version 3.14.

typing.NoDefault¶

Một đối tượng canh gác được sử dụng để chỉ ra rằng tham số loại không có giá trị mặc định. Ví dụ:

>>> T = TypeVar("T")
>>> T.__default__ đang gõ.NoDefault
đúng
>>> S = TypeVar("S", default=None)
>>> S.__default__ là Không có
đúng

Added in version 3.13.

Hằng số¶

typing.TYPE_CHECKING¶

Một hằng số đặc biệt được coi là True bởi trình kiểm tra loại tĩnh của bên thứ 3. Đó là False khi chạy.

Một mô-đun nhập đắt tiền và chỉ chứa các loại được sử dụng để nhập chú thích, có thể được nhập một cách an toàn bên trong khối if TYPE_CHECKING:. Điều này ngăn không cho mô-đun thực sự được nhập vào lúc chạy; các chú thích không được đánh giá một cách háo hức (xem PEP 649) nên việc sử dụng các ký hiệu không xác định trong các chú thích là vô hại--miễn là sau này bạn không kiểm tra chúng. Công cụ phân tích loại tĩnh của bạn sẽ đặt TYPE_CHECKING thành True trong quá trình phân tích loại tĩnh, có nghĩa là mô-đun sẽ được nhập và các loại sẽ được kiểm tra chính xác trong quá trình phân tích đó.

Cách sử dụng:

nếu TYPE_CHECKING:
    nhập đắt_mod

def fun(arg: cost_mod.SomeType) -> Không có:
    local_var: đắt_mod.AnotherType = other_fun()

Nếu đôi khi bạn cần kiểm tra các chú thích loại trong thời gian chạy có thể chứa các ký hiệu không xác định, hãy sử dụng annotationlib.get_annotations() với tham số format là annotationlib.Format.STRING hoặc annotationlib.Format.FORWARDREF để truy xuất các chú thích một cách an toàn mà không cần tăng NameError.

Added in version 3.5.2.

Bí danh không được dùng nữa¶

Mô-đun này xác định một số bí danh không được dùng nữa cho các lớp thư viện tiêu chuẩn có sẵn. Chúng ban đầu được bao gồm trong mô-đun typing để hỗ trợ tham số hóa các lớp chung này bằng []. Tuy nhiên, các bí danh trở nên dư thừa trong Python 3.9 khi các lớp có sẵn tương ứng được cải tiến để hỗ trợ [] (xem PEP 585).

Các loại dư thừa không được dùng nữa kể từ Python 3.9. Tuy nhiên, mặc dù các bí danh này có thể bị xóa vào một thời điểm nào đó nhưng việc loại bỏ các bí danh này hiện chưa được lên kế hoạch. Do đó, hiện tại không có cảnh báo ngừng sử dụng nào được trình thông dịch đưa ra cho các bí danh này.

Nếu tại một thời điểm nào đó, người ta quyết định xóa các bí danh không được dùng nữa này thì trình thông dịch sẽ đưa ra cảnh báo không dùng nữa cho ít nhất hai bản phát hành trước khi xóa. Các bí danh được đảm bảo vẫn còn trong mô-đun typing mà không có cảnh báo không dùng nữa cho đến ít nhất là Python 3.14.

Trình kiểm tra loại được khuyến khích gắn cờ việc sử dụng các loại không được dùng nữa nếu chương trình mà họ đang kiểm tra nhắm mục tiêu phiên bản Python tối thiểu là 3.9 hoặc mới hơn.

Bí danh cho các loại tích hợp¶

class typing.Dict(dict, MutableMapping[KT, VT])¶

Bí danh dict không còn được dùng nữa.

Lưu ý rằng để chú thích các đối số, nên sử dụng loại bộ sưu tập trừu tượng như Mapping hơn là sử dụng dict hoặc typing.Dict.

Sắp loại bỏ từ phiên bản 3.9: builtins.dict hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.List(list, MutableSequence[T])¶

Bí danh list không còn được dùng nữa.

Lưu ý rằng để chú thích các đối số, nên sử dụng loại bộ sưu tập trừu tượng như Sequence hoặc Iterable hơn là sử dụng list hoặc typing.List.

Sắp loại bỏ từ phiên bản 3.9: builtins.list hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Set(set, MutableSet[T])¶

Bí danh builtins.set không còn được dùng nữa.

Lưu ý rằng để chú thích các đối số, nên sử dụng loại bộ sưu tập trừu tượng như collections.abc.Set hơn là sử dụng set hoặc typing.Set.

Sắp loại bỏ từ phiên bản 3.9: builtins.set hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.FrozenSet(frozenset, AbstractSet[T_co])¶: Bí danh builtins.frozenset không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: builtins.frozenset hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

typing.Tuple¶

Bí danh không được dùng nữa cho tuple.

tuple và Tuple được đặt biệt trong hệ thống loại; xem Chú thích các bộ dữ liệu để biết thêm chi tiết.

Sắp loại bỏ từ phiên bản 3.9: builtins.tuple hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Type(Generic[CT_co])¶

Bí danh type không còn được dùng nữa.

Xem Kiểu đối tượng của lớp để biết chi tiết về cách sử dụng type hoặc typing.Type trong chú thích loại.

Added in version 3.5.2.

Sắp loại bỏ từ phiên bản 3.9: builtins.type hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Bí danh cho các loại trong `collections`¶

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])¶: Bí danh collections.defaultdict không còn được dùng nữa.

Added in version 3.5.2.

Sắp loại bỏ từ phiên bản 3.9: collections.defaultdict hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])¶: Bí danh collections.OrderedDict không còn được dùng nữa.

Added in version 3.7.2.

Sắp loại bỏ từ phiên bản 3.9: collections.OrderedDict hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])¶: Bí danh collections.ChainMap không còn được dùng nữa.

Added in version 3.6.1.

Sắp loại bỏ từ phiên bản 3.9: collections.ChainMap hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Counter(collections.Counter, Dict[T, int])¶: Bí danh collections.Counter không còn được dùng nữa.

Added in version 3.6.1.

Sắp loại bỏ từ phiên bản 3.9: collections.Counter hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Deque(deque, MutableSequence[T])¶: Bí danh collections.deque không còn được dùng nữa.

Added in version 3.6.1.

Sắp loại bỏ từ phiên bản 3.9: collections.deque hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Bí danh cho các loại bê tông khác¶

class typing.Pattern¶

class typing.Match¶

Các bí danh không được dùng nữa tương ứng với các kiểu trả về từ re.compile() và re.match().

Các loại này (và các hàm tương ứng) là chung trên AnyStr. Pattern có thể được chuyên biệt hóa thành Pattern[str] hoặc Pattern[bytes]; Match có thể được chuyên biệt hóa thành Match[str] hoặc Match[bytes].

Sắp loại bỏ từ phiên bản 3.9: Các lớp Pattern và Match từ re hiện hỗ trợ []. Xem PEP 585 và Loại bí danh chung.

class typing.Text¶

Bí danh không được dùng nữa cho str.

Text được cung cấp để cung cấp đường dẫn tương thích về phía trước cho mã Python 2: trong Python 2, Text là bí danh cho unicode.

Sử dụng Text để chỉ ra rằng một giá trị phải chứa chuỗi unicode theo cách tương thích với cả Python 2 và Python 3

def add_unicode_checkmark(text: Text) -> Text:
    trả lại văn bản + u' \u2713'

Added in version 3.5.2.

Sắp loại bỏ từ phiên bản 3.11: Python 2 không còn được hỗ trợ và hầu hết các trình kiểm tra loại cũng không còn hỗ trợ kiểm tra loại mã Python 2. Việc xóa bí danh hiện chưa được lên kế hoạch nhưng người dùng được khuyến khích sử dụng str thay vì Text.

Bí danh cho vùng chứa ABC trong `collections.abc`¶

class typing.AbstractSet(Collection[T_co])¶: Bí danh collections.abc.Set không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Set hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.ByteString(Sequence[int])¶

Bí danh collections.abc.ByteString không còn được dùng nữa.

Sử dụng isinstance(obj, collections.abc.Buffer) để kiểm tra xem obj có triển khai buffer protocol khi chạy hay không. Để sử dụng trong chú thích loại, hãy sử dụng Buffer hoặc liên kết chỉ định rõ ràng các loại mà mã của bạn hỗ trợ (ví dụ: bytes | bytearray | memoryview).

ByteString ban đầu được dự định là một lớp trừu tượng sẽ đóng vai trò là siêu kiểu của cả bytes và bytearray. Tuy nhiên, vì ABC chưa bao giờ có bất kỳ phương thức nào nên việc biết rằng một đối tượng là một thể hiện của ByteString chưa bao giờ thực sự cho bạn biết bất kỳ điều gì hữu ích về đối tượng đó. Các loại bộ đệm phổ biến khác như memoryview cũng không bao giờ được hiểu là kiểu con của ByteString (trong thời gian chạy hoặc bằng trình kiểm tra kiểu tĩnh).

Xem PEP 688 để biết thêm chi tiết.

Không được dùng nữa kể từ phiên bản 3.9, sẽ bị xóa trong phiên bản 3.17.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])¶: Bí danh collections.abc.Collection không còn được dùng nữa.

Added in version 3.6.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Collection hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Container(Generic[T_co])¶: Bí danh collections.abc.Container không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Container hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])¶: Bí danh collections.abc.ItemsView không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.ItemsView hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.KeysView(MappingView, AbstractSet[KT_co])¶: Bí danh collections.abc.KeysView không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.KeysView hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Mapping(Collection[KT], Generic[KT, VT_co])¶: Bí danh collections.abc.Mapping không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Mapping hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.MappingView(Sized)¶: Bí danh collections.abc.MappingView không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.MappingView hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.MutableMapping(Mapping[KT, VT])¶: Bí danh collections.abc.MutableMapping không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.MutableMapping hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.MutableSequence(Sequence[T])¶: Bí danh collections.abc.MutableSequence không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.MutableSequence hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.MutableSet(AbstractSet[T])¶: Bí danh collections.abc.MutableSet không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.MutableSet hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Sequence(Reversible[T_co], Collection[T_co])¶: Bí danh collections.abc.Sequence không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Sequence hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.ValuesView(MappingView, Collection[_VT_co])¶: Bí danh collections.abc.ValuesView không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.ValuesView hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Bí danh cho ABC không đồng bộ trong `collections.abc`¶

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])¶

Bí danh collections.abc.Coroutine không còn được dùng nữa.

Xem Trình tạo chú thích và coroutine để biết chi tiết về cách sử dụng collections.abc.Coroutine và typing.Coroutine trong chú thích loại.

Added in version 3.5.3.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Coroutine hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])¶

Bí danh collections.abc.AsyncGenerator không còn được dùng nữa.

Xem Trình tạo chú thích và coroutine để biết chi tiết về cách sử dụng collections.abc.AsyncGenerator và typing.AsyncGenerator trong chú thích loại.

Added in version 3.6.1.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.AsyncGenerator hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Thay đổi trong phiên bản 3.13: Tham số SendType hiện có giá trị mặc định.

class typing.AsyncIterable(Generic[T_co])¶: Bí danh collections.abc.AsyncIterable không còn được dùng nữa.

Added in version 3.5.2.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.AsyncIterable hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.AsyncIterator(AsyncIterable[T_co])¶: Bí danh collections.abc.AsyncIterator không còn được dùng nữa.

Added in version 3.5.2.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.AsyncIterator hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Awaitable(Generic[T_co])¶: Bí danh collections.abc.Awaitable không còn được dùng nữa.

Added in version 3.5.2.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Awaitable hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Bí danh cho các ABC khác trong `collections.abc`¶

class typing.Iterable(Generic[T_co])¶: Bí danh collections.abc.Iterable không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Iterable hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Iterator(Iterable[T_co])¶: Bí danh collections.abc.Iterator không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Iterator hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

typing.Callable¶

Bí danh collections.abc.Callable không còn được dùng nữa.

Xem Chú thích các đối tượng có thể gọi được để biết chi tiết về cách sử dụng collections.abc.Callable và typing.Callable trong chú thích loại.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Callable hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Thay đổi trong phiên bản 3.10: Callable hiện hỗ trợ ParamSpec và Concatenate. Xem PEP 612 để biết thêm chi tiết.

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])¶

Bí danh collections.abc.Generator không còn được dùng nữa.

Xem Trình tạo chú thích và coroutine để biết chi tiết về cách sử dụng collections.abc.Generator và typing.Generator trong chú thích loại.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Generator hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Thay đổi trong phiên bản 3.13: Giá trị mặc định cho loại gửi và trả lại đã được thêm vào.

class typing.Hashable¶: Bí danh collections.abc.Hashable không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.12: Thay vào đó hãy sử dụng collections.abc.Hashable trực tiếp.

class typing.Reversible(Iterable[T_co])¶: Bí danh collections.abc.Reversible không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.9: collections.abc.Reversible hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

class typing.Sized¶: Bí danh collections.abc.Sized không còn được dùng nữa.

Sắp loại bỏ từ phiên bản 3.12: Thay vào đó hãy sử dụng collections.abc.Sized trực tiếp.

Bí danh cho `contextlib` ABC¶

class typing.ContextManager(Generic[T_co, ExitT_co])¶

Bí danh contextlib.AbstractContextManager không còn được dùng nữa.

Tham số loại đầu tiên, T_co, đại diện cho loại được trả về bởi phương thức __enter__(). Tham số loại thứ hai tùy chọn, ExitT_co, mặc định là bool | None, đại diện cho loại được trả về bởi phương thức __exit__().

Added in version 3.5.4.

Sắp loại bỏ từ phiên bản 3.9: contextlib.AbstractContextManager hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Thay đổi trong phiên bản 3.13: Đã thêm tham số loại thứ hai tùy chọn, ExitT_co.

class typing.AsyncContextManager(Generic[T_co, AExitT_co])¶

Bí danh contextlib.AbstractAsyncContextManager không còn được dùng nữa.

Tham số loại đầu tiên, T_co, đại diện cho loại được trả về bởi phương thức __aenter__(). Tham số loại thứ hai tùy chọn, AExitT_co, mặc định là bool | None, đại diện cho loại được trả về bởi phương thức __aexit__().

Added in version 3.6.2.

Sắp loại bỏ từ phiên bản 3.9: contextlib.AbstractAsyncContextManager hiện hỗ trợ đăng ký ([]). Xem PEP 585 và Loại bí danh chung.

Thay đổi trong phiên bản 3.13: Đã thêm tham số loại thứ hai tùy chọn, AExitT_co.

Dòng thời gian ngừng sử dụng các tính năng chính¶

Một số tính năng nhất định trong typing không được dùng nữa và có thể bị xóa trong phiên bản Python trong tương lai. Bảng sau đây tóm tắt các trường hợp ngừng sử dụng chính để thuận tiện cho bạn. Điều này có thể thay đổi và không phải tất cả các trường hợp không dùng nữa đều được liệt kê.

tính năng	Không được dùng nữa ở	Loại bỏ dự kiến	PEP/số phát hành
phiên bản `typing` của bộ sưu tập tiêu chuẩn	3,9	Chưa quyết định (xem Bí danh không được dùng nữa để biết thêm thông tin)	PEP 585
`typing.ByteString`	3,9	3.17	gh-91896
`typing.Text`	3.11	Chưa quyết định	gh-92332
`typing.Hashable` và `typing.Sized`	3.12	Chưa quyết định	gh-94309
`typing.TypeAlias`	3.12	Chưa quyết định	PEP 695
`@typing.no_type_check_decorator`	3.13	3,15	gh-106309
`typing.AnyStr`	3.13	3.18	gh-105578

`typing` --- Hỗ trợ gợi ý loại¶

Đặc điểm kỹ thuật cho hệ thống kiểu Python¶

Nhập bí danh¶

Loại mới¶

Chú thích các đối tượng có thể gọi được¶

Thuốc gốc¶

Chú thích các bộ dữ liệu¶

Kiểu đối tượng của lớp¶

Trình tạo chú thích và coroutine¶

Các loại chung do người dùng xác định¶

Loại `Any`¶

Phân nhóm danh nghĩa và cấu trúc¶

Nội dung mô-đun¶

Kiểu gõ đặc biệt¶

Các loại đặc biệt¶

Các hình thức đặc biệt¶

Xây dựng các loại chung và bí danh loại¶

Các chỉ thị đặc biệt khác¶

Giao thức¶

ABC và các giao thức để làm việc với I/O¶

Chức năng và trang trí¶

Người giúp đỡ nội tâm¶

Hằng số¶

Bí danh không được dùng nữa¶

Bí danh cho các loại tích hợp¶

Bí danh cho các loại trong `collections`¶

Bí danh cho các loại bê tông khác¶

Bí danh cho vùng chứa ABC trong `collections.abc`¶

Bí danh cho ABC không đồng bộ trong `collections.abc`¶

Bí danh cho các ABC khác trong `collections.abc`¶

Bí danh cho `contextlib` ABC¶

Dòng thời gian ngừng sử dụng các tính năng chính¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

typing --- Hỗ trợ gợi ý loại¶

Đặc điểm kỹ thuật cho hệ thống kiểu Python¶

Nhập bí danh¶

Loại mới¶

Chú thích các đối tượng có thể gọi được¶

Thuốc gốc¶

Chú thích các bộ dữ liệu¶

Kiểu đối tượng của lớp¶

Trình tạo chú thích và coroutine¶

Các loại chung do người dùng xác định¶

Loại Any¶

Phân nhóm danh nghĩa và cấu trúc¶

Nội dung mô-đun¶

Kiểu gõ đặc biệt¶

Các loại đặc biệt¶

Các hình thức đặc biệt¶

Xây dựng các loại chung và bí danh loại¶

Các chỉ thị đặc biệt khác¶

Giao thức¶

ABC và các giao thức để làm việc với I/O¶

Chức năng và trang trí¶

Người giúp đỡ nội tâm¶

Hằng số¶

Bí danh không được dùng nữa¶

Bí danh cho các loại tích hợp¶

Bí danh cho các loại trong collections¶

Bí danh cho các loại bê tông khác¶

Bí danh cho vùng chứa ABC trong collections.abc¶

Bí danh cho ABC không đồng bộ trong collections.abc¶

Bí danh cho các ABC khác trong collections.abc¶

Bí danh cho contextlib ABC¶

Dòng thời gian ngừng sử dụng các tính năng chính¶

`typing` --- Hỗ trợ gợi ý loại¶

Loại `Any`¶

Bí danh cho các loại trong `collections`¶

Bí danh cho vùng chứa ABC trong `collections.abc`¶

Bí danh cho ABC không đồng bộ trong `collections.abc`¶

Bí danh cho các ABC khác trong `collections.abc`¶

Bí danh cho `contextlib` ABC¶