long_description vs. pyproject.toml

[0cjs]

I recently uploaded my first package to PyPI and immediately discovered that I didn't get the nice long description that all the other packages have. As it turns out, this is because I didn't have a long_description field set when uploading, which was news to me. I feel that the the basic "Here's how you set up your first pyproject.toml" instructions should include something about that (properly explained in light of further notes below).

I can't recall now where I was sent in this documentation to fix this (or how I got to a link that sent me there), but I think I eventually ended up at Making a PyPI-friendly README, which is clearly relevant documentation. However, this mentions nothing about pyproject.toml and only suggests that you add Python code to setup.py that does a read_text() on README.md, and manually pass that and long_description_content_type='text/markdown' to the setup() function.

After some searching about, it appears that the correct (and far easier) way to do this is simply to add readme = 'README.md' to the [project] section of pyproject.toml, which will set long_description to the contents of that file and, based on the extension, long_description_content_type = 'text/markdown'.

This should be documented there, and somewhere (possibly on the same page) should be an explanation that this generates the long description section on PyPI.org.

Ideally, there would also be something somewhere that shows how to generate the stuff that appears in the left-hand bar on PyPI.org, too, such as the home page, GitHub repo, etc.

#971 may be related to this, though that's about two and a half years old and is talking about using setup.cfg rather than pyproject.toml.

[webknjaz]

add readme = 'README.md' to the [project] section of pyproject.toml, which will set long_description to the contents of that file and, based on the extension, long_description_content_type = 'text/markdown'.

I think the part about setting the type automatically might be backend-specific (as in setuptools would do this and some other backend wouldn't, maybe). FWIW here's an example of how you can specify it explicitly: https://github.com/cherrypy/cheroot/blob/f156ccd/pyproject.toml#L68-L70.

P.S. long_description and long_description_content_type names are configuration settings that are specific to setuptools (so they can be seen in setup.cfg and/or setup.py). Now that the ecosystem is more diverse, setuptools is not the only way to build dists. Each of the build backends may have their own setting names so you should really check their docs. However, with PEP 621 being accepted and implemented by virtually every backend, some of the canonical metadata field names are standardized in a specific structure in pyproject.toml configs. For as long as you choose to use this standard, the metadata that is standardized can look the same allowing you to switch backends. Though, some backend-specific features may require changing the configs when you migrate between them, and some may not exist in other tools (especially if those are not just packaging but workflow tools).

[0cjs]

Setting the type automatically for .md and .rst files is required by PEP 621:

If the file path ends in a case-insensitive .md suffix, then tools MUST assume the content-type is text/markdown. If the file path ends in a case-insensitive .rst, then tools MUST assume the content-type is text/x-rst.

I'm not sure what the situation is with long_description, but an error mentioning that is what comes out in twine check dist/* when readme is not set in pyproject.toml. I don't think it's necessary to be perfect with this and cover every build and upload tool, but leading users to the right answer when using the most common build and upload tools and errors like that appear would be very helpful. (Presumably the more sophisticated workflow tools also have, or can have, better error reporting.)

[webknjaz]

twine check dist/*

Don't forget to always run this early in your CI pipeline with the --strict flag, before it even hits the CD phase.