Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

long_description vs. pyproject.toml #1535

Open
0cjs opened this issue Apr 23, 2024 · 3 comments
Open

long_description vs. pyproject.toml #1535

0cjs opened this issue Apr 23, 2024 · 3 comments
Labels
component: guides type: task Something that needs to be done that is not a bug or feature

Comments

@0cjs
Copy link

0cjs commented Apr 23, 2024

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
Copy link
Member

webknjaz commented Apr 23, 2024

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
Copy link
Author

0cjs commented Apr 23, 2024

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
Copy link
Member

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.

@chrysle chrysle added type: task Something that needs to be done that is not a bug or feature component: guides labels May 9, 2024
0cjs added a commit to mc68-net/r8format that referenced this issue May 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component: guides type: task Something that needs to be done that is not a bug or feature
Projects
None yet
Development

No branches or pull requests

4 participants
@webknjaz @0cjs @chrysle and others