Installing links to local projects

Sometimes developers want to have a project that’s being worked on available in an environment as if it was installed there, but without actually installing it because they want any changes they make to the project to be immediately reflected in the environment without the need to reinstall. (pip calls these editable installations.)

You can get the equivalent effect using the distil link command, which works like distil install but only writes a link to the target environment (see Where things are installed to see where links are installed).

The command is run like this:

$ distil -e e2 link /path/to/my/project

You can specify more than one project path. Projects to be linked need to have a package.json file in the project directory, so that the project name can be determined. Here’s an example:

$ e2/bin/python -c "import sarge; print(sarge.__file__)"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: No module named sarge

There’s no sarge project available in the environment. Let’s download it to a local directory:

$ distil download -d /tmp sarge
Downloading https://pypi.python.org/packages/source/s/sarge/sarge-0.1.tar.gz to /tmp/sarge-0.1
    35KB @ 210 KB/s 100 % Done: 00:00:00
Unpacking ... done.

Now let’s link the project:

$ distil -e e2 link /tmp/sarge-0.1

The command doesn’t output anything unless an error occurs. Now, sarge should be available in the environment:

$ e2/bin/python -c "import sarge; print(sarge.__file__)"
/tmp/sarge-0.1/sarge/__init__.py

As you can see, the sarge project available in the environment is the one in the editable location /tmp/sarge-0.1.

Removing links

To remove links, you specify -r and the names of the projects you want to remove links to:

$ distil -e e2 link -r sarge

The command doesn’t output anything unless an error occurs. Now, sarge will no longer be available in the environment:

$ e2/bin/python -c "import sarge; print(sarge.__file__)"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: No module named sarge

Here is the complete help for distil‘s link command:

$ distil help link
usage: distil link [-h] [-r] [-s] DIR_OR_NAME [DIR_OR_NAME ...]

Install links to one or more local projects so that they can be used while
remaining editable.

positional arguments:
  DIR_OR_NAME   A directory of a local project when linking, or the project
                name when unlinking.

optional arguments:
  -h, --help    show this help message and exit
  -r            Remove links to named projects.
  -s, --system  Install to system Python (may require sufficient privileges).
                By default, installations are written to the user site
                (~/.local), or to a virtual environment specified with -e.