32

I'm having a hard time understanding from the documentation exactly what typing.Annotated is good for and an even harder time finding explanations/examples outside the documentation.

Or does it "being good for something" depend entirely on what third party libraries you're using? In what (real-world) context would you use Annotated?

Jesse
  • 860
  • 1
  • 11
  • 13
  • 4
    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. – Samwise Apr 17 '22 at 01:37
  • 5
    Just want to share [this real-world](https://pydantic-docs.helpmanual.io/usage/schema/#typingannotated-fields) 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. – Jesse May 16 '22 at 10:44
  • 1
    Much like function annotations were originally designed to attach arbitrary metadata to function parameters and the function's return value (not the value returned by any specific call to the function), `Annotated` lets you attach arbitrary metadata (though still with an eye towards using that for further type checking) to the type itself in a function or variable annotation. – chepner Mar 19 '23 at 20:52

4 Answers4

14

Simply, it is a way of saying that there is metadata x for the type T:

Annotated[T, x]

use of which entirely depends on the library you are using (or your code)

Ultimately, the responsibility of how to interpret the annotations (if at all) is the responsibility of the tool or library encountering the Annotated type.

You can use it as a lazy type checking as in strawberry, since it can be safely ignored as explained above:

If a library (or tool) encounters a typehint Annotated[T, x] and has no special logic for metadata x, it should ignore it and simply treat the type as T.

Or you can use it for safer typing as in FastAPI

innomatic
  • 170
  • 2
  • 6
13

FastAPI 0.9.5 (released yesteday) adds support for dependencies and parameters using Annotated. Through the documentation good examples and explanations can be found of its usage, such as:

Fabio Ramalho
  • 161
  • 1
  • 9
10

Annotated in python allows devs to declare type of a reference and and also to 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.

Mirza Haider
  • 161
  • 2
  • 4
4

In my case I am using it for Lazy Types in the strawberry GraphQL library. It's pretty useful if you have circular dependencies between types.
Example: https://strawberry.rocks/docs/types/lazy
oc7o

oc7o
  • 66
  • 3