[Python-ideas] More Metadata for Variable Annotations

[Ivan Levkivskyi]

Hi Bagrat,

Thanks for a detailed proposal! Indeed, some projects might want to have
some additional metadata attached to a variable/argument besides its type.
However, I think it would be more productive to first discuss this on a
more specialized forum like https://github.com/python/typing/issues

Note that similar proposals have been discussed and rejected before, see
for example
https://www.python.org/dev/peps/pep-0484/#what-about-existing-uses-of-annotations
so that you would need to have a strong argument, for example some popular
projects that will benefit from your proposal.

--
Ivan



On 18 August 2017 at 17:09, Bagrat Aznauryan <bagrat at aznauryan.org> wrote:

> # 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.
>
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20170818/2ec7435e/attachment.html>