PyPI not rendering ReST long_description
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST? Wichert.
On Sun, Jul 13, 2014 at 9:04 AM, Wichert Akkerman <wichert@wiggy.net> wrote:
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST?
I filed a PyPI issue about this some time before July 2012. It bothers me that I can't seem to find the issue listed on the current PyPI issues page: https://bitbucket.org/pypa/pypi/issues . It also disturbs me that I can't seem to find the issue on the old SourceForge page either: http://sourceforge.net/projects/pypi/ . The only thing I have to go on is this link which no longer goes anywhere: http://sourceforge.net/tracker/?func=detail&aid=3539253&group_id=66150&atid=513503 I had included it in a related issue I filed on the main Python bug tracker: http://bugs.python.org/issue15266 If I recall, my suggestion in the PyPI issue I filed was three-fold: 1) When uploading a reST long_description to PyPI via the command-line, PyPI should provide an error message saying why the conversion to HTML failed (so the user knows what to fix). 2) When setting a reST long_description on PyPI via the web UI, PyPI should provide an error message saying why the conversion to HTML failed (so the user knows what to fix). 3) The user should have some way of running the conversion locally (as a check), using the same rules as PyPI, so the user can be assured in advance that the conversion will be successful when interacting with the real PyPI. The third suggestion was the subject of the Distutils issue I filed on the main Python bug tracker. On a related note, in the new packaging docs about registering and uploading packages to PyPI: https://packaging.python.org/en/latest/tutorial.html#uploading-your-project-... I don't the see the troubleshooting tip that the old packaging docs contained, namely the advice to try running: $ python setup.py --long-description | rst2html.py > output.html The old location is here: https://docs.python.org/2.7/distutils/packageindex.html#pypi-package-display . It would be good if someone went through that page in its entirety and made sure that any useful information is copied over or otherwise reflected in the new packaging docs. --Chris
Wichert.
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
On 13 Jul 2014, at 21:36, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
On Sun, Jul 13, 2014 at 9:04 AM, Wichert Akkerman <wichert@wiggy.net> wrote:
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST?
I filed a PyPI issue about this some time before July 2012.
It bothers me that I can't seem to find the issue listed on the current PyPI issues page: https://bitbucket.org/pypa/pypi/issues . It also disturbs me that I can't seem to find the issue on the old SourceForge page either: http://sourceforge.net/projects/pypi/ .
That is somewhat worrying. I created a new ticket for this: https://bitbucket.org/pypa/pypi/issue/161/rest-formatting-fails-and-there-is...
3) The user should have some way of running the conversion locally (as a check), using the same rules as PyPI, so the user can be assured in advance that the conversion will be successful when interacting with the real PyPI.
I don’t believe that is a viable approach. I suspect there is a reasonable risk that environment changes between PyPI and your local system, for example environment settings or available locals, and using different versions of packages such as docutils will lead to incorrect results. There really is no substitute for PyPI itself reporting errors it finds. Wichert.
On Jul 13, 2014, at 4:35 PM, Wichert Akkerman <wichert@wiggy.net> wrote:
On 13 Jul 2014, at 21:36, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
On Sun, Jul 13, 2014 at 9:04 AM, Wichert Akkerman <wichert@wiggy.net> wrote:
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST?
I filed a PyPI issue about this some time before July 2012.
It bothers me that I can't seem to find the issue listed on the current PyPI issues page: https://bitbucket.org/pypa/pypi/issues . It also disturbs me that I can't seem to find the issue on the old SourceForge page either: http://sourceforge.net/projects/pypi/ .
That is somewhat worrying. I created a new ticket for this: https://bitbucket.org/pypa/pypi/issue/161/rest-formatting-fails-and-there-is...
3) The user should have some way of running the conversion locally (as a check), using the same rules as PyPI, so the user can be assured in advance that the conversion will be successful when interacting with the real PyPI.
I don’t believe that is a viable approach. I suspect there is a reasonable risk that environment changes between PyPI and your local system, for example environment settings or available locals, and using different versions of packages such as docutils will lead to incorrect results. There really is no substitute for PyPI itself reporting errors it finds.
Wichert.
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
Currently PyPI has no method to report that it has failed except to fail the upload with a message. This isn’t acceptable because we don’t mandate ReST and some people want to just have plain text uploads. With PyPI/Metadata 2.0 this is getting resolved in a way that’ll make all of this possible as well as additional renderers. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 13 Jul 2014, at 23:06, Donald Stufft <donald@stufft.io> wrote: Currently PyPI has no method to report that it has failed except to fail the upload with a message. This isn’t acceptable because we don’t mandate ReST and some people want to just have plain text uploads. With PyPI/Metadata 2.0 this is getting resolved in a way that’ll make all of this possible as well as additional renderers.
Doesn’t that still leave the other two options as possible right now? Wichert.
On Sun, Jul 13, 2014 at 1:35 PM, Wichert Akkerman <wichert@wiggy.net> wrote:
On 13 Jul 2014, at 21:36, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
On Sun, Jul 13, 2014 at 9:04 AM, Wichert Akkerman <wichert@wiggy.net> wrote:
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST?
I filed a PyPI issue about this some time before July 2012.
It bothers me that I can't seem to find the issue listed on the current PyPI issues page: https://bitbucket.org/pypa/pypi/issues . It also disturbs me that I can't seem to find the issue on the old SourceForge page either: http://sourceforge.net/projects/pypi/ .
That is somewhat worrying. I created a new ticket for this: https://bitbucket.org/pypa/pypi/issue/161/rest-formatting-fails-and-there-is...
3) The user should have some way of running the conversion locally (as a check), using the same rules as PyPI, so the user can be assured in advance that the conversion will be successful when interacting with the real PyPI.
I don’t believe that is a viable approach. I suspect there is a reasonable risk that environment changes between PyPI and your local system, for example environment settings or available locals, and using different versions of packages such as docutils will lead to incorrect results. There really is no substitute for PyPI itself reporting errors it finds.
I was suggesting this in addition to PyPI reporting errors and not as a substitute. It shouldn't be necessary to interact with a remote service when developing locally to validate and check for errors. --Chris
On 13 Jul 2014, at 18:04, Wichert Akkerman <wichert@wiggy.net> wrote:
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST?
I ended up debugging this by manually bisecting the long description through the PyPI web-interface. The culprit turned out to be this bit: `Pyramid <docs.pylonsproject.org/projects/pyramid/en/latest/>`_ This is perfectly valid ReST, but I am guessing PyPI somehow forbids you from using URLs without a scheme. Wichert.
Hi, I just want to note that I'm aware of this issue and I have "do something about it" in my long TODO. That link is malformed in any case - docutils just passes it on through and you're just lucky that browsers will guess that it is supposed to have a "http://" scheme on the front. PyPI does indeed check URL schemes in links for security reasons. I guess I never though that I'd need to allow a blank one - I'd have to think about the implications of allowing it. Richard On 14 July 2014 17:30, Wichert Akkerman <wichert@wiggy.net> wrote:
On 13 Jul 2014, at 18:04, Wichert Akkerman <wichert@wiggy.net> wrote:
I just uploaded a new pyramid_sqlalchemy package to PyPI. Looking at the distribution page at https://pypi.python.org/pypi/pyramid_sqlalchemy PyPI is not rendering ReST. I can’t figure out why though: according to both “python setup.py check” and "python setup.py --long-description | rst2html-2.7.py > /dev/null” there are no ReST syntax errors in me description. Is there any way to see why PyPI is not rendering my ReST?
I ended up debugging this by manually bisecting the long description through the PyPI web-interface. The culprit turned out to be this bit:
`Pyramid <docs.pylonsproject.org/projects/pyramid/en/latest/>`_
This is perfectly valid ReST, but I am guessing PyPI somehow forbids you from using URLs without a scheme.
Wichert.
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
On 15 Jul 2014, at 11:22, Richard Jones <richard@python.org> wrote:
Hi, I just want to note that I'm aware of this issue and I have "do something about it" in my long TODO.
That link is malformed in any case - docutils just passes it on through and you're just lucky that browsers will guess that it is supposed to have a "http://" scheme on the front. PyPI does indeed check URL schemes in links for security reasons. I guess I never though that I'd need to allow a blank one - I'd have to think about the implications of allowing it.
I don’t particularly mind PyPI refusing URL without a scheme – that is a perfectly reasonably precaution. The problem is that there is no way at all to see why PyPI was refusing to render my ReST without manually bisecting the long description manually through its web-interface. Wichert.
Yep, I understand and sympathise with the frustration. On 15 July 2014 19:24, Wichert Akkerman <wichert@wiggy.net> wrote:
On 15 Jul 2014, at 11:22, Richard Jones <richard@python.org> wrote:
Hi, I just want to note that I'm aware of this issue and I have "do something about it" in my long TODO.
That link is malformed in any case - docutils just passes it on through and you're just lucky that browsers will guess that it is supposed to have a "http://" scheme on the front. PyPI does indeed check URL schemes in links for security reasons. I guess I never though that I'd need to allow a blank one - I'd have to think about the implications of allowing it.
I don’t particularly mind PyPI refusing URL without a scheme – that is a perfectly reasonably precaution. The problem is that there is no way at all to see why PyPI was refusing to render my ReST without manually bisecting the long description manually through its web-interface.
Wichert.
On Tue, Jul 15, 2014 at 2:24 AM, Wichert Akkerman <wichert@wiggy.net> wrote:
On 15 Jul 2014, at 11:22, Richard Jones <richard@python.org> wrote:
Hi, I just want to note that I'm aware of this issue and I have "do something about it" in my long TODO.
That link is malformed in any case - docutils just passes it on through and you're just lucky that browsers will guess that it is supposed to have a "http://" scheme on the front. PyPI does indeed check URL schemes in links for security reasons. I guess I never though that I'd need to allow a blank one - I'd have to think about the implications of allowing it.
I don’t particularly mind PyPI refusing URL without a scheme – that is a perfectly reasonably precaution. The problem is that there is no way at all to see why PyPI was refusing to render my ReST without manually bisecting the long description manually through its web-interface.
One possible interim solution is to add a "check ReST" form to PyPI's web UI. The form could simply display the error output of running PyPI's conversion to HTML on whatever text is given. That would address Donald's point that it's not acceptable to fail an upload, while still giving people *some* reasonable way to troubleshoot failures. The existence of the validation form could be documented in the PyPI upload docs. --Chris
participants (4)
-
Chris Jerdonek -
Donald Stufft -
Richard Jones -
Wichert Akkerman