Python Setting Up Your Environment

These notes are based on the Python - Installing Packages documentation. Here, we will focus on setting up a minimal environment for running the python scripts (soon to be) used in our continuous integration (CI) framework Firebot. The following instructions should work for macOS and Linux. For Windows, please follow the same basic process, but look to the aforementioned documentation.

Requirements

First, make sure you have Python version 3.7 or higher installed.

$ python --version
Python 3.12.2

If you get an error, or have a version below 3.7, talk to your system administrator or attempt the installation yourself (see the next section). Installation instructions for Python can be found here.

Installing Python (if necessary)

The following is based on this thread. If the command above does not return a version of Python greater than 3.7, then try:

(macOS)

$ brew update
$ brew install python
$ brew info python
...
==> Caveats
Python has been installed as
  /opt/homebrew/bin/python3

Unversioned symlinks `python`, `python-config`, `pip` etc. pointing to
`python3`, `python3-config`, `pip3` etc., respectively, have been installed into
  /opt/homebrew/opt/python@3.12/libexec/bin

This last line is useful. Copy this and add it to your PATH in your ~/.bash_profile.

export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"

Now "python" and "python3" should behave the same way.

(Ubuntu Linux)

Follow these instructions.

(Enterprise Linux)

Follow these instructions.

Note

If Python 2.7 is still active on your Linux system, the preferred way to point "python" to "python3" is to simply use an alias, as discussed here.

Why Use a Python Environment?

The simple answer to this question is that environments avoid the "version hell" dilemma. All the packages that you import, and their dependencies, must be compatible with the version of Python you are using to process your scripts. The only sane way to accomplish this is with a package manager. There is no need for a commercial package manager, pip (preferred installer program) works great, and if you include "ipython" in your requirements.txt file (which we do), then you will have the IPython interactive shell and Jupyter notebooks available.

Setting Up Your Environment

Note

You only have to do this step once, not each time you use Python. Subsequently, you either activate your environment on startup or whenever you decide (as discussed below).

We want to process scripts in Firebot, so it will be convenient to work inside the FDS project repository to ensure our environment works consistently for each user and with GitHub Actions. If you do not have the repo, see Git Notes: Getting Started.

First, cd to the top level of the FDS repository and into the .github subdirectory, which is where the requirements.txt file lives. We will store our environment here, as this makes it convenient for use with GitHub Actions.

$ cd <path-to-repo>/fds/.github

Next, create your environment with this command:

$ python -m venv fds_python_env
$ ls
dependabot.yml  fds_python_env  ISSUE_TEMPLATE  requirements.txt  workflows

Doing an ls shows that you have just created the environment folder "fds_python_env".

Note

The name of the environment (here "fds_python_env") is your choice, as is where you decide to store it. In this example, we are creating an environment that will be used by everyone on the development team and GitHub Actions, so it makes sense that it lives inside our repository.

Now activate the environment with

$ source fds_python_env/bin/activate
(fds_python_env) username@host .github (master) $

You will notice your prompt now has the environment name prepended.

Finally, run pip to install the packages listed in the FDS requirements.txt file.

$ pip install -r requirements.txt
Collecting numpy
  Downloading numpy-1.26.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.2 MB)
     |████████████████████████████████| 18.2 MB 109.1 MB/s

.
.
.

Successfully installed ... (lots of stuff)

If you get to this point without any errors (warnings are ok; for example, you might get a warning about pip version), then you are good to go. You can use this Python to run any of the FDS scripts.

If you get an error, it is likely related to the Python version.

If you no longer want to use this environment, simply deactivate it by typing

$ deactivate
username@host .github (master) $

and you will see the prompt return to normal.

To reactivate your environment or to activate it manually at any time simply source your environment from where ever you are on the system using

$ source <path-to-env>/fds_python_env/bin/activate
(fds_python_env) username@host <where ever you are> $

Activating Your Environment on Startup (optional)

You can add the source command to your terminal startup script (~/.bash_profile on macOS or ~/.bashrc on Linux). Just make sure the path to the environment is correct. For example, if your repo path is ~/GitHub/firemodels/ then add this to your startup.

# Start Python environment
source ~/GitHub/firemodels/fds/.github/fds_python_env/bin/activate