pipenv help documentation writes:

Install a local setup.py into your virtual environment/Pipfile:

$ pipenv install -e .

Can someone further elaborate when and how to use the command pipenv install -e . in relation to setup.py?

According to pipenv, -e . refers to editable dependencies. However, I am unable to understand the given explanation. Can someone explain this?

Edit: For example, after I had created a simple distro package call mypkg in my --user directory in pip, i.e.~/mypkg, using commands:

$ pipenv shell
(mypkg-x985xH5M) $ python3 setup.py sdist bdist_wheel
(mypkg-x985xH5M) $ twine upload --repository-url https://test.pypi.org/legacy/ dist/*

and /mypkg and has the following file structure:

/mypkg
  |_ LICENSE
  |_ README.md
  |_ setup.py
  |_ /mypkg
  |    |_ __init__.py
  |    |_ mypkg.py
  |_ /dist
  |    |_ mypkg-0.0.1rc1.tar.gz
  |    |_ mypkg-0.0.1rc1-py3-none-any.whl
  |_ /build
  |    |_ /bdist.linux-x86_64
  |    |_ /lib
  |         |_ /mypkg
  |              |_ __init__.py
  |              |_ mypkg.py
  |_ /mypkg.egg-info
       |_ dependency_links.txt
       |_ entry_points.txt
       |_ PKG-INFO
       |_ SOURCES.txt
       |_ top_level.txt

what does the command $ pipenv install -e . do?

Normally, pip (driving setup.py or another PEP 518 compliant build tool) will build and install a Python project, into the Python site-packages location. .py and .pyc files are copied over in this process.

This means that if you have a local copy of the project on disk, you can't just edit the .py source files and see the changes reflected in projects that load those same files from site-packages.

The -e switch builds, then installs a pointer file in site-packages that automatically adds the location of the project to Python's module search path. Now loading the modules will load them from the on-disk location, not from site-packages, and changes to the files will show up every time you run a Python project that uses it. See Python setup.py develop vs install and Difference between setup.py install and setup.py develop

. just tells pip / pipenv to take the current working directory as the location of the project to build (setup.py or pyproject.toml file with [build-system] section should exist in that directory).

For your example, running pip install -e . in ~/mypkg, it means python3 setup.py develop will be run, adding a .egg-link file in the site-packages directory of the Python 3 virtualenv that Pipenv is maintaining. In the same site-packages directory is a easy-install.pth file that is updated to add the full path of the ~/mypkg directory. All this means that import mypkg in Python will import the code directly from the ~/mypkg/mypkg package, and any changes you make to the .py files there are going to be directly available.