Why do I have Description-Content-Type: UNKNOWN

Question

I recently discovered a new metadata in my .egg-info/PKG-INFO: Description-Content-Type.

When I run:

python setup.py egg_info

I get:

Description-Content-Type: UNKNOWN

For instance, how can I tell that I use Markdown (text/markdown)?

Answer 1

The metadata field Description-Content-Type was introduced in setuptools v36.4 (on Sept 2017). It is available in the Core Metadata v2.1.

You can use this metadata in you setup.py to specify the content type of your package Description.

The classic usage is to fill the long_description with the README file of your project. Then, you can use the long_description_content_type parameter to set the content-type.

The long description of your project is displayed in PyPi (the Python Package Index). You can read the PyPA article: “Including your README in your package’s metadata”.

Here is an example:

import io

from setuptools import setup


def read(filename):
    with io.open(filename, mode="r", encoding='utf-8') as fd:
        return fd.read()


setup(
    name="YourProject",
    version='1.2.3',

    description="One line description of your project",
    long_description=read("README.rst"),
    long_description_content_type='text/x-rst',

    ...
)

You can choose one of those content types:

• "text/plain": for simple text (eg.: "README" or "README.txt"),
• "text/x-rst": for reStructuredText (eg.: "README.rst"), or
• "text/markdown": for Markdown (eg.: "README.md").

Note: the support of Markdown is recent (you need setuptools >= 38.6).

Additionally, you can use twine to check the long description of your package (once the distribuable is built). For instance:

twine check dist/*