Building and Packaging

With pip:

Currently, we are building using Setuptools via a pyproject.toml file as specified in PEP 518. This may allow us to switch out the build backend (or frontend) later.

For now, the package can be built by running

python -m build

from within the project directory. After that

pip install --editable .

will install the package in editable mode, which means that changes in the project directory will affect the code that is run (i.e., the installation will not copy over the code to site-packages but simply link the project directory.

Note: Due to this pyzmq issue, if you're running on Ubuntu, you need to specify

pip install -e . --no-binary pyzmq

When uninstalling, be sure to do so from outside the project directory, since otherwise, pip only appears to find the command line script, not the full package.

Optional dependencies

By default, the procedure above only installs the requirements for running improv itself. If you also want to run tests and build documentation, you should run, e.g.,

pip install -e .[tests,docs]

(on bash) or

pip install -e ".[tests,docs]"

(on zsh for newer Macs).

Building documents locally

Currently, we have GitHub Actions set up to build the Jupyter Book automatically. But for previewing changes locally, you will want to build the documents and check them yourself.

To do that, you'll first need to install the docs dependencies with

pip install -e .[docs]

Then simply run

jupyter-book build docs

and open docs/_build/html/index.html in your browser.

Getting around certificate issues

On some systems, building (or installing from pip) can run into this error related to SSL certificates. For pip, the solution is given in the linked StackOverflow question (add --trusted-host) to the command line, but for build, we run into the issue that the trusted-host flag will not be passed through to pip, and pip will build inside an isolated venv, meaning it won't read a file-based configuration option like the one given in the answer, either.

The (inelegant) solution that will work is to set the pip.conf file with

[global]
trusted-host = pypi.python.org
               pypi.org
               files.pythonhosted.org

and then run

python -m build --no-isolation

which will allow pip to correctly read the configuration.