On Aug 9, 2014, at 4:26 AM, Paul Moore firstname.lastname@example.org wrote:
On 8 August 2014 22:53, Donald Stufft email@example.com wrote:
Some automated tools may permit the use of a direct reference as an alternative to a normal version specifier. A direct reference consists of the specifier ``@`` and an explicit URL.
Whether or not direct references are appropriate depends on the specific use case for the version specifier. Automated tools SHOULD at least issue warnings and MAY reject them entirely when direct references are used inappropriately.
Public index servers SHOULD NOT allow the use of direct references in uploaded distributions. Direct references are intended as a tool for software integrators rather than publishers.
Depending on the use case, some appropriate targets for a direct URL reference may be a valid ``source_url`` entry (see PEP 426), an sdist, or a wheel binary archive. The exact URLs and targets supported will be tool dependent.
For example, a local source archive may be referenced directly::
pip @ file:///localbuilds/pip-1.3.1.zip
Alternatively, a prebuilt archive may also be referenced::
pip @ file:///localbuilds/pip-1.3.1-py33-none-any.whl
One very minor question. Is URL format required here? I guess so. On Windows, file URLs are confusing and annoying to type - use of / rather than \ makes tab-completion useless, it's difficult to remember how many slashes go at the start and where the drive letter goes, and do UNC paths need 157 or 158 slashes at the start (:-)), and the documentation is inconsistent and hard to find.
Allowing a pathname here would be convenient for users, but it's 100% not important enough to need a new version of the spec. A clarification (presumably, that a URL is required) with a pointer to a document that explains the relevant filename->URL translation algorithm, would be good, though.
To be clear, the direct reference is mostly for use in the install_requires. On the CLI pip can still just take a path to a file or whatever. This feature is intended to replace dependency_links in a way that people can use them for private packages but that they won't be allowed on PyPI or the like.
--- Donald Stufft PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA