Tips for setting up a PyStan development environment

As part of a topic that came up over in the PyStan issues page, it seems it would be helpful to share some instructions on getting a Python environment set up for doing development and tinkering with PyStan.

PyStan uses Poetry for dependency management and packaging. It also makes for a convenient way to set up a development environment. While I’m sure there are other ways to get up and running for PyStan development, the below steps show how to go from installing Poetry to getting a proper dev environment set up.

  1. Install Poetry – the introduction documentation gives the recommended installation for your particular system.

  2. Clone the PyStan repository from GitHub:

     git clone https://github.com/stan-dev/pystan.git
    
  3. Navigate into the freshly cloned pystan directory and install it via Poetry:

     cd pystan
     poetry install
    

    At install, Poetry creates an isolated virtual environment where all the dependencies are installed, and PyStan is installed in develop mode. This allows local changes to PyStan to be immediately reflected in this environment without breaking any other projects that use the library.

  4. The Poetry-created virtual environment is the backbone of your dev environment. It can be used directly via Poetry’s command line interface. For example,

     poetry run my_script.py
    

    Will run the file my_script.py using the PyStan environment.

    The environment can be directly activated as well if you want more flexibility:

     poetry shell
    

    For those who prefer to use IDEs like PyCharm or VS Code, you can locate the path of the Poetry virtual environment by running:

     poetry env info
    

    Pointing your IDE to use the Python interpreter at that path will allow you to use all the tools/features of the IDE as normal.

    Lastly, Poetry gives an easy interface to run dev tools like pytest and black, calling these commands with Poetry should do the trick, for example for running tests:

     poetry run pytest
    

There are plenty of other commands/more complex behavior in Poetry that one could take advantage of, check out the documentation if you’re interested. Hopefully these steps are useful for others who want to tinker with PyStan. If anyone else has a different approach or wants to share some tips of their own, feel free to share!

1 Like

Thanks for the instructions.

I would also add 2 common dev steps.

  1. Fork PyStan repository and clone the forked repo.

git clone https://github.com/ghuser/pystan.git

  1. Add git remote repo

git remote add upstream https://github.com/stan-dev/pystan.git

2 Likes

Likely due to years of using pip install -e . when developing, I do things a bit differently.

Here’s how I set things up, more or less:

git clone https://github.com/stan-dev/pystan.git
cd pystan
poetry export -f requirements.txt --dev -o requirements.txt
python3 -m venv venv
source venv/bin/activate
python3 -m pip install -r requirements.txt

At this point it’s possible to modify source files and run tests, e.g., python3 -m pytest tests.

1 Like

Great news: this problem is solved in newer versions of pip. pip now supports “editable” installs of projects which only have a pyproject.toml.

pip install -e .

will work if you are sitting in the root directory of the pystan repository.

Support for this was added in pip 21.3, released 2021-10-11.

2 Likes