PEP 727: Documentation Metadata in Typing

[pf_moore (Paul Moore)]

@tiangolo

An argument content_type and explicit MIME types sound very long to be typing it in code (what is supported in pyproject.toml), that’s why I propose format. I would think a shorter syntax with the main predefined formats with short names and a default of Markdown.

Frankly, I think that if a documentation string for an argument needs to use Markdown or ReST, it’s already way too long for me to be happy seeing it in the argument list of a function (as opposed to the docstring, which is intended for long-form textual information). And equally, if you’re writing enough text to care about ReST vs Markdown, saving a few characters doesn’t seem worth the cost of not conforming with the existing (pyproject.toml) approach.