PEP 727: Documentation Metadata in Typing

PEPs
19

Thanks for the input @Zomatree !

I don’t feel that Annotated should be used by other typing functions but rather be for 3rd parties to add additional metadata, leaning on Annotated for this type of feature feels like a hack.

As this is not altering the semantics of Annotated, I think it could be considered working in the same way as a third party library. The same way dataclasses are something that could perfectly be a third-party library (it was even inspired by one), but it makes sense to have a centralized option.

A side note: having a centralized option doesn’t mean enforcing it, the same way dataclasses are not enforced nor the only option, many people prefer to use attrs or pydantic.

If you’re concern is about using a space (Annotated) that should be somewhat reserved for third-party libraries that use Annotated, like FastAPI, Pydantic, Strawberry, Typer, SQLModel… we are the main ones asking for this, and we intend to support re-using this now (hopefully) “standardized” way to document parameters and types, instead of only relying on each of our custom solutions for this.

Furthermore I don’t see the appeal of this over a docstring, you are already adding this to your own code so it should be trivial to include this information inside the docstring instead.

I would encourage you to read the document. Most of the document is arguments for why this PEP would make sense.

In short, docstrings for parameters have several disadvantages, including:

  • info duplication
  • info resynchronization, because of the duplication… which in turn becomes a type of manual code cache invalidation for developers maintaining those docstrings
  • editor support for editing this information
  • runtime access to the information
  • simplification for tooling implementers to extract the information (no custom syntax parser needed)
  • No new micro syntax for developers to learn (not everyone knows all these microsyntaxes, but everyone knows Python)

This doesn’t feel like a feature which should be included in the stdlib.

There are several reasons why it would belong in the standard library (again, I encourage you to read the PEP).

Some reasons:

  • Bring consensus and standardization, this would make it easier for developers to adopt it for new projects, and for implementers to decide to support it (the implementation would be minimal).
  • No need for external libraries for this, developers of new packages could use it without installing something external (if they decided to do so).
2 Likes