Docu example on "editable project in current directory" seems not to work/is unclear/suggests failing behaviour

[smartsammler]

• Pip version: pip 9.0.1
• Docu version: latest/ 041b603
• Python version: python 3.6 (miniconda3)
• Operating system: GNU/Linux Fedora 25 Workstation

Description:

The documentation's (reference/pip_install.rst) example 6 says it would be possible to install a local package at a specific version, $ pip install -e .[PDF]==3.0 # editable project in current directory
At least for the case of setuputils extras and the editable mode. Since the version 3.0 should reference to the package's version (here .'s version) it suggests that one could install local packages with a specific version like $ pip install -e .[]==3.0 which is not the case.

What I've run:

$ python3 -m pip install -e '.==0.0.5'

throws an exception:

.==0.0.5 should either be a path to a local project or a VCS url beginning with svn+, git+, hg+, or bzr+

So does

$ python3 -m pip install -e '.[]==0.0.5'

and the cases without quotes and with --upgrade

In contrast to that running without -e does throw an exception with a traceback

$ python3 -m pip install  '.[]==0.0.5' --upgrade
Invalid requirement: '.[]==0.0.5'
Traceback (most recent call last):
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/packaging/requirements.py", line 92, in __init__
    req = REQUIREMENT.parseString(requirement_string)
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 1617, in parseString
    raise exc
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 1607, in parseString
    loc, tokens = self._parse( instring, 0 )
  File ~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 1379, in _parseNoCache
    loc,tokens = self.parseImpl( instring, preloc, doActions )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 3376, in parseImpl
    loc, exprtokens = e._parse( instring, loc, doActions )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 1379, in _parseNoCache
    loc,tokens = self.parseImpl( instring, preloc, doActions )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 3698, in parseImpl
    return self.expr._parse( instring, loc, doActions, callPreParse=False )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 1379, in _parseNoCache
    loc,tokens = self.parseImpl( instring, preloc, doActions )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 3359, in parseImpl
    loc, resultlist = self.exprs[0]._parse( instring, loc, doActions, callPreParse=False )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 1383, in _parseNoCache
    loc,tokens = self.parseImpl( instring, preloc, doActions )
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/pyparsing.py", line 2670, in parseImpl
    raise ParseException(instring, loc, self.errmsg, self)
pip._vendor.pyparsing.ParseException: Expected W:(abcd...) (at char 0), (line:1, col:1)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "~/miniconda3/lib/python3.6/site-packages/pip/req/req_install.py", line 82, in __init__
    req = Requirement(req)
  File "~/miniconda3/lib/python3.6/site-packages/pip/_vendor/packaging/requirements.py", line 96, in __init__
    requirement_string[e.loc:e.loc + 8]))
pip._vendor.packaging.requirements.InvalidRequirement: Invalid requirement, parse error at "'.[]==0.0'"

Possible solution:

Since the IRC #pypa said it was not possible to install/downgrade a local package to a specific version, I think the documentation should be fixed by deleting line 803 of docs/reference/pip_install.rst

      $ pip install -e .[PDF]==3.0  # editable project in current directory

or adjusting it to not suggest that it was possible to install with .[]==version. Or add this functionality, so one does not need to roll back to the version one wants and then install (git checkout v0.0.5 && pip install --upgrade .) or use the repository @-syntax (pip install --upgrade "git+file:///home/username/package/.git@v0.0.5#egg=package")

[msarahan]

@pganssle I'm at the PyPA sprint in NYC. I'd be interested in helping here, but I'm not clear what's remaining, given the commit that exists here. Do we just need a PR to be put up? I can pull in @smartsammler's commit and submit a PR with it if that would help.

[pganssle]

I think @pradyunsg would know better?

[pradyunsg]

Apologies for missing this. My personal Octobox instance went down and I lost track of a few notifications.

Just a PR would removing the example would be fine, given that this doesn't work.