Environments, packaging and tooling

Code that runs on your machine and nowhere else is not finished. This section covers what makes a project portable: a virtual environment so each project keeps its own packages and versions, pinned dependencies so a colleague installs exactly what you did, a layout people expect to find, and tools that format and check the code for you. It ends on reading a traceback, which is the single most useful debugging skill in the language.

Virtual environments#

A virtual environment is a folder holding its own copy of Python and its own packages. Each project gets one, so two projects can use different versions of the same library without fighting.

python3 -m venv .venv           # create it
source .venv/bin/activate       # turn it on (Mac and Linux)
.venv\Scripts\activate          # Windows

which python                    # .../project/.venv/bin/python
deactivate                      # turn it off

Activating simply puts that folder first in your PATH, which is the list of places your shell searches for commands. So typing python finds the project copy instead of the system one. That is the whole mechanism.

Dependencies#

pip install requests
pip install "pydantic>=2.0"
pip freeze > requirements.txt      # record exact versions
pip install -r requirements.txt    # install them elsewhere

Recording exact versions matters more than it seems. Without it, a project that builds today can break in three weeks because a library you never named published an update. The failure arrives in CI on an unrelated change and costs an afternoon.

Project layout#

myproject/
  .venv/              never committed
  .env                secrets, never committed
  .gitignore
  pyproject.toml      project and dependency declaration
  README.md
  src/
    myproject/
      __init__.py
      main.py
  tests/
    test_main.py

Secrets belong in a .env file that is listed in .gitignore, and are read at runtime. An API key committed to a public repository is scanned and abused within minutes.

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.environ["GEMINI_API_KEY"]

Tooling#

• ruff: linting and formatting in one tool, fast enough to run every time you save.
• uv: a much faster replacement for pip and venv, worth adopting on new projects.
• A type checker in your editor, so annotations help you while you type rather than in CI.

ruff check .          # find problems
ruff check --fix .    # fix what it can
ruff format .         # format everything

Reading a traceback#

Read a traceback from the bottom up. The last line is the actual error. The lines above it are the path of calls that led there, oldest at the top.

Traceback (most recent call last):
  File "main.py", line 12, in <module>
    result = process(data)
  File "process.py", line 8, in process
    return item["name"]
KeyError: 'name'

When the trace runs through library code, find the last line that belongs to you. That is almost always where the problem is, because the library is usually doing exactly what it was told.