Rename "/legacy" url to something else

[rsyring]

Original concern and Donald's reply below:

My setup.py has been communicating with https://upload.pypi.org/legacy/ by default. Note the legacy part.

This is confusing, and it is essentially due to the fact there are two things here which are considered “legacy”. One is the legacy codebase/deployment that currently powers pypi.python.org which are are slowly replacing and migrating things over to the new, modern code base that powers pypi.org. The other thing is the actual upload API itself, which has stayed the same currently, but which I plan to replace at some point in the future. This API is also considered “legacy” (it just doesn’t have a replacement yet). So the legacy in https://upload.pypi.org/legacy/ has to do with the API rather than the location/deployment.

I probably should have named it something other than /legacy/, my goal was mostly that changing URLs is hard (it requires a bunch of documentation/updates in different packages and N years for that to percolate out) so since we were forcing people to change the URLs with the move from pypi.python.org to pypi.org, might as well get it all done at once. It might be reasonable to name it something else now, and just keep the /legacy/ around as an alias. I’m not sure if that adds or subtracts from the confusion, but if you think that would have helped you, please open a new issue on Warehouse.

FWIW, something like "/api/v1" seems reasonable. I do think "/legacy" is confusing and renaming it now will be less confusing than keeping it.

[dstufft]

Probably if we do this, using v0 makes sense just to indicate this is some sort of weird not-designed API or something.

[brainwane]

@rsyring Thank you very much for suggesting this, and sorry for the slow response! I brought this issue up in a meeting of Warehouse developers today I want to walk you (and other Python developers reading this in the future) through what Warehouse's maintainers currently think about this question.

(For context: the folks working on Warehouse have gotten limited funding to concentrate on improving and deploying Warehouse, and have kicked off work towards our development roadmap -- the most urgent task is to improve Warehouse to the point where we can redirect pypi.python.org to pypi.org so the site is more sustainable and reliable.)

When I put this item on the meeting agenda, I was initially thinking: yes, it's currently a confusing URL, and as long as we're trying to get a lot of package maintainers to change their workflows, we should do this and coordinate with the distribution tools/docs folks so it changes everywhere at once.

As we were talking today, two counterarguments came up.

• in the past, we've already changed the URL once, and caused substantial client support confusion and frustration.
• We could make an alias, but that might just lead to more confusion in the long run, since /legacy would still be around and working, and some clients would use it.

So this needs further thought. And since this issue isn't a blocker to shutting down the old site, I've moved it to a future milestone.

Thanks and sorry again for the wait.

[ncoghlan]

FWIW, I added an explanation of the legacy in the URL to the end of https://packaging.python.org/guides/migrating-to-pypi-org/#publishing-releases when consolidating the two distinct sets of migration guidance that we had.

Note that our main recommendation is to upgrade twine, setuptools, and/or Python to get an updated default setting, not to adjust your config directly.

So while we could add the v0 alias, the exact URL is already mostly hidden from users that aren't stuck using older upload clients, and it isn't clear yet whether Warehouse is going to use API versioning in the URL, or instead provide graceful evolution of the individual endpoints.

[ncoghlan]

https://github.com/pypa/python-packaging-user-guide/issues/479 highlights a remaining case where the "legacy" in the URL is visible: when setting up use of test.pypi.org.

That currently looks like:

$ twine upload --repository-url https://test.pypi.org/legacy/ dist/* 

I think part of the problem in that case is that the phrasing of the legacy URL explanation at https://packaging.python.org/guides/using-testpypi/#using-test-pypi is confusing, but I also think it would likely be clearer with v1 as originally suggested above:

$ twine upload --repository-url https://test.pypi.org/v1/ dist/* 

Alternatively, we could stick an -api suffix in there to make it clear that the versioning info relates to the specific API, not the service itself:

$ twine upload --repository-url https://test.pypi.org/v1-api/ dist/* 
$ twine upload --repository-url https://test.pypi.org/legacy-api/ dist/* 

While the v0 idea was interesting, I think v1 or v1-api would be clearer, as we'll be calling the new upload API the "Version 2 upload API" for the sake of discussing the design, even if it doesn't actually end up with "v2" in the related URL endpoints.

[theacodes]

Sounds good to me- so all we really need to do here is change /legacy to /v1-api and keep an alias for /legacy so that no one breaks?

[theacodes]

Or more simply add a /v1-api alias for /legacy and leave /legacy alone.

I'm happy to make this change, but I actually can't find where this is configured.

[pradyunsg]

It seems to me to be at the following (but I've been wrong with regards to this codebase before):

https://github.com/pypa/warehouse/blob/54e59eab93be8aee21d96d993b64bf53272b9087/warehouse/forklift/action_routing.py#L16-L25

[kimyen]

I am looking for the URL to the new upload (not legacy) to test.pypi. I couldn't find it anywhere and my search takes me here. Is the new upload available for test.pypi?

My use case: I intended to use test.pypi as my "staging". I am writing an automated job that create the package distribution and push it to test.pypi. We hope that we can catch any bugs/ mistakes while the new version is released to test.pypi and have not been released to pypi. So it's critical for me that test.pypi behaves exactly the same as pypi. Currently, I ran into problems with pypi allows markdown for project description, while uploading to test.pypi the markdown was rendered as plain text. I guess my question is, does test.pypi support my use case? Does it behave the same with pypi?

Sorry if my question is posted at the wrong location. Any comments/ clarification/ redirection would be greatly appreciated. Thanks!

[di]

@kimyen There is only one upload API. It's a "legacy" API because it mimics the original upload endpoint for pypi-legacy, but there is not yet a replacement for it. Sorry for the confusion!

[kimyen]

@di Does rendering project description with markdown format have anything to do with the upload?

[di]

@kimyen Yes! Please open a new issue describing your problem and we'll try to help.

[rsyring]

@kimyen maybe you are looking for this? https://github.com/di/markdown-description-example

[kimyen]

Thanks @rsyring ! I was following the instruction in https://dustingram.com/articles/2018/03/16/markdown-descriptions-on-pypi/, and get it working in pypi in the past. I cannot reproduce the same working state in test.pypi this time (for the same code). And I got confused on the second paragraph of section 7 in that post, which lead me here.

@di , I created #5276. Thank you for looking into it!

[di]

Ah, good catch, I should update that paragraph, it is confusing!

[CAM-Gerlach]

Is there a particular reason this was never done? Even as a moderately experienced Python dev involved in a number of open-source projects, but who hadn't gone back and referenced the packaging guide much since the Warehouse transition and hadn't done a lot of release management lately, until I read this issue I was rather confused with the API naming when skimming over the basic packaging tutorial to ensure my RELEASE.md and flow reflected the latest packaging best practices. In particular, as other users have mentioned, I was concerned it was reliant on the legacy PyPI infrastructure or otherwise deprecated and I shouldn't be using it, which isn't actually the case. Thanks!

[brainwane]

@CAM-Gerlach My understanding is that we just haven't had the time to do it yet; doing it properly will require some communication and coordination with various other tool maintainers and we've been concentrating on other things. Sorry.