# The Python Project Journey: A Tale of Two Developers (Part 1) In the world of software development, writing code is only half the battle. The other half—a critical, often underestimated challenge—is managing the environment in which that code runs. How do you ensure a project that works perfectly on your machine will also work perfectly on your colleague's? How do you handle dependencies without creating a tangled mess? This is the story of two developers, Alex and Ben. Through their journey, we will explore the fundamental tools and workflows that solve these problems in the Python ecosystem. This is the definitive guide to `pyenv`, `venv`, `pip`, and the magic of a file named `requirements.txt`. ## Chapter 1: Alex Starts a New Project (The Creator's Journey) Meet Alex. Alex is a thoughtful developer who believes that a project's foundation is just as important as its features. He is about to start a new data analysis application, "Project Insight," and he wants to do it right from the very beginning. ### Step 1: Choosing the Right Engine (`pyenv`) Alex knows that different projects may require different versions of Python. His last project used Python 3.8, but for Project Insight, he wants to use the latest features available in Python 3.10. If he just installed Python 3.10 system-wide, it could break his old project. This is a classic dilemma. Alex's solution is **`pyenv`**, a powerful Python version manager. It allows him to install multiple versions of Python on his computer and switch between them seamlessly. First, Alex asks `pyenv` to install the specific version he wants. ``` # Alex tells pyenv to install a very specific version of Python $ pyenv install 3.10.13 # After a few minutes of pyenv downloading and compiling, it's ready. ``` Now, he navigates to his new project directory and uses `pyenv` to "lock" this directory to that specific version. ``` $mkdir project-insight$ cd project-insight # This command creates a hidden .python-version file in the directory $ pyenv local 3.10.13 ``` This is Alex's first **Point of Certainty**. He can now verify that his shell is correctly configured. ``` # Alex performs his first check to ensure he has the right engine. $ python --version Python 3.10.13 ``` Success! `pyenv` has done its job. The `python` command in this directory now points to the exact version he needs. ### Step 2: Building the Workshop (`venv`) Alex knows that installing his project's packages globally is a recipe for disaster. If Project Insight needs version `2.0` of a library, but another project needs version `3.0`, they will conflict. His solution is to create a virtual environment using Python's built-in **`venv`** module. This creates an isolated "workshop" or "sandbox" just for Project Insight, where all its tools (packages) will live, completely separate from everything else on his computer. Because he already used `pyenv` to set his Python version, creating the workshop is simple and reliable. ``` # Alex uses the python he just verified to run its own venv module. # The command tells the module to create a workshop directory named ".venv" $ python -m venv .venv ``` The `.venv` directory is now sitting in his project folder. But just because the workshop exists doesn't mean he's inside it. ### Step 3: Entering the Workshop (`activate`) To start working, Alex must "activate" the environment. This action tells his terminal to use the tools inside the `.venv`workshop instead of his system's global tools. ``` $ source .venv/bin/activate # The prompt changes, giving him a clear visual cue. (.venv) $ ``` This is Alex's second **Point of Certainty**. He can now prove that his terminal session is completely isolated. He uses the `which` command to ask, "Where is the `python` I'm about to use?" ``` # Alex performs his second check. (.venv) $ which python /Users/alex/projects/project-insight/.venv/bin/python ``` The path points directly inside his project's `.venv` folder. This is irrefutable proof. He is safe to start installing packages. ### Step 4: Stocking the Workshop (`pip install`) Project Insight needs two key libraries: `requests` for fetching data from the web, and `pandas` for analyzing it. Alex uses `pip`, Python's package installer, to add them to his workshop. ``` # Because the environment is active, 'pip' installs these packages # directly into the .venv folder, not globally. (.venv) $ pip install requests pandas ``` He writes his application code, and everything works perfectly. ### Step 5: Creating the Shopping List (`pip freeze`) Alex's project is working on his machine, but his job isn't done. He needs to prepare it for his colleague, Ben. How can Ben recreate this perfectly stocked workshop on his own computer? Alex creates a "shopping list" that records every package and its exact version in his environment. The standard name for this file is `requirements.txt`. ``` # 'pip freeze' lists all installed packages and their versions. # The '>' redirects that output into a new file. (.venv) $ pip freeze > requirements.txt ``` He opens the `requirements.txt` file and sees a perfect record of his setup: ``` # requirements.txt certifi==2024.6.2 charset-normalizer==3.3.2 idna==3.7 numpy==1.26.4 pandas==2.2.2 python-dateutil==2.9.0.post0 pytz==2024.1 requests==2.32.3 six==1.16.0 urllib3==2.2.1 ``` Finally, Alex commits his work to Git. He adds his application code (`insight_app.py`) and his shopping list (`requirements.txt`). He explicitly tells Git to **ignore** the `.venv` folder. That folder is his personal workshop; Ben needs to build his own. The stage is now set for Ben. ## Chapter 2: Ben Joins the Project (The Collaborator's Journey) Meet Ben. Ben is a talented developer who has just been asked to contribute to Project Insight. His first task is to get the project running on his own machine. ### Step 1: Getting the Code and Checking the Engine Ben clones the project from the Git repository. ``` $git clone https://github.com/alex/project-insight.git$ cd project-insight ``` The first thing he sees is the `.python-version` file that Alex created. Ben also uses `pyenv`, so his system is already configured to read this file automatically. This is his first **Point of Certainty**. He immediately runs the same check Alex did. ``` # Ben verifies that pyenv has automatically set the correct Python version for him. $ python --version Python 3.10.13 ``` Perfect. Without any confusion or manual steps, Ben's machine is already aligned with the project's required Python version. ### Step 2: Building and Entering His Own Workshop Ben knows that the `.venv` folder wasn't included in the repository, so he needs to build his own local workshop. Because he just verified his active `python` is correct, he can proceed with confidence. ``` # Step 2: Ben builds his workshop. $ python -m venv .venv # Step 3: Ben enters his workshop. $ source .venv/bin/activate (.venv) $ ``` This is Ben's second **Point of Certainty**. He does the same `which` check as Alex. ``` (.venv) $ which python /Users/ben/dev/project-insight/.venv/bin/python ``` The path confirms he is now inside his own, brand new, isolated workshop. Currently, this workshop is empty. It has the Python 3.10 engine, but none of the special tools Alex installed. ### Step 3: Furnishing the Workshop (`pip install -r`) How does Ben get the right tools? He uses the `requirements.txt` shopping list that Alex so thoughtfully provided. This is the final, crucial step that connects their two worlds. ``` # The '-r' flag tells pip: "Read all the packages from the following file and install them." (.venv) $ pip install -r requirements.txt Collecting certifi==2024.6.2 Downloading certifi-2024.6.2-py3-none-any.whl (164 kB) ... Collecting pandas==2.2.2 Downloading pandas-2.2.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.0 MB) ... Successfully installed certifi-2024.6.2 charset-normalizer-3.3.2 ... pandas-2.2.2 ... ``` With that one command, `pip` reads the shopping list and furnishes Ben's workshop with the exact same tools, down to the precise version numbers, that Alex had in his. Ben can now run the application, confident that his environment is a perfect replica of Alex's. ## Part 1 Conclusion: The Pillars of Reproducibility Through the story of Alex and Ben, we've established a robust, reproducible workflow built on four pillars: 1. **`pyenv`**: Manages and selects the **Python interpreter version**. It provides the engine for your workshop. 2. **`venv`**: Creates an **isolated workshop** for a project, ensuring its tools (packages) don't conflict with other projects. 3. **`pip install <package>`**: The command used by the creator (Alex) to **stock the workshop** with tools for the first time. 4. **`pip install -r requirements.txt`**: The command used by the collaborator (Ben) to **furnish a new workshop**according to a precise shopping list. This workflow ensures that the dreaded phrase, "But it works on my machine!", becomes a thing of the past. _**Coming up in Part 2...**_ _Alex and Ben's team grows. They hire a developer who works in Node.js as well as Python. How can they manage multiple languages without multiple version managers? Then, they need to deploy Project Insight to a server for real users. How can they bundle not just the Python environment, but the entire operating system for perfect deployment? The journey continues with **`asdf`** and **`Docker`**._