[Python-ideas] More Metadata for Variable Annotations

[Guido van Rossum]

A similar approach (though only for class/instance variables) is taken by
the 'attrs' package and by the proposal currently code-named "dataclasses" (
https://github.com/ericvsmith/dataclasses).

On Fri, Aug 18, 2017 at 10:48 AM, Ivan Levkivskyi <levkivskyi at gmail.com>
wrote:

> 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/
>>
>>
>
> _______________________________________________
> 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/
>
>


-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20170818/e6fc1449/attachment.html>