Project Setup

Getting a reproducible development environment off the ground

Concepts

• A virtual environment is an isolated copy of Python with its own set of packages
  • Installing something for one project does not affect any other project on the same machine
  • Why do research projects need virtual environments if we're just writing scripts for our own use?
• uv manages both the virtual environment and the packages inside it
  • uv add installs a package and records it in pyproject.toml
  • uv sync recreates the environment from that record
  • uv run something runs in the environment
  • Or activate it with source .venv/bin/activate and run something
  • Explain what adding a dependency with uv add actually does to pyproject.toml and uv.lock
• uv.lock pins the exact version of every package (including transitive dependencies) so that anyone who runs uv sync gets bit-for-bit the same environment you tested with
  • What would go wrong if two researchers are working on the same project but have different versions of a shared library?
• pyproject.toml is the single source of truth for project metadata, dependencies, and tool configuration
  • Show me what a minimal pyproject.toml looks like for a Python web application
• The [tool.taskipy.tasks] section of pyproject.toml stores the shell commands needed to build, test, and run the project so that no one has to remember or retype them
  • task <name> runs any task by name.
  • What taskipy tasks should a research Python project have by default?

Create the project with uv

• Why uv instead of pip or conda for research projects
  • What are the disadvantages of uv versus pip or conda for managing a research project?
• uv init
  • Walk me through what uv init creates and what each generated file does
• Structure of a minimal pyproject.toml
  • Explain each field in a minimal pyproject.toml for a Python web application

Add dependencies

• uv add for runtime packages
  • Add litestar, htpy, and snailz as runtime dependencies to this project
• uv add --dev for linting and testing
  • Add ruff and pytest as development dependencies using uv
• Checking uv.lock into version control and why it matters
  • What would go wrong if I added uv.lock to .gitignore?
• PEP 723 headers
  • What is a PEP 723 header and when would I use one in a research script?

Automate tasks with taskipy

• Storing tasks in pyproject.toml alongside dependencies and tool configuration so the project has a single configuration file
  • Add a taskipy task to update all dependencies in the project to their latest allowed versions
• Writing taskipy tasks for running the server, tests, and linters
  • Write a taskipy tasks for running the ruff linter for this project

Lay out project

• Directories for source code, tests, static assets, and data
  • Describe a layout for a simple Python web application that separates source code, tests, static assets, and data
• Prompting an LLM to propose a layout and evaluating the result
  • What questions should I ask to decide whether an LLM's suggested project layout is well-organized?
• Finish with a "hello world" script that imports each major dependency and run it to confirm everything is wired up
  • Write a hello world script that imports litestar, htpy, and snailz and prints their version numbers to confirm they are all installed correctly

Check for Understanding

Exercises

Extend the tasks

Add two new tasks to the [tool.taskipy.tasks] section of pyproject.toml: one that opens a Python REPL inside the virtual environment, and one that prints the exact Python version in use. Run both to confirm they work. Ask the LLM to help, then read the generated task definitions and make sure you understand what each one does before accepting it.

Explore dependency trees

Run uv tree and examine the output. Identify which of your runtime dependencies pulls in the most transitive packages. Ask the LLM to explain why that dependency has so many sub-dependencies and evaluate whether the explanation makes sense given what you know about the package.

Reproduce from scratch

Clone the repository into a fresh directory on your machine (or ask a classmate to do it on theirs). Prompt an LLM to set up an environment using the instructions in pyproject.toml and the README, then check that the "hello world" script runs.

Pin a specific version

Prompt the LLM to change the snailz dependency to a specific older version. Observe what changes in pyproject.toml and uv.lock, then restore the original constraint and explain the difference between a version constraint and a pinned version in one sentence.