devsetup1-5  Exercise 1: Installing Python Support and Meeting PEP 668
=======================================================================

STEP 1: INSTALL
---------------
    sudo apt install python3-pip python3-venv python3-dev pipx

STEP 2: VERIFY WITH THE CHAPTER 3 TOOLS
---------------------------------------
    for p in python3-pip python3-venv python3-dev pipx; do
      dpkg-query -W -f='${Package} ${Version} ${db:Status-Abbrev}\n' "$p"
    done
    python3 --version          # expect Python 3.13.x
    pip --version
    pipx --version
    type -a python3            # expect a single /usr/bin/python3

Each package line should end with "ii". Your version strings will differ.

STEP 3: TRIGGER THE ERROR
-------------------------
    pip install requests

Expected: the install is refused, with an error beginning
"error: externally-managed-environment" and text saying the environment is
managed by the operating system, and suggesting a virtual environment or
apt (python3-NAME) instead.

WHAT PEP 668 IS
---------------
PEP 668 is a Python standard that lets an operating system mark its Python
installation as "externally managed". Debian does this with a marker file
named EXTERNALLY-MANAGED in the standard library directory. When pip finds it,
it refuses to install or change packages in that Python, unless you explicitly
override the check.

WHY DEBIAN ENFORCES IT
----------------------
Debian's own tools are written in Python and rely on particular versions of
particular libraries. If pip changed one of those system-wide, a Debian tool
could break, and the failure would show up somewhere unrelated to what you
did. Refusing the install removes that whole category of accident.

STEP 4: DO IT CORRECTLY
-----------------------
    mkdir -p ~/projects/pep668-test && cd ~/projects/pep668-test
    python3 -m venv .venv
    source .venv/bin/activate
    pip install requests           # succeeds this time
    pip list
    python3 -c "import requests; print(requests.__version__)"
    deactivate

Then check the system Python did not change:

    python3 -c "import requests"   # should fail with ModuleNotFoundError,
                                   # unless python3-requests was already
                                   # installed from apt

WHY THIS WORKS AS AN ANSWER
---------------------------
It shows the rule from both sides: the refusal, the reasoning behind it, and
the correct workflow that succeeds. The last check proves the install went
into the venv and did not touch the system Python.