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 <[email protected]> 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 > [email protected] > https://mail.python.org/mailman/listinfo/python-ideas > Code of Conduct: http://python.org/psf/codeofconduct/ > >
_______________________________________________ Python-ideas mailing list [email protected] https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
