Setting up your development environment

Recommended tools

Many of the tools listed below are optional, but highly recommended by the pyscope development team. All of them are free, some require an academic email address.

1. Miniconda (Python 3.10+ version) or if you use an ARM-based MacBook (M1+) Miniforge. (Other recommended ARM tools can be found in this GitHub repository from Shreyas Shankar and this website).

2. GitHub account. If you have an academic email address, we strongly recommend that you sign up for the GitHub Student Developer Pack. If you are using Windows, you may have to install Git separately.

3. VSCode is a powerful IDE with many extensions that make it a great choice for pyscope development. We recommend the following extensions:

   • Python: Python development

   • Jupyter: Jupyter notebook support

   • black code formatter for code formatting compatability with pyscope

   • isort: import sorting compatability with pyscope

   • GitHub Copilot: AI-powered code completion (free with the GitHub Student Developer Pack)

   • GitHub Actions: GitHub Actions config file support

   • GitLens: line-by-line blame preview and other version control tools (Pro version free with the GitHub Student Developer Pack)

   • ErrorLens: inline error highlighting

   • CodeCov: CodeCov integration

   • esbonio: Sphinx documentation preview window with on-the-fly compilation

   • Simple RST for RST linting

   • Markdown Lint for Markdown linting

   • HTML Preview for inline HTML preview

   • Path IntelliSense for path autocompletion

   • Indent Rainbow for indentation highlighting (useful for Python specifically)

   • VSCode Icons for file type icons

   • One Dark Pro for a dark theme

Creating a new conda environment

We recommend that you have an environment dedicated to pyscope development. To create a new environment, run the following command in your terminal:

conda create -n pyscope-dev python=3.11

This will create a new environment called pyscope-dev with Python 3.11 installed. To activate the environment, run:

conda activate pyscope-dev

You can deactivate the environment with:

conda deactivate

Forking the repository

To contribute to pyscope, you will need to fork the repository. To do this, go to the pyscope GitHub page and click the “Fork” button in the top right corner. This will create a copy of the repository in your GitHub account. Move to a location on your computer where you want to store the repository and run:

git clone https://github.com/<your-username>/pyscope

where <your-username> is your GitHub username. This will create a new folder called pyscope with the repository contents. Move into this folder with:

cd pyscope

Installing dependencies

Once you have cloned the repository, you can install the development version of pyscope with:

pip install -e ".[dev]"

This will install pyscope in editable mode with all of the development dependencies. We recommend that you use the VSCode IDE with the extensions listed above. You can open the repository in VSCode with:

code .

GitHub Codespaces

The pyscope repository includes a devcontainer.json file that allows you to develop pyscope in a GitHub Codespace with many of the above tools pre-installed. This is a handy way to develop pyscope without having to go through the setup process on your local machine. To use a Codespace, click the “Code” button in the top right corner of the pyscope GitHub page and select “Open with Codespaces”. This will open a Codespace in your browser. If you have VSCode installed, you can click the “Open with VS Code Desktop” button in the menu from the upper left to use the Codespace from the familiar VSCode interface. You may be prompted to install the GitHub Codespaces extension and other helper extensions.