search

pypa / readme_renderer

Safely render long_description/README files in Warehouse
Apache License 2.0
158 stars 89 forks source link

correct way to validate using readme_renderer with an exit code #151

Closed svenevs closed 5 years ago

svenevs commented 5 years ago

It used to be python setup.py check -r -s, which still currently works, but says:

warning: Check: This command has been deprecated. Use `twine check` instead: https://packaging.python.org/guides/making-a-pypi-friendly-readme#validating-restructuredtext-markup

warning: Check: The project's long_description is either missing or empty.

but it fails my test (tox) which is good. But if I run the suggested command:

$ twine check dist/*
Checking distribution ...whl
warning: `long_description_content_type` missing.  defaulting to `text/x-rst`.
warning: `long_description` missing.
Passed
Checking distribution ...tar.gz:
warning: `long_description_content_type` missing.  defaulting to `text/x-rst`.
warning: `long_description` missing.
Passed
$ echo $?
0

It is helpful to have a failing exit code on warnings somehow, specifically on the package artifacts. python -m readme_renderer invalid.rst will give a non-zero exit code on invalid RST for example, but I parse my README and extract a couple of things, so I can't use that directly.

I didn't know if this was a twine issue or an issue here...sorry if I chose the wrong repo!

di commented 5 years ago

In this example, python setup.py check -r -s is failing because you're telling it to validate the long_description, but there is no long description to validate, so it fails.

However, twine check dist/* is passing because you're telling it to validate the build artifacts, not just the description. This uses the same checks that PyPI uses to determine if an artifact can be published or not. And since a build artifact without a description is a valid distribution, it passes.

We need to migrate to validating the build artifacts instead to prepare for the future when metadata is not necessarily stored in a setup.py file. So, without making the long_description field required, this is expected behavior and there isn't really anything to do here besides warn you that long_description is missing.

svenevs commented 5 years ago

Ah interesting. Thank you for explaining the changes in how this works. I'm ok with paying attention to output...it's not like the setup scripts change that much xD