Open 0cjs opened 4 months ago
add
readme = 'README.md'
to the[project]
section ofpyproject.toml
, which will setlong_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).
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.)
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.
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 firstpyproject.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 tosetup.py
that does aread_text()
onREADME.md
, and manually pass that andlong_description_content_type='text/markdown'
to thesetup()
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 ofpyproject.toml
, which will setlong_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 thanpyproject.toml
.