Environments, packaging & dependencies

A virtual environment (venv) is a private, throwaway folder that holds one project's Python packages. Without it, every pip install dumps packages into your system Python, so two projects that need different versions of the same package fight each other. A venv gives each project its own clean box. This lab creates one, turns it on, installs a package into it, and records what got installed.

1. python3 -m venv .venv creates the environment in a hidden folder named .venv inside your project. It's just a directory of files — nothing is installed system-wide yet.
2. source .venv/bin/activate switches on the venv for this terminal. You'll see (.venv) appear at the start of your prompt — that's how you know packages will now go into the project's box, not the system.
3. pip install requests downloads the requests package into the active venv only. Other projects never see it.
4. pip freeze > requirements.txt writes the exact versions of everything installed into a text file (the > saves the output to that file). That file is the recipe someone else uses to rebuild the same setup.
5. deactivate turns the venv back off, returning your terminal to the system Python.

What the output means: Nothing dramatic prints; the payoff is on disk — a .venv/ folder holding requests, and a requirements.txt listing its exact version.

Try this: Run these lines, then type which python before and after deactivate. Inside the venv it points into .venv/; after deactivating it points back at the system Python. That path change is the isolation.

requirements.txt is your project's shopping list of exact package versions. This lab shows the full loop: install what you need, snapshot it, then rebuild it identically on another machine. This is how you avoid "but it worked on my laptop".

1. pip install fastapi uvicorn installs two packages (a web framework and the server that runs it) into the active venv.
2. pip freeze > requirements.txt snapshots every installed package and its exact version into the file — not just the two you named, but everything they pulled in too.
3. pip install -r requirements.txt is the reverse: the -r flag means "read this requirements file and install exactly what it lists." Run on a teammate's machine, a CI runner, or inside a container, it recreates the same environment.
4. cat requirements.txt just prints the file so you can see the pinned lines, e.g. fastapi==0.115.0. The == means "exactly this version".

What the output means: The cat shows lines like fastapi==0.115.0 — one per package, each locked to a specific version.

Try this: Open requirements.txt after running freeze. You'll see more lines than the two packages you installed — those extras are dependencies-of-dependencies, captured automatically so the rebuild is complete.

Package versions look like 2.3.1 = MAJOR.MINOR.PATCH. A MAJOR bump (2 → 3) can break your code; MINOR and PATCH bumps are meant to be safe. This tiny program checks whether a version falls inside an allowed range, which is exactly the question pip asks before upgrading.

1. parse(v) turns the string "2.3.1" into the number triple (2, 3, 1) by splitting on the dots — so versions can be compared like numbers instead of text.
2. is_compatible(...) returns True only if the version is at or above the minimum and its major number (h[0]) is below the cutoff major. That mirrors a spec like >=2.3,<3.
3. The first print checks 2.3.1 against >=2.3,<3 — it fits, so it prints True.
4. The second checks 3.0.0 against the same range. Its major is 3, which is not below 3, so it prints False — a breaking major that you should review before upgrading.

What the output means: True then False: 2.3.1 is inside the allowed range, 3.0.0 is a breaking major that falls outside it.

Try this: Change the check to is_compatible("2.9.9", "2.3.0", 3) — still True, because any 2.x is allowed. Then try "2.2.0": False, because it's below the 2.3 minimum.

When two of your packages each demand a different version of a third package, something has to give — that's a dependency conflict. Real tools like pip run a resolver to find one version that satisfies everyone, or to report failure. This lab is a miniature resolver so you can see the logic.

1. resolve(constraints, available) takes a list of rules and the list of versions that actually exist, and returns the highest version that obeys all the rules.
2. ok(v, c) is true when a version v sits inside one constraint's window (at or above min, below lt_major).
3. The loop walks versions highest-first (reverse=True) and returns the first that passes all(...) the constraints — so you always get the newest version that fits.
4. First run: pkgA needs >=1.2,<2 and pkgB needs >=1.5,<2. The newest version satisfying both is 1.9.
5. Then a conflict is added: pkgC demands >=2.0, but the others cap at below 2.0. No single version can satisfy all three, so resolve returns None.

What the output means: resolved to: 1.9 (a version everyone accepts), then with pkgC>=2.0: None — None is the resolver's way of saying "impossible, these requirements conflict."

Try this: Add 2.5 to the avail list and change pkgA/pkgB's lt_major to 3.0. Now the conflict disappears and the resolver finds a version that satisfies pkgC too.

This isn't code that runs — it's the standard folder shape of a professional Python project. Following it means tools, teammates, and packaging all know where to look. The ├── and └── lines are just a drawing of the folder tree (indentation = "inside this folder").

1. README.md explains the project; .gitignore lists files Git should ignore (like .venv/).
2. pyproject.toml is the modern control file: it holds the project's name, version, dependencies, and how to build it (covered in the next lab).
3. src/my_project/ holds your actual code. __init__.py marks the folder as an importable package; core.py is your module. Putting code under src/ prevents accidentally importing it before it's properly installed.
4. tests/ holds your tests, kept separate from the code they check.

Try this: Compare this to your own scripts folder. The single biggest upgrade is moving loose .py files into src/my_project/ and adding a pyproject.toml — that's what turns "some scripts" into "a package".

pyproject.toml is the one file that describes your whole package: its name, version, what Python it needs, its dependencies, and how to build it. It's written in TOML — a simple key = value config format grouped into [sections]. This replaces the older setup.py.

1. [project] holds the basics: name, version, the minimum Python (requires-python), and dependencies — here a range requests>=2.30,<3 meaning "any 2.x from 2.30 up."
2. [project.scripts] creates a command-line command. mytool = "my_project.core:main" means "after install, typing mytool in a terminal runs the main function in core.py."
3. [build-system] tells pip which tool builds the package (hatchling here). You rarely change this — it's boilerplate.
4. The comments show the two commands you'll actually run: python -m build makes a shippable file (a wheel), and pip install -e . does an editable install — installs the project while pointing at your source so edits take effect without reinstalling.

Try this: Run pip install -e . in a folder with this file, then type mytool. The command exists because of the [project.scripts] line — that's how CLI tools like black or pytest become terminal commands.

Sometimes you need your program to ask "what's actually installed here, and which version?" — for logging, debugging, or compatibility checks. Python's built-in importlib.metadata reads that information straight from the environment, no extra packages needed.

1. from importlib.metadata import version, distributions pulls in two helpers: version (get one package's version) and distributions (list everything installed).
2. version("pip") returns pip's own version as a string and prints it.
3. distributions() yields every installed package; the code reads each one's "Name", sorts them, and keeps the first five ([:5]) as a sample.
4. The final print shows that short sample list.

What the output means: Two lines: pip's version (e.g. pip: 24.0) and the first few installed package names alphabetically — a quick snapshot of what lives in this venv.

Try this: Change [:5] to [:20] to see more, or call version("requests"). If you ask for a package that isn't installed, you'll get an error — which is exactly what the next lab turns into a useful CI check.

A team lead's job is to make sure everyone runs the same versions. This script is a drift check: it compares what's installed against what's required and reports any mismatch. Wired into CI, it fails the build before a version mismatch causes a "works on my machine" bug.

1. REQUIRED is a dictionary of package: expected-major-version. Here it only checks that pip exists (None = don't check the version); the comment shows a real one pinning majors like {"requests":"2", "pytest":"8"}.
2. audit(required) loops over each required package and collects problems into a list.
3. try: have = version(pkg) attempts to read the installed version. If the package is missing it raises PackageNotFoundError, which the except catches and records as MISSING instead of crashing.
4. have.split(".")[0] grabs the installed major number. If it doesn't match the wanted major, that's flagged as drift.
5. Finally it prints environment OK when the problems list is empty, or lists every problem it found.

What the output means: environment OK — the list of problems was empty, so the environment matches requirements. In CI you'd have the script exit non-zero on problems to fail the build.

Try this: Add a fake package: REQUIRED = {"pip": None, "nonexistent-pkg": "1"} and re-run. You'll see DRIFT: MISSING: nonexistent-pkg — the exact signal that stops a broken environment from shipping.