Appendix C: UV for Python Management

Python is an open-source and open-access software, so it is not difficult to get on your computer. In fact, it probably came preloaded on your computer when you bought it. The problem is that Python is a living language that changes every year. Your installation, if you have it, is likely old—from when it was configured in the factory. Moreover, we want to control the Python version we are working with. In production, it is rare that we work on the newest version of Python because we use the version of Python that the software was first built on. So, we need to use the same version as the production version when we make changes. Luckily, Python has created easy ways to do this with what are called virtual environments. Essentially, a virtual environment is an isolated environment where you can run a specific version of Python and keep necessary software libraries associated with the project, and the project will run the specified Python version by default. To make handling this type of stuff more easily, we will use Anaconda. After we set up our first environment, we will then download an IDE (we will use VS Code) to write all of our code.

We will use uv to manage package environments and projects in this textbook. uv is a command-line tool that simplifies the process of creating and managing virtual environments for Python projects. It allows you to easily create isolated environments with specific Python versions and dependencies, ensuring that your projects remain consistent and reproducible across different systems.

First, let’s install uv. You can install it by following the instructions on the official uv documentation page here. In order to install, you will need to use the terminal. If you are on Windows, you will want to open PowerShell. If you have already installed git and git bash for Windows, you should still use PowerShell for this command. If you are on a Mac or Linux, you can use the terminal application that comes with your operating system. Simply copy the command from the documentation into the terminal.

Note

To paste into the terminal, you need to use Ctrl + Shift + V on Windows and Linux, and Cmd + V on Mac.

Once you have installed uv, you can move on to creating your first python projects.

uv Python Projects and Environments

In order to work with uv you must be in a terminal. If you work on a Windows machine, then you will need to work in git bash for Windows. It was downloaded when you installed git in appendix A

uv is excellent for managing Python projects and environments because it bootstraps a project with a all you would need to get started. When you run uv init in a new directory, it will create a new project with a virtual environment, a pyproject.toml file (which is used to manage project dependencies), and a .gitignore file (which specifies files and directories that should be ignored by Git). This makes it easy to set up a new Python project with all the necessary components in place. It will also generate a src folder for your source code. This is a place for you to put utility functions and other python code that is not a notebook. uv will save this location in the pyproject.toml file so that you can import it into your notebooks. In short, it makes it really easy to work with modules you will write in the src/ folder.

As a matter of convention, you should create a new directory in the root of the project named notebooks to store your Jupyter notebooks we will create in this textbook. This is not required, but it is a good practice to keep your project organized.

Creating a New Project

Note

Make sure git is installed on your computer before you start this part. uv will generate a .git folder (necessary for git) and a .gitignore file.

Before we create a new project, we need to understand paths and directories and the file system. When you log into your machine, you start in the home directory. In Windows, this is usually C:\Users\<username>. In Mac and Linux, this is usually /home/<username>. In Mac, the home directory is hidden from the file finder by default. Nevertheless, it is the root of the user file system for all three operating systems. Similarly, all three operating machines create a Documents folder in the home directory (path: ~/Documents/). This is a good place to create a new directory for your programming projects. I call my directory for my programming projects dev. This is a fairly common practice.

To create this directory, open your file explorer or navigator or finder. Navigate to Documents and create a new folder called dev. You can do this in the terminal with the command mkdir ~/Documents/dev/. Now, navigate to this directory. You can do this with terminal commands if you prefer, using cd (change directory): cd ~/Documents/dev. Let’s create the directory for this class. Let’s call it python-class. Create a new folder in dev named python-class. Now navigate there and let’s setup our first project.

In this textbook, I recommend you code along with each chapter. So we will create a new folder in python-class called classwork. This will be the project we will use for all the chapters in this textbook. Now navigate to this directory. 1) Open a terminal and navigate to the classwork directory with the command cd ~/Documents/dev/python-class/classwork. Then run the command uv init -p 3.12. This will create a new project in the current directory and set the python version to 3.12 through the -p flag. You can use any version of Python you want, but I recommend using 3.12 because it is the latest version of Python that is supported by all the libraries we will use at the time of writing this textbook.

Now that we have created the project, we can add libraries that we will need. We will use the following libraries.

  • Jupyter:
  • NumPy: A library for numerical computing in Python, providing support for arrays, matrices, and a wide range of mathematical functions.
  • Pandas: A library for data manipulation and analysis, offering data structures like DataFrames for handling structured data.
  • Matplotlib: A plotting library for creating static, interactive, and animated visualizations in Python.
  • Seaborn: A statistical data visualization library built on top of Matplotlib, providing a high-level interface for creating informative and attractive visualizations.
  • SciPy: A library for scientific computing, offering modules for optimization, integration,
  • Scikit-learn: A machine learning library that provides simple and efficient tools for data mining and data analysis.

Let’s add these by running the command uv add jupyter numpy pandas matplotlib seaborn scipy scikit-learn. This will add the libraries to the pyproject.toml file and install them in the virtual environment. Now we can

Now our file structure should look like this:

├── pyproject.toml
├── README.md
└── src
    └── classwork
        └── __init__.py

3 directories, 3 files

Notice, we have a src/ directory. Inside it, there is a classwork directory. It is autogenerated based on the name of the folder in which uv init ran. This is the place that we will create helper and utility functions for our work. See more about this in the chapter on functions. In addition, there is a file named __init__.py. This file is necessary for Python to recognize the classwork directory as a package. It can be empty, but it must be present. Basically, ignore it for now. We will discuss such matters in due time.

We need to do one more thing. We need to create a notebooks directory (folder) in the root of the project. When you are complete, your file structure should look as follows:

.
├── notebooks
├── pyproject.toml
├── README.md
└── src
    └── classwork
        └── __init__.py

4 directories, 3 files

All Jupyter notebooks (.ipynb files) should be stored in the notebooks directory. This is a good practice to keep your project organized and maintain a clear separation between your source code and your notebooks.

Now you are ready to program!