Document how to install provides_extras from local wheel file

[johnthagen]

Closes #9694

[johnthagen]

@uranusjr Could you add the label to skip news-file for this PR? I presume this isn't large enough to warrant a news entry.

[uranusjr]

You can create an empty file with the .trivial.rst extension to skip the check yoirself.

I'm personally not sure if this should count as trivial. This is legitimately adding new things to the documentation and is worth a line.

[sbidoul]

Are we sure we want to encourage use of this non-standard syntax ?

python -m pip install 'somepackage[my-extras] @ file://$PWD/somepackage-1.0-py2.py3-none-any.whl' should work and is PEP 508 compliant.

Related: #8828

[uranusjr]

The downside of PEP 508 is there's no obvious Windows-compatible format 🙁 So personally I'm OK with the non-standard syntax here since it at least is consistent to teach everywhere.

[johnthagen]

@uranusjr Do you know what needs to be done to move this PR forward? Is there consensus on what we want to do?

[uranusjr]

Personally I am fine with the PR as-is, but want input from other maintainers.

[uranusjr]

p.s. the CI checks here are outdated and don’t work anymore so you need to rebase the PR to make it mergable.

[sbidoul]

The downside of PEP 508 is there's no obvious Windows-compatible format 🙁

Yes, but we have determined in #1289 (comment) and #9471 that pip needs to be able to parse PEP 508-like requirements that have a local path instead of a URL (so we can deprecate #egg fragments).

And when that will be implemented, I think it will become the preferred format.

So today the path[extras] syntax is necessary, but in the long run we may consider to steer away from it.

[uranusjr]

Yes, but that have not happened yet, and before that happens we can still put the old format in the documentation. Once PEP 508 parsing is implemented properly, we can change the documentation to use the new format.

[johnthagen]

@uranusjr I just rebased this PR on master.

[sbidoul]

Would it make sense to at least mention the PEP 508 syntax (name[extras] @ files://fullpath) and say that the path[extras] syntax might be deprecated in the future and recommend to use it only when the PEP 508 syntax is not usable (e.g. because of the need to use a relative path).

[uranusjr]

say that the path[extras] syntax might be deprecated in the future and recommend to use it only when the PEP 508 syntax is not usable

Sounds reasonable to me. @johnthagen could you make this addition?

[johnthagen]

Sounds reasonable to me. @johnthagen could you make this addition?

@uranusjr I added a note for this. Does this look good?

[sbidoul]

Thanks!

[johnthagen]

Thanks all for helping get this merged.