Skip to content

Setup Guide

It's possible to set up your python environment in many different ways.

To use the AutoRA package you need:

  • python and
  • packages as specified in the pyproject.toml file.

To develop the AutoRA package, you also need:

  • git, the source control tool,
  • pre-commit which is used for handling git pre-commit hooks.

You should also consider using an IDE. We recommend:

  • PyCharm. This is a python-specific integrated development environment which comes with useful tools for changing the structure of python code, running tests, etc.
  • Visual Studio Code. This is a powerful general text editor with plugins to support python development.

The following sections describe how to install and configure the recommended setup for developing AutoRA.

Tip

It is helpful to be familiar with the command line for your operating system. The topics required are covered in:

Development Setup

Clone The Repository

The easiest way to clone the repo is to go to the repository page on GitHub and click the "<> Code" button and follow the prompts.

Hint

We recommend using:

Install Python

Success

All contributions to the AutoRA core packages should work under python 3.8, so we recommend using that version for development.

You can install python:

If successful, you should be able to run python in your terminal emulator like this: 

python

...and see some output like this: 

Python 3.11.3 (main, Apr  7 2023, 20:13:31) [Clang 14.0.0 (clang-1400.0.29.202)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

Create A Virtual Environment

Success

We recommend setting up your development environment using a manager like venv, which creates isolated python environments. Other environment managers, like virtualenv, pipenv, virtualenvwrapper, hatch, poetry, are available and will likely work, but will have different syntax to the syntax shown here.

Our packages are set up using virtualenv with pip

In the <project directory>, run the following command to create a new virtual environment in the .venv directory

python3 -m "venv" ".venv"

Hint

If you have multiple Python versions installed on your system, it may be necessary to specify the Python version when creating a virtual environment. For example, run the following command to specify Python 3.8 for the virtual environment. 

python3.8 -m "venv" ".venv"

Activate it by running 

source ".venv/bin/activate"

Install Dependencies

Upgrade pip: 

pip install --upgrade pip

Install the current project development dependencies: 

pip install --upgrade --editable ".[dev]"

Your IDE may have special support for python environments. For IDE-specific setup, see:

Activating And Using The Environment

To run interactive commands, you can activate the virtualenv environment. From the <project directory> directory, run:

source ".venv/bin/activate"

This spawns a new shell where you have access to the python and all the packages installed using pip install. You should see the prompt change:

% source .venv/bin/activate
(.venv) %

If you execute python and then import numpy, you should be able to see that numpy has been imported from the .venv environment:

(.venv) % python
Python 3.8.16 (default, Dec 15 2022, 14:31:45) 
[Clang 14.0.0 (clang-1400.0.29.202)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> numpy
<module 'numpy' from '/Users/me/Developer/autora/.venv/lib/python3.8/site-packages/numpy/__init__.py'>
>>> exit()
(.venv) %

You should be able to check that the current project works by running the tests: 

pytest

It should return something like:

% pytest
.
--------------------------------
Ran 1 test in 0.000s

OK

Hint

To deactivate the virtualenv environment, deactivate it. This should return you to your original prompt, as follows: 

(venv) % deactivate
%

Running Code Non-Interactively

You can run python programs without activating the environment, by using /path/to/python run {command}. For example, to run unittests tests, execute:

.venv/bin/python -m pytest

It should return something like:

% .venv/bin/python -m pytest
.
--------------------------------
Ran 1 test in 0.000s

OK

Pre-Commit Hooks

If you wish to commit to the repository, you should install and activate pre-commit as follows. 

pip install pre-commit
pre-commit install

You can run the pre-commit hooks manually by calling: 

pre-commit run --all-files

For more information on pre-commit hooks, see Pre-Commit-Hooks