<div dir="ltr"><div><div><div><div><div>Hi Bagrat,<br><br></div>Thanks for a detailed proposal! Indeed, some projects might want to have some additional metadata attached to a variable/argument besides its type.<br></div>However, I think it would be more productive to first discuss this on a more specialized forum like <a href="https://github.com/python/typing/issues">https://github.com/python/typing/issues</a><br><br>Note that similar proposals have been discussed and rejected before, see for example<br><a href="https://www.python.org/dev/peps/pep-0484/#what-about-existing-uses-of-annotations">https://www.python.org/dev/peps/pep-0484/#what-about-existing-uses-of-annotations</a><br></div>so that you would need to have a strong argument, for example some popular projects that will benefit from your proposal.<br><br></div>--<br></div>Ivan<br><div><div><div><br><br></div></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On 18 August 2017 at 17:09, Bagrat Aznauryan <span dir="ltr"><<a href="mailto:bagrat@aznauryan.org" target="_blank">bagrat@aznauryan.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div># Abstract</div><div><br></div><div>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:</div><div><br></div><div>* the type</div><div>* the human-readable description</div><div>* some value constraints (e.g. a range for integer variable)</div><div><br></div><div>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.<br></div><div><br></div><div>The idea is to make it possible to be able to include all of the mentioned metadata in the variable annotations.</div><div><br></div><div># Rationale</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div># Possible Solutions</div><div><br></div><div>## A wrapper</div><div><br></div><div>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:</div><div><br></div><div>```</div><div>foo: wrapper(</div><div> int,</div><div> description="bar",</div><div> minimum=0,</div><div> maximum=100</div><div>)</div><div>```</div><div><br></div><div>Later, the metadata can be accessed as the annotation attributes, like e.g.:</div><div><br></div><div>```</div><div>__annotations__['foo'].<wbr>description</div><div>```</div><div><br></div><div>## Annotation as a tuple</div><div><br></div><div>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:</div><div><br></div><div><div>```</div><div>foo: (</div><div> int,</div><div> {</div><div> description="bar",</div><div> minimum=0,</div><div> maximum=100</div><div> }</div><div>)</div><div>```</div><br class="m_2517875875583442038inbox-inbox-Apple-interchange-newline"></div><div>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.</div><div><br></div><div># Summary</div><div><br></div><div>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.</div><div><br></div><div>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.</div></div>
<br>______________________________<wbr>_________________<br>
Python-ideas mailing list<br>
<a href="mailto:Python-ideas@python.org">Python-ideas@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/python-ideas" rel="noreferrer" target="_blank">https://mail.python.org/<wbr>mailman/listinfo/python-ideas</a><br>
Code of Conduct: <a href="http://python.org/psf/codeofconduct/" rel="noreferrer" target="_blank">http://python.org/psf/<wbr>codeofconduct/</a><br>
<br></blockquote></div><br></div>