diff --git a/source/specifications.rst b/source/specifications.rst index 84d68d507..dd3b68b5e 100644 --- a/source/specifications.rst +++ b/source/specifications.rst @@ -21,7 +21,7 @@ The current core metadata file format, version 1.2, is specified in :pep:`345`. However, the version specifiers and environment markers sections of that PEP have been superceded as described below. In addition, metadata files are -permitted to contain the following additional field: +permitted to contain the following additional fields: Provides-Extra (multiple use) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -52,6 +52,86 @@ respectively. It is legal to specify ``Provides-Extra:`` without referencing it in any ``Requires-Dist:``. +Description-Content-Type +~~~~~~~~~~~~~~~~~~~~~~~~ + +A string stating the markup syntax (if any) used in the distribution's +description, so that tools can intelligently render the description. + +Historically, PyPI supported descriptions in plain text and `reStructuredText +(reST) `_, +and could render reST into HTML. However, it is common for distribution +authors to write the description in `Markdown +`_ (`RFC 7763 +`_) as many code hosting sites render +Markdown READMEs, and authors would reuse the file for the description. PyPI +didn't recognize the format and so could not render the description correctly. +This resulted in many packages on PyPI with poorly-rendered descriptions when +Markdown is left as plain text, or worse, was attempted to be rendered as reST. +This field allows the distribution author to specify the format of their +description, opening up the possibility for PyPI and other tools to be able to +render Markdown and other formats. + +The format of this field is the same as the ``Content-Type`` header in HTTP +(i.e.: +`RFC 1341 `_). +Briefly, this means that it has a ``type/subtype`` part and then it can +optionally have a number of parameters: + +Format:: + + Description-Content-Type: /; charset=[; = ...] + +The ``type/subtype`` part has only a few legal values: + +- ``text/plain`` +- ``text/x-rst`` +- ``text/markdown`` + +The ``charset`` parameter can be used to specify the character encoding of +the description. The only legal value is ``UTF-8``. If omitted, it is assumed to +be ``UTF-8``. + +Other parameters might be specific to the chosen subtype. For example, for the +``markdown`` subtype, there is an optional ``variant`` parameter that allows +specifying the variant of Markdown in use (defaults to ``CommonMark`` if not +specified). Currently, the only value that is recognized is: + +- ``CommonMark`` for `CommonMark + `_ + +Example:: + + Description-Content-Type: text/plain; charset=UTF-8 + +Example:: + + Description-Content-Type: text/x-rst; charset=UTF-8 + +Example:: + + Description-Content-Type: text/markdown; charset=UTF-8; variant=CommonMark + +Example:: + + Description-Content-Type: text/markdown + +If a ``Description-Content-Type`` is not specified, then applications should +attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to +``text/plain`` if it is not valid rst. + +If a ``Description-Content-Type`` is an unrecognized value, then the assumed +content type is ``text/plain`` (Although PyPI will probably reject anything +with an unrecognized value). + +If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is not +specified or is set to an unrecognized value, then the assumed ``variant`` is +``CommonMark``. + +So for the last example above, the ``charset`` defaults to ``UTF-8`` and the +``variant`` defaults to ``CommonMark`` and thus it is equivalent to the example +before it. + Version Specifiers ==================