[PEP 508] Clarification of URL References
PEP 508 allows for pointing to required packages using URL's. This is the except: A minimal URL based lookup:: pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a... However, there is very little documentation, blog posts, etc on how to use beyond the PEP itself, and so I struggled to understand it. I incorrectly assumed that *pip*, at the start of the line, had something to do with the given package being *installed via pip*, rather than *the name of the package being installed*. Therefore, is it possible to list another example line in the PEP to make it clear that the line doesn't have to start with "pip" to work? For further reading, my original issue, and the discovered solution --> https://github.com/jazzband/pip-tools/issues/1056 The explanation there that was helpful for me (that I didn't get from reading the PEP) was:
I believe the issue is in the name @ url pattern. It should be project_name @ vcs_url, no eggs param needed in this case by the way, but the project_name should be the same as package name in vcs_url/setup.py. [source](https://github.com/jazzband/pip-tools/issues/1056#issuecomment-582982556)
c.f. the issue I raised on GitHub, where I was suggested to post here --> https://github.com/python/peps/issues/1444 Thanks.
On Sun, 21 Jun 2020 at 21:49, <w_minchin@hotmail.com> wrote:
PEP 508 allows for pointing to required packages using URL's. This is the except:
A minimal URL based lookup::
pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a...
However, there is very little documentation, blog posts, etc on how to use beyond the PEP itself, and so I struggled to understand it. I incorrectly assumed that *pip*, at the start of the line, had something to do with the given package being *installed via pip*, rather than *the name of the package being installed*.
PEP 440 also covers direct URLs, here: https://www.python.org/dev/peps/pep-0440/#direct-references. But basically you have reached the correct answer: `NAME @ URL` is a reference to a project located at URL. The NAME must be the name of the project hosted at URL, it's an error for the name and the URL to not match. The URL should have a #HASHTYPE=HASH part, that gives the hash of the file the URL points to (and the type of hash, typically something like sha256). This is to allow installers to check that the file they downloaded is the one expected.
Therefore, is it possible to list another example line in the PEP to make it clear that the line doesn't have to start with "pip" to work?
Does PEP 440 cover this any better for you? We could add further clarifying examples but the PEPs are intended to be definitions rather than tutorials, so we have to strike a balance in the PEP. An additional example may be reasonable, but more explanatory information may be better handled as part of the packaging user guide at https://packaging.python.org/. I don't think anyone had considered that by using pip as the example of the project name, readers might assume that was the installer rather than the project, so changing that example may be reasonable.
For further reading, my original issue, and the discovered solution --> https://github.com/jazzband/pip-tools/issues/1056 The explanation there that was helpful for me (that I didn't get from reading the PEP) was:
I believe the issue is in the name @ url pattern. It should be project_name @ vcs_url, no eggs param needed in this case by the way, but the project_name should be the same as package name in vcs_url/setup.py. [source](https://github.com/jazzband/pip-tools/issues/1056#issuecomment-582982556)
This is correct. Paul
Does PEP 440 cover this any better for you?
I actually think the example in PEP 440 are part of what caused my confusion, because all of them are also for *pip*: ``` pip @ file:///localbuilds/pip-1.3.1.zip pip @ file:///localbuilds/pip-1.3.1-py33-none-any.whl pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a... pip @ git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d pip @ git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee6... ```
We could add further clarifying examples
Yes please!
I don't think anyone had considered that by using pip as the example of the project name, readers might assume that was the installer rather than the project, so changing that example may be reasonable.
This about sums up the roadblock I hit.
but the PEPs are intended to be definitions rather than tutorials
(I think) I understand that PEPs are meant for a technical discussion, but they should be also verbose enough to allow the proposal to be implemented. I read the PEP and tried to implement it, but failed. My hope if that those that follow after me will be more successful.
more explanatory information may be better handled as part of the packaging user guide at https://packaging.python.org/.
I think this is a good idea as well, as I could find any part of the documentation there that dealt with this. I would offer to write that myself, but I feel like I'm operating just at (or past!) the limits of my understanding here. Thanks for you help thus far.
participants (2)
-
Paul Moore -
w_minchin＠hotmail.com