Development Environment

Setting up a predictable development environment.

Integrated Development Environment (IDE)

Be sure to install the plugin for a language server (ruff):

  • Autocompletion
  • Checks if code is syntactically correct
  • Warnings about styles and types
  • Automatically formats code

For the below commands, use the terminal (macOS, Linux) or the command prompt (Windows) to enter the commands. Your IDE may also have an integrated terminal that you can use.

Python Packaging system (uv)

Python uses a system called 'virtual environment' to define where to install packages, which python version to use, and what libraries you can import in your scripts. Since different libraries may depend on specific versions of other libraries, the packaging system has to construct a graph of dependencies and ensure all conditions can be met. This is done by the famous pip in the python world.

However, pip is very slow, and so we use modern tools like uv which claim to be 10 to 100x faster, with a friendlier interface.

To begin, install uv (pay attention to any messages it may return):

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

To start a 'project' (i.e. create a virtual environment) in the current directory (thesis-template):

uv init

This creates the following files:

  • .python-version: The version of python we are using

  • pyproject.toml: The details of our python library/application. Modify as needed.

[project]
name = "thesis"
version = "0.1.0"
description = "Python repository for thesis"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
  • hello.py: An example program

Now, we can install the packages we want, for instance:

uv add numpy pandas matplotlib scikit-learn rich
# Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
# Creating virtual environment at: .venv
# Resolved 23 packages in 16.76s

This installs the packages and also creates:

  • uv.lock: File with which uv keeps track of packages and their versions.

  • .venv/: The folder where all packages will be installed.

To confirm that everything works as intended, add the following at the start of hello.py:

import pandas
import matplotlib
import numpy
import sklearn
import rich

Now run the script:

python hello.py

It should run without errors.

Git Version Control

This is a much more nuanced topic that cannot be covered here.

For the absolute basics:

# Check which online repository this folder is linked to
# ( i.e. confirm that you did 'use-template' from github )
git remote -v

# Each time you make significant changes:

  # Check which files changed
  git status

  # Mark all files to be saved
  git add .

  # Save a checkpoint
  git commit -m "Some message"

  # Check again that
  #   - all changes have been recorded
  #   - no changes are leftover
  git status

  # Send the changes to the github server
  git push

Documentation

Prefer to use plain text (markdown) over latex in the initial stages. It will help us concentrate on substance instead of formatting. This also allows us to have a clean look at our thesis by serving it as a website (as this site is currently):

uv add mkdocs mkdocs-terminal

The current repository already defines some good defaults in the config file mkdocs.yml, so we can directly serve the site:

mkdocs serve

The documentation will be available at: localhost:4444 (port 4444 is defined in mkdocs.yml)