特別型別¶

這些可以在註釋中做為型別。他們並不支援[] 的下標使用。

typing.Any¶

特別型別，指出一個不受約束 (unconstrained) 的型別。

• 所有型別皆與Any 相容。

• Any 相容於所有型別。

在 3.11 版的變更:Any 可以作為一個基礎類別。這對於在任何地方使用鴨子型別或是高度動態的型別，避免型別檢查器的錯誤是非常有用的。

typing.AnyStr¶

一個不受約束的型別變數。

定義：

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

AnyStr 是對於函式有用的，他可以接受str 或bytes 引數但不可以將此兩種混合。

舉例來說：

defconcat(a:AnyStr,b:AnyStr)->AnyStr:returna+bconcat("foo","bar")# OK, output has type 'str'concat(b"foo",b"bar")# OK, output has type 'bytes'concat("foo",b"bar")# Error, cannot mix str and bytes

請注意，儘管他的名稱相近，AnyStr 與Any 型別無關，更不代表是「任何字串」的意思。尤其，AnyStr 與str|bytes 兩者不同且具有不同的使用情境：

# Invalid use of AnyStr:# The type variable is used only once in the function signature,# so cannot be "solved" by the type checkerdefgreet_bad(cond:bool)->AnyStr:return"hi there!"ifcondelseb"greetings!"# The better way of annotating this function:defgreet_proper(cond:bool)->str|bytes:return"hi there!"ifcondelseb"greetings!"

Deprecated since version 3.13, will be removed in version 3.18:Deprecated in favor of the newtype parameter syntax.UseclassA[T:(str,bytes)]:... instead of importingAnyStr. SeePEP 695 for more details.

In Python 3.16,AnyStr will be removed fromtyping.__all__, anddeprecation warnings will be emitted at runtime when it is accessed orimported fromtyping.AnyStr will be removed fromtypingin Python 3.18.

typing.LiteralString¶

特別型別，只包含文本字串。

任何文本字串都相容於LiteralString，對於另一個LiteralString 亦是如此。然而，若是一個型別僅為str 的物件則不相容。一個字串若是透過組合多個LiteralString 型別的物件建立，則此字串也可以視為LiteralString。

舉例來說：

defrun_query(sql:LiteralString)->None:...defcaller(arbitrary_string:str,literal_string:LiteralString)->None:run_query("SELECT * FROM students")# OKrun_query(literal_string)# OKrun_query("SELECT * FROM "+literal_string)# OKrun_query(arbitrary_string)# type checker errorrun_query(# type checker errorf"SELECT * FROM students WHERE name ={arbitrary_string}")

LiteralString 對於敏感的 API 來說是有用的，其中任意的使用者產生的字串可能會產生問題。舉例來說，上面兩個案例中產生的型別檢查器錯誤是脆弱的且容易受到 SQL 注入攻擊。

更多細節請見PEP 675。

在 3.11 版被加入.

typing.Never¶

typing.NoReturn¶

Never 和NoReturn 表示底部型別 (bottom type)，為一個沒有任何成員的型別。

它們可以被用來代表一個不會回傳的函式，像是sys.exit()：

fromtypingimportNever# 或 NoReturndefstop()->Never:raiseRuntimeError('no way')

或被用來定義一個不應被呼叫的函式，因為不會有有效的引數，、像是assert_never()：

fromtypingimportNever# or NoReturndefnever_call_me(arg:Never)->None:passdefint_or_str(arg:int|str)->None:never_call_me(arg)# type checker errormatcharg:caseint():print("It's an int")casestr():print("It's a str")case_:never_call_me(arg)# OK, arg is of type Never (or NoReturn)

Never 以及NoReturn 在型別系統中具有相同的意義且靜態型別檢查器會將兩者視為相等。

在 3.6.2 版被加入:新增NoReturn。

在 3.11 版被加入:新增Never。

typing.Self¶

特別型別，用來表示目前類別之內 (enclosed class)。

舉例來說：

fromtypingimportSelf,reveal_typeclassFoo:defreturn_self(self)->Self:...returnselfclassSubclassOfFoo(Foo):passreveal_type(Foo().return_self())# Revealed type is "Foo"reveal_type(SubclassOfFoo().return_self())# Revealed type is "SubclassOfFoo"

這個註釋在語意上相等於下列內容，且形式更為簡潔：

fromtypingimportTypeVarSelf=TypeVar("Self",bound="Foo")classFoo:defreturn_self(self:Self)->Self:...returnself

一般來說，如果某個東西回傳self 如上方的範例所示，你則應該使用Self 做為回傳值的註釋。若Foo.return_self 被註釋為回傳"Foo"，則型別檢查器應該推論這個從SubclassOfFoo.return_self 回傳的物件為Foo 型別，而並非回傳SubclassOfFoo 型別。

其他常見的使用案例包含：

• classmethod 被用來作為替代的建構函式 (constructor) 並回傳cls 參數的實例。

• 註釋一個回傳自己的__enter__() 方法。

當類別被子類別化時，若方法不保證回傳一個子類別的實例，你不應該使用Self 作為回傳註釋：

classEggs:# Self would be an incorrect return annotation here,# as the object returned is always an instance of Eggs,# even in subclassesdefreturns_eggs(self)->"Eggs":returnEggs()

更多細節請見PEP 673。

在 3.11 版被加入.

typing.TypeAlias¶

做為明確宣告一個型別別名 的特別註釋。

舉例來說：

fromtypingimportTypeAliasFactors:TypeAlias=list[int]

TypeAlias 在舊的 Python 版本中特別有用，其註釋別名可以用來進行傳遞參照 (forward reference)，因為對於型別檢查器來說，分辨這些別名與一般的變數賦值相當困難：

fromtypingimportGeneric,TypeAlias,TypeVarT=TypeVar("T")# "Box" does not exist yet,# so we have to use quotes for the forward reference on Python <3.12.# Using ``TypeAlias`` tells the type checker that this is a type alias declaration,# not a variable assignment to a string.BoxOfStrings:TypeAlias="Box[str]"classBox(Generic[T]):@classmethoddefmake_box_of_strings(cls)->BoxOfStrings:...

更多細節請見PEP 613。

在 3.10 版被加入.

在 3.12 版之後被棄用:TypeAlias 被棄用，請改用type 陳述式來建立TypeAliasType 的實例，其自然可以支援傳遞參照的使用。請注意，雖然TypeAlias 以及TypeAliasType 提供相似的用途且具有相似的名稱，他們是不同的，且後者不是前者的型別。現在還沒有移除TypeAlias 的計畫，但鼓勵使用者們遷移 (migrate) 至type 陳述式。

特別型式¶

這些在註釋中可以當作型別使用。他們全都支援[] 的下標使用，但每個都具有獨特的語法。

typing.Union¶

聯集型別；Union[X,Y] 與X|Y 是相等的，且都意味著 X 或 Y 兩者其一。

為了定義聯集，例如可以使用Union[int,str] 或是使用簡寫 (shorthand)int|str。使用這種簡寫是非常推薦的。詳細請看：

• 引數必須為型別且必須有至少一個。

• 聯集中的聯集會是扁平化的 (flattened)，舉例來說：

  Union[Union[int,str],float]==Union[int,str,float]

  However, this does not apply to unions referenced through a typealias, to avoid forcing evaluation of the underlyingTypeAliasType:

  typeA=Union[int,str]Union[A,float]!=Union[int,str,float]

• 單一引數的聯集會消失不見，舉例來說：

  Union[int]==int# 實際上建構函式會回傳 int

• 多餘的引數會被略過，舉例來說：

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

• 當比較聯集時，引數的順序會被忽略，舉例來說：

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

• 你不能建立Union 的子類別或是實例。

• 你不能寫成Union[X][Y]。

在 3.7 版的變更:請勿在 runtime 中將顯性子類別從聯集中移除。

在 3.10 版的變更:現在可以將聯集寫成X|Y。請見聯集型別運算式。

typing.Optional¶

Optional[X] 與X|None 是相等的（或是Union[X,None]）。

請注意，這與具有預設值的選擇性引數 (optional argument) 不是相同的概念。一個具有預設值的選擇性引數的型別註釋中不具有Optional 限定符 (qualifier)，單純的因為它就是選擇性的。舉例來說：

deffoo(arg:int=0)->None:...

另一方面，如果一個顯性的值None 是被允許的，不論引數是不是選擇性的，Optional 都適用。舉例來說：

deffoo(arg:Optional[int]=None)->None:...

在 3.10 版的變更:現在可以將 Optional 寫成X|None。請見聯集型別運算式。

typing.Concatenate¶

用於註釋高階函式的特別型式。

Concatenate 可以被用在可呼叫物件與ParamSpec 的接合 (conjunction) 並註釋一個高階的 Callable 物件可以新增、移除、轉換另一個 Callable 物件的參數。使用方法是依照這個格式Concatenate[Arg1Type,Arg2Type,...,ParamSpecVariable]。Concatenate 目前只在Callable 物件中第一個引數使用時有效。Concatenate 的最後一個參數必須為一個ParamSpec 或是刪節號 (...)。

舉例來說，註釋一個為裝飾過後的函式提供threading.Lock 的裝飾器with_lock，Concatenate 可以用於指出with_lock 預期一個 Callable 物件，該物件可以接受Lock 作為第一引數，並回傳一個具有不同型別簽名 Callable 物件。在這種情況下，ParamSpec 指出回傳的 Callable 物件的參數型別會依賴傳遞的 Callable 物件的參數型別：

fromcollections.abcimportCallablefromthreadingimportLockfromtypingimportConcatenate# Use this lock to ensure that only one thread is executing a function# at any time.my_lock=Lock()defwith_lock[**P,R](f:Callable[Concatenate[Lock,P],R])->Callable[P,R]:'''A type-safe decorator which provides a lock.'''definner(*args:P.args,**kwargs:P.kwargs)->R:# Provide the lock as the first argument.returnf(my_lock,*args,**kwargs)returninner@with_lockdefsum_threadsafe(lock:Lock,numbers:list[float])->float:'''Add a list of numbers together in a thread-safe manner.'''withlock:returnsum(numbers)# We don't need to pass in the lock ourselves thanks to the decorator.sum_threadsafe([1.1,2.2,3.3])

在 3.10 版被加入.

也參考

• PEP 612 -- 參數技術規範變數

• ParamSpec

• 註釋 callable 物件

typing.Literal¶

特殊型別格式，用於定義「文本型別 (literal type)」。

Literal 可以用於型別檢查器並指出註釋物件具有一個與提供的文本相同的值。

舉例來說：

defvalidate_simple(data:Any)->Literal[True]:# always returns True...typeMode=Literal['r','rb','w','wb']defopen_helper(file:str,mode:Mode)->str:...open_helper('/some/path','r')# Passes type checkopen_helper('/other/path','typo')# Error in type checker

Literal[...] 不可以進行子類別化。在 runtime 之中，任意的值是允許作為Literal[...] 的型別引數，但型別檢查器可能會加強限制。更多有關文本型別的詳細資訊請看PEP 586。

其他細節：

• 引數必須為文本值且必須有至少一個。

• 巢狀的Literal 會是扁平化的 (flattened)，舉例來說：

  assertLiteral[Literal[1,2],3]==Literal[1,2,3]

  However, this does not apply toLiteral types referenced through a typealias, to avoid forcing evaluation of the underlyingTypeAliasType:

  typeA=Literal[1,2]assertLiteral[A,3]!=Literal[1,2,3]

• 多餘的引數會被略過，舉例來說：

  assertLiteral[1,2,1]==Literal[1,2]

• 當比較文本時，引數的順序會被忽略，舉例來說：

  assertLiteral[1,2]==Literal[2,1]

• 你不能建立Literal 的子類別或是實例。

• 你不能寫成Literal[X][Y]。

在 3.8 版被加入.

在 3.9.1 版的變更:Literal 現在可以刪除重複 (de-deplicate) 的參數。Literal 物件的相等性比較不再依照相依性排序。Literal 物件現在會在相等性比較期間，若任一個其中的參數無法hashable 時，則會引發一個TypeError 例外。

typing.ClassVar¶

特殊型別建構，用來標記類別變數。

如同在PEP 526 中的介紹，一個變數註解被包裝在 ClassVar 中時，會指出一個給定的屬性 (attribute) 意圖被當作類別變數使用，且不該被設定成該類別的實例。使用方法如下：

classStarship:stats:ClassVar[dict[str,int]]={}# 類別變數damage:int=10# 實例變數

ClassVar 只接受型別請不得使用下標。

ClassVar 並不代表該類別本身，而且不應該和isinstance() 或是issubclass() 一起使用。ClassVar 不會改變 Python runtime 的行為，但它可以被第三方的型別檢查器使用。舉例來說，一個型別檢查器可能會標記下方的程式碼為一個錯誤：

enterprise_d=Starship(3000)enterprise_d.stats={}# Error, setting class variable on instanceStarship.stats={}# This is OK

在 3.5.3 版被加入.

在 3.13 版的變更:ClassVar can now be nested inFinal and vice versa.

typing.Final¶

特殊型別建構，用來指出給型別檢查器的最終名稱。

最終名稱不可以在任何作用域 (scope) 中重新賦值。在類別作用域中宣告的最終名稱，不得在子類別中進行覆寫 (override)。

舉例來說：

MAX_SIZE:Final=9000MAX_SIZE+=1# Error reported by type checkerclassConnection:TIMEOUT:Final[int]=10classFastConnector(Connection):TIMEOUT=1# Error reported by type checker

這些屬性 (property) 不會在 runtime 時進行檢查。更多詳細資訊請看PEP 591。

在 3.8 版被加入.

在 3.13 版的變更:Final can now be nested inClassVar and vice versa.

typing.Required¶

特殊型別建構，用來標記一個TypedDict 鍵值是必須的。

主要用於total=False 的 TypedDict。更多細節請見TypedDict 與PEP 655。

在 3.11 版被加入.

typing.NotRequired¶

特殊型別建構，用來標記一個TypedDict 鍵值是可能消失的。

更多細節請見TypedDict 與PEP 655。

在 3.11 版被加入.

typing.ReadOnly¶

特殊型別建構，用來標記一個TypedDict 的項目是唯讀的。

舉例來說：

classMovie(TypedDict):title:ReadOnly[str]year:intdefmutate_movie(m:Movie)->None:m["year"]=1999# allowedm["title"]="The Matrix"# 型別檢查器錯誤

這些屬性 (property) 不會在 runtime 時進行檢查。

更多細節請見TypedDict 與PEP 705。

在 3.13 版被加入.

typing.Annotated¶

Special typing form to add context-specific metadata to an annotation.

Add metadatax to a given typeT by using the annotationAnnotated[T,x]. Metadata added usingAnnotated can be used bystatic analysis tools or at runtime. At runtime, the metadata is storedin a__metadata__ attribute.

If a library or tool encounters an annotationAnnotated[T,x] and hasno special logic for the metadata, it should ignore the metadata and simplytreat the annotation asT. As such,Annotated can be useful for codethat wants to use annotations for purposes outside Python's static typingsystem.

UsingAnnotated[T,x] as an annotation still allows for statictypechecking ofT, as type checkers will simply ignore the metadatax.In this way,Annotated differs from the@no_type_check decorator, which can also be used foradding annotations outside the scope of the typing system, butcompletely disables typechecking for a function or class.

The responsibility of how to interpret the metadatalies with the tool or library encountering anAnnotated annotation. A tool or library encountering anAnnotated typecan scan through the metadata elements to determine if they are of interest(e.g., usingisinstance()).

Annotated[<type>,<metadata>]

Here is an example of how you might useAnnotated to add metadata totype annotations if you were doing range analysis:

@dataclassclassValueRange:lo:inthi:intT1=Annotated[int,ValueRange(-10,5)]T2=Annotated[T1,ValueRange(-20,3)]

The first argument toAnnotated must be a valid type. Multiple metadataelements can be supplied asAnnotated supports variadic arguments. Theorder of the metadata elements is preserved and matters for equality checks:

@dataclassclassctype:kind:stra1=Annotated[int,ValueRange(3,10),ctype("char")]a2=Annotated[int,ctype("char"),ValueRange(3,10)]asserta1!=a2# 順序是有意義的

It is up to the tool consuming the annotations to decide whether theclient is allowed to add multiple metadata elements to one annotation and how tomerge those annotations.

NestedAnnotated types are flattened. The order of the metadata elementsstarts with the innermost annotation:

assertAnnotated[Annotated[int,ValueRange(3,10)],ctype("char")]==Annotated[int,ValueRange(3,10),ctype("char")]

However, this does not apply toAnnotated types referenced through a typealias, to avoid forcing evaluation of the underlyingTypeAliasType:

typeFrom3To10[T]=Annotated[T,ValueRange(3,10)]assertAnnotated[From3To10[int],ctype("char")]!=Annotated[int,ValueRange(3,10),ctype("char")]

Duplicated metadata elements are not removed:

assertAnnotated[int,ValueRange(3,10)]!=Annotated[int,ValueRange(3,10),ValueRange(3,10)]

Annotated can be used with nested and generic aliases:

@dataclassclassMaxLen:value:inttypeVec[T]=Annotated[list[tuple[T,T]],MaxLen(10)]# When used in a type annotation, a type checker will treat "V" the same as# ``Annotated[list[tuple[int, int]], MaxLen(10)]``:typeV=Vec[int]

Annotated cannot be used with an unpackedTypeVarTuple:

typeVariadic[*Ts]=Annotated[*Ts,Ann1]=Annotated[T1,T2,T3,...,Ann1]# 無效

whereT1,T2, ... areTypeVars. This is invalid asonly one type should be passed to Annotated.

By default,get_type_hints() strips the metadata from annotations.Passinclude_extras=True to have the metadata preserved:

>>>fromtypingimportAnnotated,get_type_hints>>>deffunc(x:Annotated[int,"metadata"])->None:pass...>>>get_type_hints(func){'x': <class 'int'>, 'return': <class 'NoneType'>}>>>get_type_hints(func,include_extras=True){'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

At runtime, the metadata associated with anAnnotated type can beretrieved via the__metadata__ attribute:

>>>fromtypingimportAnnotated>>>X=Annotated[int,"very","important","metadata"]>>>Xtyping.Annotated[int, 'very', 'important', 'metadata']>>>X.__metadata__('very', 'important', 'metadata')

If you want to retrieve the original type wrapped byAnnotated, use the__origin__ attribute:

>>>fromtypingimportAnnotated,get_origin>>>Password=Annotated[str,"secret"]>>>Password.__origin__<class 'str'>

Note that usingget_origin() will returnAnnotated itself:

>>>get_origin(Password)typing.Annotated

也參考

PEP 593 - Flexible function and variable annotations

The PEP introducingAnnotated to the standard library.

在 3.9 版被加入.

typing.TypeIs¶

Special typing construct for marking user-defined type predicate functions.

TypeIs can be used to annotate the return type of a user-definedtype predicate function.TypeIs only accepts a single type argument.At runtime, functions marked this way should return a boolean and take atleast one positional argument.

TypeIs aims to benefittype narrowing -- a technique used by statictype checkers to determine a more precise type of an expression within aprogram's code flow. Usually type narrowing is done by analyzingconditional code flow and applying the narrowing to a block of code. Theconditional expression here is sometimes referred to as a "type predicate":

defis_str(val:str|float):# "isinstance" type predicateifisinstance(val,str):# Type of ``val`` is narrowed to ``str``...else:# Else, type of ``val`` is narrowed to ``float``....

Sometimes it would be convenient to use a user-defined boolean functionas a type predicate. Such a function should useTypeIs[...] orTypeGuard as its return type to alert static type checkers tothis intention.TypeIs usually has more intuitive behavior thanTypeGuard, but it cannot be used when the input and output typesare incompatible (e.g.,list[object] tolist[int]) or when thefunction does not returnTrue for all instances of the narrowed type.

Using->TypeIs[NarrowedType] tells the static type checker that for a givenfunction:

1. 回傳值是一個布林值。

2. If the return value isTrue, the type of its argumentis the intersection of the argument's original type andNarrowedType.

3. If the return value isFalse, the type of its argumentis narrowed to excludeNarrowedType.

舉例來說：

fromtypingimportassert_type,final,TypeIsclassParent:passclassChild(Parent):pass@finalclassUnrelated:passdefis_parent(val:object)->TypeIs[Parent]:returnisinstance(val,Parent)defrun(arg:Child|Unrelated):ifis_parent(arg):# Type of ``arg`` is narrowed to the intersection# of ``Parent`` and ``Child``, which is equivalent to# ``Child``.assert_type(arg,Child)else:# Type of ``arg`` is narrowed to exclude ``Parent``,# so only ``Unrelated`` is left.assert_type(arg,Unrelated)

The type insideTypeIs must be consistent with the type of thefunction's argument; if it is not, static type checkers will raisean error. An incorrectly writtenTypeIs function can lead tounsound behavior in the type system; it is the user's responsibilityto write such functions in a type-safe manner.

If aTypeIs function is a class or instance method, then the type inTypeIs maps to the type of the second parameter (aftercls orself).

In short, the formdeffoo(arg:TypeA)->TypeIs[TypeB]:...,means that iffoo(arg) returnsTrue, thenarg is an instanceofTypeB, and if it returnsFalse, it is not an instance ofTypeB.

TypeIs also works with type variables. For more information, seePEP 742 (Narrowing types withTypeIs).

在 3.13 版被加入.

typing.TypeGuard¶

Special typing construct for marking user-defined type predicate functions.

Type predicate functions are user-defined functions that return whether theirargument is an instance of a particular type.TypeGuard works similarly toTypeIs, but has subtly differenteffects on type checking behavior (see below).

Using->TypeGuard tells the static type checker that for a givenfunction:

1. 回傳值是一個布林值。

2. If the return value isTrue, the type of its argumentis the type insideTypeGuard.

TypeGuard also works with type variables. SeePEP 647 for more details.

舉例來說：

defis_str_list(val:list[object])->TypeGuard[list[str]]:'''Determines whether all objects in the list are strings'''returnall(isinstance(x,str)forxinval)deffunc1(val:list[object]):ifis_str_list(val):# Type of ``val`` is narrowed to ``list[str]``.print(" ".join(val))else:# Type of ``val`` remains as ``list[object]``.print("Not a list of strings!")

TypeIs 和TypeGuard 在以下幾個方面有所不同：

• TypeIs requires the narrowed type to be a subtype of the input type, whileTypeGuard does not. The main reason is to allow for things likenarrowinglist[object] tolist[str] even though the latteris not a subtype of the former, sincelist is invariant.

• When aTypeGuard function returnsTrue, type checkers narrow the type of thevariable to exactly theTypeGuard type. When aTypeIs function returnsTrue,type checkers can infer a more precise type combining the previously known type of thevariable with theTypeIs type. (Technically, this is known as an intersection type.)

• When aTypeGuard function returnsFalse, type checkers cannot narrow the type ofthe variable at all. When aTypeIs function returnsFalse, type checkers can narrowthe type of the variable to exclude theTypeIs type.

在 3.10 版被加入.

typing.Unpack¶

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator* on atype variable tuple is equivalent to usingUnpackto mark the type variable tuple as having been unpacked:

Ts=TypeVarTuple('Ts')tup:tuple[*Ts]# Effectively does:tup:tuple[Unpack[Ts]]

In fact,Unpack can be used interchangeably with* in the contextoftyping.TypeVarTuple andbuiltins.tuple types. You might seeUnpack being usedexplicitly in older versions of Python, where* couldn't be used incertain places:

# In older versions of Python, TypeVarTuple and Unpack# are located in the `typing_extensions` backports package.fromtyping_extensionsimportTypeVarTuple,UnpackTs=TypeVarTuple('Ts')tup:tuple[*Ts]# Syntax error on Python <= 3.10!tup:tuple[Unpack[Ts]]# Semantically equivalent, and backwards-compatible

Unpack can also be used along withtyping.TypedDict for typing**kwargs in a function signature:

fromtypingimportTypedDict,UnpackclassMovie(TypedDict):name:stryear:int# This function expects two keyword arguments - `name` of type `str`# and `year` of type `int`.deffoo(**kwargs:Unpack[Movie]):...

SeePEP 692 for more details on usingUnpack for**kwargs typing.

在 3.11 版被加入.

Building generic types and type aliases¶

The following classes should not be used directly as annotations.Their intended purpose is to be building blocksfor creating generic types and type aliases.

These objects can be created through special syntax(type parameter lists and thetype statement).For compatibility with Python 3.11 and earlier, they can also be createdwithout the dedicated syntax, as documented below.

classtyping.Generic¶

Abstract base class for generic types.

A generic type is typically declared by adding a list of type parametersafter the class name:

classMapping[KT,VT]:def__getitem__(self,key:KT)->VT:...# Etc.

Such a class implicitly inherits fromGeneric.The runtime semantics of this syntax are discussed in theLanguage Reference.

This class can then be used as follows:

deflookup_name[X,Y](mapping:Mapping[X,Y],key:X,default:Y)->Y:try:returnmapping[key]exceptKeyError:returndefault

Here the brackets after the function name indicate ageneric function.

For backwards compatibility, generic classes can also bedeclared by explicitly inheriting fromGeneric. In this case, the type parameters must be declaredseparately:

KT=TypeVar('KT')VT=TypeVar('VT')classMapping(Generic[KT,VT]):def__getitem__(self,key:KT)->VT:...# Etc.

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

Type variable.

The preferred way to construct a type variable is via the dedicated syntaxforgeneric functions,generic classes, andgeneric type aliases:

classSequence[T]:# T 是一個 TypeVar...

This syntax can also be used to create bounded and constrained typevariables:

classStrSequence[S:str]:# S is a TypeVar with a `str` upper bound;...# we can say that S is "bounded by `str`"classStrOrBytesSequence[A:(str,bytes)]:# A is a TypeVar constrained to str or bytes...

However, if desired, reusable type variables can also be constructed manually, like so:

T=TypeVar('T')# 可以是任何東西S=TypeVar('S',bound=str)# 可以是任何 str 的子型別A=TypeVar('A',str,bytes)# 必須是 str 或 bytes

Type variables exist primarily for the benefit of static typecheckers. They serve as the parameters for generic types as wellas for generic function and type alias definitions.SeeGeneric for moreinformation on generic types. Generic functions work as follows:

defrepeat[T](x:T,n:int)->Sequence[T]:"""Return a list containing n references to x."""return[x]*ndefprint_capitalized[S:str](x:S)->S:"""Print x capitalized, and return x."""print(x.capitalize())returnxdefconcatenate[A:(str,bytes)](x:A,y:A)->A:"""Add two strings or bytes objects together."""returnx+y

Note that type variables can bebounded,constrained, or neither, butcannot be both boundedand constrained.

The variance of type variables is inferred by type checkers when they are createdthrough thetype parameter syntax or wheninfer_variance=True is passed.Manually created type variables may be explicitly marked covariant or contravariant by passingcovariant=True orcontravariant=True.By default, manually created type variables are invariant.SeePEP 484 andPEP 695 for more details.

Bounded type variables and constrained type variables have differentsemantics in several important ways. Using abounded type variable meansthat theTypeVar will be solved using the most specific type possible:

x=print_capitalized('a string')reveal_type(x)# revealed type is strclassStringSubclass(str):passy=print_capitalized(StringSubclass('another string'))reveal_type(y)# revealed type is StringSubclassz=print_capitalized(45)# error: int is not a subtype of str

The upper bound of a type variable can be a concrete type, abstract type(ABC or Protocol), or even a union of types:

# Can be anything with an __abs__ methoddefprint_abs[T:SupportsAbs](arg:T)->None:print("Absolute value:",abs(arg))U=TypeVar('U',bound=str|bytes)# Can be any subtype of the union str|bytesV=TypeVar('V',bound=SupportsAbs)# Can be anything with an __abs__ method

Using aconstrained type variable, however, means that theTypeVarcan only ever be solved as being exactly one of the constraints given:

a=concatenate('one','two')reveal_type(a)# revealed type is strb=concatenate(StringSubclass('one'),StringSubclass('two'))reveal_type(b)# revealed type is str, despite StringSubclass being passed inc=concatenate('one',b'two')# error: type variable 'A' can be either str or bytes in a function call, but not both

在 runtimeisinstance(x,T) 會引發TypeError。

__name__¶

The name of the type variable.

__covariant__¶

Whether the type var has been explicitly marked as covariant.

__contravariant__¶

Whether the type var has been explicitly marked as contravariant.

__infer_variance__¶

Whether the type variable's variance should be inferred by type checkers.

在 3.12 版被加入.

__bound__¶

The upper bound of the type variable, if any.

在 3.12 版的變更:For type variables created throughtype parameter syntax,the bound is evaluated only when the attribute is accessed, not whenthe type variable is created (seeLazy evaluation).

__constraints__¶

A tuple containing the constraints of the type variable, if any.

在 3.12 版的變更:For type variables created throughtype parameter syntax,the constraints are evaluated only when the attribute is accessed, not whenthe type variable is created (seeLazy evaluation).

__default__¶

The default value of the type variable, ortyping.NoDefault if ithas no default.

在 3.13 版被加入.

has_default()¶

Return whether or not the type variable has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.

在 3.13 版被加入.

在 3.12 版的變更:Type variables can now be declared using thetype parameter syntax introduced byPEP 695.Theinfer_variance parameter was added.

在 3.13 版的變更:新增對預設值的支援。

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

Type variable tuple. A specialized form oftype variablethat enablesvariadic generics.

Type variable tuples can be declared intype parameter listsusing a single asterisk (*) before the name:

defmove_first_element_to_last[T,*Ts](tup:tuple[T,*Ts])->tuple[*Ts,T]:return(*tup[1:],tup[0])

Or by explicitly invoking theTypeVarTuple constructor:

T=TypeVar("T")Ts=TypeVarTuple("Ts")defmove_first_element_to_last(tup:tuple[T,*Ts])->tuple[*Ts,T]:return(*tup[1:],tup[0])

A normal type variable enables parameterization with a single type. A typevariable tuple, in contrast, allows parameterization with anarbitrary number of types by acting like anarbitrary number of typevariables wrapped in a tuple. For example:

# T is bound to int, Ts is bound to ()# Return value is (1,), which has type tuple[int]move_first_element_to_last(tup=(1,))# T is bound to int, Ts is bound to (str,)# Return value is ('spam', 1), which has type tuple[str, int]move_first_element_to_last(tup=(1,'spam'))# T is bound to int, Ts is bound to (str, float)# Return value is ('spam', 3.0, 1), which has type tuple[str, float, int]move_first_element_to_last(tup=(1,'spam',3.0))# This fails to type check (and fails at runtime)# because tuple[()] is not compatible with tuple[T, *Ts]# (at least one element is required)move_first_element_to_last(tup=())

Note the use of the unpacking operator* intuple[T,*Ts].Conceptually, you can think ofTs as a tuple of type variables(T1,T2,...).tuple[T,*Ts] would then becometuple[T,*(T1,T2,...)], which is equivalent totuple[T,T1,T2,...]. (Note that in older versions of Python, you mightsee this written usingUnpack instead, asUnpack[Ts].)

Type variable tuples mustalways be unpacked. This helps distinguish typevariable tuples from normal type variables:

x:Ts# 無效x:tuple[Ts]# 無效x:tuple[*Ts]# 正確的做法

Type variable tuples can be used in the same contexts as normal typevariables. For example, in class definitions, arguments, and return types:

classArray[*Shape]:def__getitem__(self,key:tuple[*Shape])->float:...def__abs__(self)->"Array[*Shape]":...defget_shape(self)->tuple[*Shape]:...

Type variable tuples can be happily combined with normal type variables:

classArray[DType,*Shape]:# This is finepassclassArray2[*Shape,DType]:# This would also be finepassclassHeight:...classWidth:...float_array_1d:Array[float,Height]=Array()# Totally fineint_array_2d:Array[int,Height,Width]=Array()# Yup, fine too

However, note that at most one type variable tuple may appear in a singlelist of type arguments or type parameters:

x:tuple[*Ts,*Ts]# 無效classArray[*Shape,*Shape]:# 無效pass

Finally, an unpacked type variable tuple can be used as the type annotationof*args:

defcall_soon[*Ts](callback:Callable[[*Ts],None],*args:*Ts)->None:...callback(*args)

In contrast to non-unpacked annotations of*args - e.g.*args:int,which would specify thatall arguments areint -*args:*Tsenables reference to the types of theindividual arguments in*args.Here, this allows us to ensure the types of the*args passedtocall_soon match the types of the (positional) arguments ofcallback.

SeePEP 646 for more details on type variable tuples.

__name__¶

The name of the type variable tuple.

__default__¶

The default value of the type variable tuple, ortyping.NoDefault if ithas no default.

在 3.13 版被加入.

has_default()¶

Return whether or not the type variable tuple has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.

在 3.13 版被加入.

在 3.11 版被加入.

在 3.12 版的變更:Type variable tuples can now be declared using thetype parameter syntax introduced byPEP 695.

在 3.13 版的變更:新增對預設值的支援。

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

Parameter specification variable. A specialized version oftype variables.

Intype parameter lists, parameter specificationscan be declared with two asterisks (**):

typeIntFunc[**P]=Callable[P,int]

For compatibility with Python 3.11 and earlier,ParamSpec objectscan also be created as follows:

P=ParamSpec('P')

Parameter specification variables exist primarily for the benefit of statictype checkers. They are used to forward the parameter types of onecallable to another callable -- a pattern commonly found in higher orderfunctions and decorators. They are only valid when used inConcatenate,or as the first argument toCallable, or as parameters for user-definedGenerics. SeeGeneric for more information on generic types.

For example, to add basic logging to a function, one can create a decoratoradd_logging to log function calls. The parameter specification variabletells the type checker that the callable passed into the decorator and thenew callable returned by it have inter-dependent type parameters:

fromcollections.abcimportCallableimportloggingdefadd_logging[T,**P](f:Callable[P,T])->Callable[P,T]:'''A type-safe decorator to add logging to a function.'''definner(*args:P.args,**kwargs:P.kwargs)->T:logging.info(f'{f.__name__} was called')returnf(*args,**kwargs)returninner@add_loggingdefadd_two(x:float,y:float)->float:'''Add two numbers together.'''returnx+y

WithoutParamSpec, the simplest way to annotate this previously was touse aTypeVar with upper boundCallable[...,Any]. However thiscauses two problems:

1. The type checker can't type check theinner function because*args and**kwargs have to be typedAny.

2. cast() may be required in the body of theadd_loggingdecorator when returning theinner function, or the static typechecker must be told to ignore thereturninner.

args¶

kwargs¶

SinceParamSpec captures both positional and keyword parameters,P.args andP.kwargs can be used to split aParamSpec into itscomponents.P.args represents the tuple of positional parameters in agiven call and should only be used to annotate*args.P.kwargsrepresents the mapping of keyword parameters to their values in a given call,and should be only be used to annotate**kwargs. Bothattributes require the annotated parameter to be in scope. At runtime,P.args andP.kwargs are instances respectively ofParamSpecArgs andParamSpecKwargs.

__name__¶

The name of the parameter specification.

__default__¶

The default value of the parameter specification, ortyping.NoDefault if ithas no default.

在 3.13 版被加入.

has_default()¶

Return whether or not the parameter specification has a default value. This is equivalentto checking whether__default__ is not thetyping.NoDefaultsingleton, except that it does not force evaluation of thelazily evaluated default value.

在 3.13 版被加入.

Parameter specification variables created withcovariant=True orcontravariant=True can be used to declare covariant or contravariantgeneric types. Thebound argument is also accepted, similar toTypeVar. However the actual semantics of these keywords are yet tobe decided.

在 3.10 版被加入.

在 3.12 版的變更:Parameter specifications can now be declared using thetype parameter syntax introduced byPEP 695.

在 3.13 版的變更:新增對預設值的支援。

備註

Only parameter specification variables defined in global scope canbe pickled.

也參考

• PEP 612 -- 參數技術規範變數

• Concatenate

• 註釋 callable 物件

typing.ParamSpecArgs¶

typing.ParamSpecKwargs¶

Arguments and keyword arguments attributes of aParamSpec. TheP.args attribute of aParamSpec is an instance ofParamSpecArgs,andP.kwargs is an instance ofParamSpecKwargs. They are intendedfor runtime introspection and have no special meaning to static type checkers.

Callingget_origin() on either of these objects will return theoriginalParamSpec:

>>>fromtypingimportParamSpec,get_origin>>>P=ParamSpec("P")>>>get_origin(P.args)isPTrue>>>get_origin(P.kwargs)isPTrue

在 3.10 版被加入.

classtyping.TypeAliasType(name,value,*,type_params=())¶

The type of type aliases created through thetype statement.

舉例來說：

>>>typeAlias=int>>>type(Alias)<class 'typing.TypeAliasType'>

在 3.12 版被加入.

__name__¶

The name of the type alias:

>>>typeAlias=int>>>Alias.__name__'Alias'

__module__¶

The module in which the type alias was defined:

>>>typeAlias=int>>>Alias.__module__'__main__'

__type_params__¶

The type parameters of the type alias, or an empty tuple if the alias isnot generic:

>>>typeListOrSet[T]=list[T]|set[T]>>>ListOrSet.__type_params__(T,)>>>typeNotGeneric=int>>>NotGeneric.__type_params__()

__value__¶

The type alias's value. This islazily evaluated,so names used in the definition of the alias are not resolved until the__value__ attribute is accessed:

>>>typeMutually=Recursive>>>typeRecursive=Mutually>>>MutuallyMutually>>>RecursiveRecursive>>>Mutually.__value__Recursive>>>Recursive.__value__Mutually

Other special directives¶

These functions and classes should not be used directly as annotations.Their intended purpose is to be building blocks for creating and declaringtypes.

classtyping.NamedTuple¶

Typed version ofcollections.namedtuple().

用法：

classEmployee(NamedTuple):name:strid:int

這等價於：

Employee=collections.namedtuple('Employee',['name','id'])

To give a field a default value, you can assign to it in the class body:

classEmployee(NamedTuple):name:strid:int=3employee=Employee('Guido')assertemployee.id==3

Fields with a default value must come after any fields without a default.

The resulting class has an extra attribute__annotations__ giving adict that maps the field names to the field types. (The field names are inthe_fields attribute and the default values are in the_field_defaults attribute, both of which are part of thenamedtuple()API.)

NamedTuple subclasses can also have docstrings and methods:

classEmployee(NamedTuple):"""Represents an employee."""name:strid:int=3def__repr__(self)->str:returnf'<Employee{self.name}, id={self.id}>'

NamedTuple subclasses can be generic:

classGroup[T](NamedTuple):key:Tgroup:list[T]

Backward-compatible usage:

# For creating a generic NamedTuple on Python 3.11T=TypeVar("T")classGroup(NamedTuple,Generic[T]):key:Tgroup:list[T]# A functional syntax is also supportedEmployee=NamedTuple('Employee',[('name',str),('id',int)])

在 3.6 版的變更:Added support forPEP 526 variable annotation syntax.

在 3.6.1 版的變更:Added support for default values, methods, and docstrings.

在 3.8 版的變更:The_field_types and__annotations__ attributes arenow regular dictionaries instead of instances ofOrderedDict.

在 3.9 版的變更:Removed the_field_types attribute in favor of the morestandard__annotations__ attribute which has the same information.

在 3.11 版的變更:Added support for generic namedtuples.

Deprecated since version 3.13, will be removed in version 3.15:The undocumented keyword argument syntax for creating NamedTuple classes(NT=NamedTuple("NT",x=int)) is deprecated, and will be disallowedin 3.15. Use the class-based syntax or the functional syntax instead.

Deprecated since version 3.13, will be removed in version 3.15:When using the functional syntax to create a NamedTuple class, failing topass a value to the 'fields' parameter (NT=NamedTuple("NT")) isdeprecated. PassingNone to the 'fields' parameter(NT=NamedTuple("NT",None)) is also deprecated. Both will bedisallowed in Python 3.15. To create a NamedTuple class with 0 fields,useclassNT(NamedTuple):pass orNT=NamedTuple("NT",[]).

classtyping.NewType(name,tp)¶

Helper class to create low-overheaddistinct types.

ANewType is considered a distinct type by a typechecker. At runtime,however, calling aNewType returns its argument unchanged.

用法：

UserId=NewType('UserId',int)# Declare the NewType "UserId"first_user=UserId(1)# "UserId" returns the argument unchanged at runtime

__module__¶

The module in which the new type is defined.

__name__¶

The name of the new type.

__supertype__¶

The type that the new type is based on.

在 3.5.2 版被加入.

在 3.10 版的變更:NewType is now a class rather than a function.

classtyping.Protocol(Generic)¶

Base class for protocol classes.

Protocol classes are defined like this:

classProto(Protocol):defmeth(self)->int:...

Such classes are primarily used with static type checkers that recognizestructural subtyping (static duck-typing), for example:

classC:defmeth(self)->int:return0deffunc(x:Proto)->int:returnx.meth()func(C())# Passes static type check

SeePEP 544 for more details. Protocol classes decorated withruntime_checkable() (described later) act as simple-minded runtimeprotocols that check only the presence of given attributes, ignoring theirtype signatures. Protocol classes without this decorator cannot be usedas the second argument toisinstance() orissubclass().

Protocol classes can be generic, for example:

classGenProto[T](Protocol):defmeth(self)->T:...

In code that needs to be compatible with Python 3.11 or older, genericProtocols can be written as follows:

T=TypeVar("T")classGenProto(Protocol[T]):defmeth(self)->T:...

在 3.8 版被加入.

@typing.runtime_checkable¶

Mark a protocol class as a runtime protocol.

Such a protocol can be used withisinstance() andissubclass().This allows a simple-minded structural check, very similar to "one trick ponies"incollections.abc such asIterable. For example:

@runtime_checkableclassClosable(Protocol):defclose(self):...assertisinstance(open('/some/file'),Closable)@runtime_checkableclassNamed(Protocol):name:strimportthreadingassertisinstance(threading.Thread(name='Bob'),Named)

This decorator raisesTypeError when applied to a non-protocol class.

備註

runtime_checkable() will check only the presence of the requiredmethods or attributes, not their type signatures or types.For example,ssl.SSLObjectis a class, therefore it passes anissubclass()check againstCallable. However, thessl.SSLObject.__init__ method exists only to raise aTypeError with a more informative message, therefore makingit impossible to call (instantiate)ssl.SSLObject.

備註

Anisinstance() check against a runtime-checkable protocol can besurprisingly slow compared to anisinstance() check againsta non-protocol class. Consider using alternative idioms such ashasattr() calls for structural checks in performance-sensitivecode.

在 3.8 版被加入.

在 3.12 版的變更:The internal implementation ofisinstance() checks againstruntime-checkable protocols now usesinspect.getattr_static()to look up attributes (previously,hasattr() was used).As a result, some objects which used to be considered instancesof a runtime-checkable protocol may no longer be considered instancesof that protocol on Python 3.12+, and vice versa.Most users are unlikely to be affected by this change.

在 3.12 版的變更:The members of a runtime-checkable protocol are now considered "frozen"at runtime as soon as the class has been created. Monkey-patchingattributes onto a runtime-checkable protocol will still work, but willhave no impact onisinstance() checks comparing objects to theprotocol. See"What's new in Python 3.12"for more details.

classtyping.TypedDict(dict)¶

Special construct to add type hints to a dictionary.At runtime it is a plaindict.

TypedDict declares a dictionary type that expects all of itsinstances to have a certain set of keys, where each key isassociated with a value of a consistent type. This expectationis not checked at runtime but is only enforced by type checkers.Usage:

classPoint2D(TypedDict):x:inty:intlabel:stra:Point2D={'x':1,'y':2,'label':'good'}# OKb:Point2D={'z':3,'label':'bad'}# Fails type checkassertPoint2D(x=1,y=2,label='first')==dict(x=1,y=2,label='first')

An alternative way to create aTypedDict is by usingfunction-call syntax. The second argument must be a literaldict:

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

This functional syntax allows defining keys which are not valididentifiers, for example because they arekeywords or contain hyphens, or when key names must not bemangled like regular private names:

# raises SyntaxErrorclassPoint2D(TypedDict):in:int# 'in' is a keywordx-y:int# name with hyphensclassDefinition(TypedDict):__schema:str# mangled to `_Definition__schema`# OK, functional syntaxPoint2D=TypedDict('Point2D',{'in':int,'x-y':int})Definition=TypedDict('Definition',{'__schema':str})# not mangled

By default, all keys must be present in aTypedDict. It is possible tomark individual keys as non-required usingNotRequired:

classPoint2D(TypedDict):x:inty:intlabel:NotRequired[str]# 替代語法Point2D=TypedDict('Point2D',{'x':int,'y':int,'label':NotRequired[str]})

This means that aPoint2DTypedDict can have thelabelkey omitted.

It is also possible to mark all keys as non-required by defaultby specifying a totality ofFalse:

classPoint2D(TypedDict,total=False):x:inty:int# 替代語法Point2D=TypedDict('Point2D',{'x':int,'y':int},total=False)

This means that aPoint2DTypedDict can have any of the keysomitted. A type checker is only expected to support a literalFalse orTrue as the value of thetotal argument.True is the default,and makes all items defined in the class body required.

Individual keys of atotal=FalseTypedDict can be marked asrequired usingRequired:

classPoint2D(TypedDict,total=False):x:Required[int]y:Required[int]label:str# 替代語法Point2D=TypedDict('Point2D',{'x':Required[int],'y':Required[int],'label':str},total=False)

It is possible for aTypedDict type to inherit from one or more otherTypedDict typesusing the class-based syntax.Usage:

classPoint3D(Point2D):z:int

Point3D has three items:x,y andz. It is equivalent to thisdefinition:

classPoint3D(TypedDict):x:inty:intz:int

ATypedDict cannot inherit from a non-TypedDict class,except forGeneric. For example:

classX(TypedDict):x:intclassY(TypedDict):y:intclassZ(object):pass# 一個非 TypedDict 的類別classXY(X,Y):pass# OKclassXZ(X,Z):pass# 引發 TypeError

ATypedDict can be generic:

classGroup[T](TypedDict):key:Tgroup:list[T]

To create a genericTypedDict that is compatible with Python 3.11or lower, inherit fromGeneric explicitly:

T=TypeVar("T")classGroup(TypedDict,Generic[T]):key:Tgroup:list[T]

ATypedDict can be introspected via annotations dicts(see註釋 (annotation) 最佳實踐 for more information on annotations best practices),__total__,__required_keys__, and__optional_keys__.

__total__¶

Point2D.__total__ gives the value of thetotal argument.Example:

>>>fromtypingimportTypedDict>>>classPoint2D(TypedDict):pass>>>Point2D.__total__True>>>classPoint2D(TypedDict,total=False):pass>>>Point2D.__total__False>>>classPoint3D(Point2D):pass>>>Point3D.__total__True

This attribute reflectsonly the value of thetotal argumentto the currentTypedDict class, not whether the class is semanticallytotal. For example, aTypedDict with__total__ set toTrue mayhave keys marked withNotRequired, or it may inherit from anotherTypedDict withtotal=False. Therefore, it is generally better to use__required_keys__ and__optional_keys__ for introspection.

__required_keys__¶

在 3.9 版被加入.

__optional_keys__¶

Point2D.__required_keys__ andPoint2D.__optional_keys__ returnfrozenset objects containing required and non-required keys, respectively.

Keys marked withRequired will always appear in__required_keys__and keys marked withNotRequired will always appear in__optional_keys__.

For backwards compatibility with Python 3.10 and below,it is also possible to use inheritance to declare both required andnon-required keys in the sameTypedDict . This is done by declaring aTypedDict with one value for thetotal argument and theninheriting from it in anotherTypedDict with a different value fortotal:

>>>classPoint2D(TypedDict,total=False):...x:int...y:int...>>>classPoint3D(Point2D):...z:int...>>>Point3D.__required_keys__==frozenset({'z'})True>>>Point3D.__optional_keys__==frozenset({'x','y'})True

在 3.9 版被加入.

備註

Iffrom__future__importannotations is used or if annotationsare given as strings, annotations are not evaluated when theTypedDict is defined. Therefore, the runtime introspection that__required_keys__ and__optional_keys__ rely on may not workproperly, and the values of the attributes may be incorrect.

Support forReadOnly is reflected in the following attributes:

__readonly_keys__¶

Afrozenset containing the names of all read-only keys. Keysare read-only if they carry theReadOnly qualifier.

在 3.13 版被加入.

__mutable_keys__¶

Afrozenset containing the names of all mutable keys. Keysare mutable if they do not carry theReadOnly qualifier.

在 3.13 版被加入.

SeePEP 589 for more examples and detailed rules of usingTypedDict.

在 3.8 版被加入.

在 3.11 版的變更:Added support for marking individual keys asRequired orNotRequired.SeePEP 655.

在 3.11 版的變更:Added support for genericTypedDicts.

在 3.13 版的變更:Removed support for the keyword-argument method of creatingTypedDicts.

在 3.13 版的變更:Support for theReadOnly qualifier was added.

Deprecated since version 3.13, will be removed in version 3.15:When using the functional syntax to create a TypedDict class, failing topass a value to the 'fields' parameter (TD=TypedDict("TD")) isdeprecated. PassingNone to the 'fields' parameter(TD=TypedDict("TD",None)) is also deprecated. Both will bedisallowed in Python 3.15. To create a TypedDict class with 0 fields,useclassTD(TypedDict):pass orTD=TypedDict("TD",{}).