Skip to content

Python

This project uses uv to manage its Python environments and dependencies.

Install

Outline

Order is important because each step relies on a previous one

  1. Disable the Python aliases included with Windows
    • Otherwise, they interfere with these tools
  2. Install the tool uv
    • This manages the project and Python environments instead
  3. Install Python
Further reading on this Python tooling, its uses, and how it works

Why we use uv run ...

  • uv manages the virtual environment and its commands for the project automatically
  • uv run ... activates the environment for the command that follows
  • uv invokes these managed commands and won't use a system-wide tool of the same name by accident

1. Disable Python aliases

  1. Open the Windows Settings app and navigate to:

    •   Settings Apps Advanced app settings App execution aliases

  2. Scroll down the list and disable these two entries:

    Name Detail
    App Installer python.exe
    App Installer python3.exe
Disable from PowerShell
PowerShell
# Disable the Windows Python aliases
rm "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\python.exe"
rm "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\python3.exe"

2. Install uv

Open PowerShell in Windows Terminal and install uv with winget.

PowerShell
# Install with winget
winget install --exact --id=astral-sh.uv

# Confirm that uv has been installed
uv self version

3. Install Python

Open PowerShell and use uv to install Python. We recommend Python 3.11 because it is the lowest version supported by the package.

PowerShell
# Show the available versions of Python
uv python list

# Install the latest release of a Python version
uv python install 3.11

# Set the default version of Python
uv pin --global 3.11

# Get the active version of Python
uv python find --show-version

# Show all installed and selectable versions
uv python list --only-installed

Testing code

This project focuses on writing and running tests that exercise either entire features or single functions. As bugs are fixed, we add tests that confirm the bug remains fixed.

Acceptance testing

Acceptance tests validate a use-case or workflow for a feature. They determine whether a user would find the behavior of the code acceptable.

Unit testing

Unit tests validate the outcome from running a function. They determine whether the code returns the correct output for the specified input. Input values in tests may be purposefully incorrect or inapplicable to validate that the code correctly handles error cases.

pytest

We use the tool pytest to run all of the project's tests.

PowerShell
# Run the tests
uv run pytest

# Print more information about failures
uv run pytest --verbose

The Python extension in VS Code automatically discovers the tests for this project and lists them in the testing side panel. In this view, you can also run tests and debug them.

Analyzing code

This project focuses on writing readable and unsurprising code. We run format, structure, and type analysis tools to identify code that doesn't match Python convention.

ruff

We use the tool ruff to check and fix format and structure problems.

Analyze

PowerShell
# Find differences from Python convention
uv run ruff check

# Find white space and line length problems
uv run ruff format --diff

# Show an explanation and examples for a violation
uv run ruff rule Z123

# Pipe to the tool 'mdv' to format the explanation
# - Install it with 'uv tool install mdv'
uv run ruff rule Z123 | mdv -

Fix

PowerShell
# Fix differences from Python convention
uv run ruff check --fix

# Apply formatting rules
uv run ruff format

The Python extension in VS Code can identify these problems and often has suggested fixes.

pyright

We use the tool pyright to check that functions accept and return compatible types and variables.

Analyze

PowerShell
# Find incompatible or incorrect uses of variables and classes
uv run pyright

Fix

Fixes are made by hand because pyright does not have a fix option. However, the Python extension in VS Code can identify these problems and often has suggested fixes.

Poe runner

The tool poe makes running the tests and analyzers easier because we use sequence tasks that call pytest, ruff, and pyright with their parameters.

PowerShell
# Runs 'pytest'
uv run poe test

# Runs 'ruff check'  then  'ruff format --diff'  then  'pyright --dependencies'
uv run poe lint

# Runs 'ruff check --fix'  then  'ruff format'
uv run poe fix