Clarify docs and help messages on cli commands

[ghost]

Excited pipenv user here. I don't understand what several of the commands do. Here is the output of pipenv:

Commands:
  check      Checks for security vulnerabilities and against PEP 508 markers
             provided in Pipfile.
  clean      Uninstalls all packages not specified in Pipfile.lock.
  graph      Displays currently–installed dependency graph information.
  install    Installs provided packages and adds them to Pipfile, or (if none
             is given), installs all packages.
  lock       Generates Pipfile.lock.
  open       View a given module in your editor.
  run        Spawns a command installed into the virtualenv.
  shell      Spawns a shell within the virtualenv.
  sync       Installs all packages specified in Pipfile.lock.
  uninstall  Un-installs a provided package and removes it from Pipfile.
  update     Runs lock, then sync.

1. lock "Generates Pipfile.lock." Is it doing that based on the current environment, or based on what's specified in the Pipfile, or some other thing? Sometimes it seems to be accessing the internet, which is altogether unexpected.

2. Does open open the editor with the virtualenv bin directory prepended to the PATH? Or something else?

3. install "Installs provided packages". What are "provided packages"? Do they include the ones in my Pipfile? If no arguments are given, it installs "all" packages; which "all" are you talking about: in the Pipfile, Pipfile.lock, current active environment?

4. Which of these commands modify my environment? Which modify my Pipfile? Which modify my Pipfile.lock?

Could the cli help text and documentation clear this up, please?

Thank you for all your work on pipenv.

[uranusjr]

How Pipenv manage things can be generally thought in a linear manner:

Your mind
  ↓ [manual Pipfile edit]  
Pipfile
  ↓ [lock]
lockfile
  ↓ [sync]
environment

There are three kinds of commands: essential (lock and sync, noted in the above graph), shorthands (combination of essential commands), and utilities (not related to essential commands, but make things easier to work with a project).

Shorthands:

• install/uninstall [package] = edit the Pipfile (to add/remove the package), lock, and sync
• update = lock + sync

Utilities:

• clean = A companion of sync. Due to how Python packaging works, sync only makes sure everything you want is installed, but does not check if there are stray packages maybe you don’t need. This command plugs (sort of) this hole.
• shell and run = Run things inside the virtual environment easily.
• graph = Shows a visual representation of your environment.
• open = Opens the editor. What do you mean with prepending PATH? An editor does not know about your PATH, this is not how editors work???

Pull requests on the help messages are welcomed.

[ghost]

@uranusjr Regarding open, I'm wondering whether pipenv open requests opens requests inside the virtualenv or not? This is relevant if the virtualenv contains configuration that the editor can access, like environment variables, linter executables, etc.

[techalchemy]

yes of course, pipenv manages virtualenvs. Everything involved is about virtualenvs. It finds the module in your virtualenv and opens it in an editor. That's all there is to it.

[ghost]

Ah the way I phrased the question was ambiguous. I didn't mean to ask whether open opens the module that is located in the virtualenv, but rather whether it opens the editor within the virtualenv or not. Navigating to a pipenv project and running pipenv open requests, and then within the editor checking which python, it's my regular python. By contrast, pipenv run emacs then which python within emacs gives the virtualenv's bin/python.

This result has implications for certain workflows with pipenv. Some users might prefer if pipenv open requests were more like pipenv run emacs /path/to/venv/requests.py so that the virtualenv's environment variables, linters, and python executable would be accessible within the editor.

This isn't the workflow I use normally, but I believe it's not uncommon. I hope that clears up my question and why I was asking. Cheers!

[ghost]

@uranusjr Thanks for the detailed overview. That's quite helpful.

[uranusjr]

@apnewberry No problem at all. I’m quite bad at literature and writing help messages however, so it would be awesome if you could help incorporating them into the actual documentation and help output. I’d say you’re not the only one having this question.

[ghost]

• lock

  • download the most recent version of the packages specified in Pipfile
  • compute the hashes of these packages
  • write the requirements with hashes into Pipfile.lock

• sync

  • download any Pipfile.lock requirements into the local pip cache if they're not there already
  • install all Pipfile.lock requirements from the cache into the virtualenv

Is that right?

[uranusjr]

Yes, they are correct in general. Two minor technical details:

• Lock does not always download the most recent. Say if I specify Django (latest is 2.0.x), but one of my dependencies require 1.11.x, it will download the latest 1.11.11 (currently the latest in 1.11 series). Might want to clear this up.
• Sync does not really download anything on its own. The cache is managed by pip, sync only tells it to install things. You can actually set PIP_NO_CACHE_DIR to disable it, and sync won’t care. Overall I think it would suffice to simply say sync hands the requirements in Pipfile.lock to pip for it to install them.

Really those are technical details, but better to do them absolutely right than risk giving people wrong impressions.

[ghost]

You can actually set PIP_NO_CACHE_DIR to disable it, and sync won’t care.

What do you mean by "sync won't care": in PIP_NO_CACHE_DIR=1 pipenv lock , Is the PIP_NO_CACHE_DIR value passed to pip?

I tried testing it but couldn't really understand what was supposed to happen in the pip usage of this option either (see pypa/pip#2897).

[uranusjr]

Is the PIP_NO_CACHE_DIR value passed to pip?

Yes. Well, not passed, it’s an environment variable that pip picks up automatically. Pipenv does not do anything with that flag.

If I understand it correctly, PIP_NO_CACHE_DIR tells pip to not use the default cache directory. off (or 0, false, etc.) turns off the cache completely, while on (or 1, true, etc.) tells pip to use an alternative cache directory, specified by PIP_CACHE_DIR. The names are just terrible.