How to use typing.Annotated

Jesse

24 Nov 2023, 19:10 UTC

38.2K views1

I'm having a hard time understanding what typing.Annotated is good for from the documentation and an even harder time finding explanations/examples outside the documentation. In what context would you use Annotated? Does it depend on third-party libraries?

4,948 following

1 answer

Accepted answer · original discussion

Mirza Haider

29 Nov 2023, 14:22 UTC

Permalink

Annotated in python allows developers to declare the type of a reference and provide additional information related to it.

name: Annotated[str, "first letter is capital"]

This tells that name is of type str and that name[0] is a capital letter.

On its own Annotated does not do anything other than assigning extra information (metadata) to a reference. It is up to another code, which can be a library, framework or your own code, to interpret the metadata and make use of it.

For example, FastAPI uses Annotated for data validation:

def read_items(q: Annotated[str, Query(max_length=50)])

Here the parameter q is of type str with a maximum length of 50. This information was communicated to FastAPI (or any other underlying library) using the Annotated keyword.

3 question comments

Use comments to ask for clarification. Post a solution as an answer.

SamwisePermalink

25 Nov 2023, 23:58 UTC

If you don't have a tool that makes use of this, and you aren't in the process of building one, I think you can safely ignore it. The idea behind it AFAICT is that you might in theory want to annotate a variable with something other than its type (like, say, a docstring, so that some hypothetical tool can use it to auto-generate documentation or something), and using typing.Annotation allows you to do that but also annotate it with the type.

JessePermalink

27 Nov 2023, 04:46 UTC

Just want to share this real-world use for any future wanderers who stumble across this question. The example is a data-serialization library called pydantic that uses Annotated to impose additional validators.

Keep exploring this topic

What is the difference between type-hinting a variable as an Iterable versus a Sequence?

I don't understand the difference when hinting Iterable and Sequence . What is the main difference between those two and when to use which? I think set is an Iterable but not Sequence , are there any built-in data type that is Sequence but not Iterable ? def foo(baz: Sequence[float]): ... # What is the difference? def bar(baz: Iterable

Python 3.10+: Optional[Type] or Type | None

Now that Python 3.10 has been released, is there any preference when indicating that a parameter or returned value might be optional, i.e., can be None . So what is preferred: Option 1: def f(parameter: Optional[int]) -> Optional[str]: Option 2: def f(parameter: int | None) -> str | None: Also, is there any preference between Type | None

Dynamically create Literal alias from list of valid values

I have a function which validates its argument to accept only values from a given list of valid options. Typing-wise, I reflect this behavior using a Literal type alias, like so: from typing import Literal VALID_ARGUMENTS = ['foo', 'bar'] Argument = Literal['foo', 'bar'] def func(argument: 'Argument') -> None: if argument not in

from __future__ import annotations

In the Python docs about __future__ , there is a table where it shows that annotations are "optional in" 3.7.0b1 and "mandatory in" 4.0, but I am still able to use annotations in 3.8.2 without importing annotations. Given that, what is the use of it? What do "optional" and "mandatory" here mean? >>> def add_int(a:int, b:int) -> int: ...

How to use typing.Annotated

1 answer

3 question comments

Your perspective belongs here.

Good answers start here.