[Python-ideas] More Metadata for Variable Annotations

[Bagrat Aznauryan]

# Abstract

Before the holly PEP-526 the only option for type hints were comments. And
before PEP-484 the docstrings were the main place where variable metadata
would go. That variable metadata would include:

* the type
* the human-readable description
* some value constraints (e.g. a range for integer variable)

PEP-526 introduced the awesome syntax sugar, which made the first part of
the metadata - the type, easily introspectable during the runtime. However,
if you still need to add the description and the value constraints to the
variable metadata, you still need to fallback to the docstring option.

The idea is to make it possible to be able to include all of the mentioned
metadata in the variable annotations.

# Rationale

Having the type specified using the supported annotation syntax and the
rest of the metadata in the docstrings, adds duplication and complexity for
further maintenance. Moreover, if you need the docstring-contained metadata
to be used in the runtime, you need to implement a parser or pick one from
existing ones which adds another dependency to your application.

The need for the rest of the metadata other than the type, might be proven
to be common. A typical example is generating the JSON Schema for a class,
e.g. to be used for OpenAPI definition of your API.

# Possible Solutions

## A wrapper

The proposal is to introduce a new wrapper (probably a function), that will
accept the type as the first positional argument and additional keyword
arguments for metadata. The wrapper will map the keyword arguments to the
type object as attributes and return it. The code would look like this:

```
foo: wrapper(
    int,
    description="bar",
    minimum=0,
    maximum=100
)
```

Later, the metadata can be accessed as the annotation attributes, like e.g.:

```
__annotations__['foo'].description
```

## Annotation as a tuple

This solution does not require any code change in Python, but will force
other tools change the parsing (e.g. mypy). The proposal is that when the
annotation is optionally a tuple instance, use the first element as the
type of the variable, and ignore the rest or treat as additional metadata.
This will make it possible to add the metadata into a separate dictionary
as the second element of the annotation tuple. For example:

```
foo: (
    int,
    {
        description="bar",
        minimum=0,
        maximum=100
    }
)
```

The annotation will be stored as is, so to access the metadata in the
runtime, one would need to explicitly access the second item of the
annotation tuple.

# Summary

This option would help to have a well annotated code which will be
self-descriptive and provide abilities to generate schemas and other
definitions (e.g. OpenAPI) automatically and without duplication.

The proposed solutions are definitely not perfect and not the main point of
this email. The target is to describe the idea and motivation and start a
discussion.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20170818/27965409/attachment.html>