01 — Introduction & Setup

# CPython's execution pipeline, observable from pure Python:
# 1. Source (.py) → compiler → bytecode (platform-independent .pyc)
# 2. Bytecode → CPython VM eval loop → execution
# 3. .pyc cached in __pycache__/ to skip step 1 on subsequent imports

import dis, sys, types

# Compile a function and inspect its bytecode — this is what the VM actually executes
def pipeline_example(data: list[int]) -> int:
    total = 0
    for item in data:
        if item > 0:                    # POP_JUMP_IF_FALSE branches at bytecode level
            total += item               # BINARY_OP in-place add
    return total

# disassembles to CPython bytecode — each line is one VM instruction
dis.dis(pipeline_example)
#  2           0 RESUME                   0      ← 3.11+ opcode, coroutine-aware entry
#  3           2 LOAD_CONST               1 (0)  ← push literal 0 onto value stack
#              4 STORE_FAST               1 (total) ← store into fast local slot 1
#  4           6 LOAD_FAST                1 (total) ← load local for loop init
#  ... (full output shows LOAD_FAST, BINARY_OP, POP_JUMP_IF_FALSE, JUMP_BACKWARD)

# The bytecode object itself is a real object you can inspect
code = pipeline_example.__code__
print(f"argcount={code.co_argcount}, varnames={code.co_varnames}")
print(f"stacksize={code.co_stacksize}  ← max value-stack depth the VM needs")
print(f"consts={code.co_consts}  ← literals folded into the code object at compile time")

# Production-grade: a bytecode-level hot-path analyzer
# Walks a function's code object to count specific opcodes — useful for
# understanding why a "simple" function is slow without a full profiler

import dis
from collections import Counter

def opcode_profile(func):
    """Count VM opcodes in a function — reveals hidden overhead in 'simple' code."""
    counts = Counter()
    for instr in dis.get_instructions(func):
        counts[instr.opname] += 1
    return counts

def naive_sum(data):
    total = 0
    for x in data:
        total += x          # LOAD_FAST + LOAD_CONST + BINARY_OP + STORE_FAST per iteration
    return total

profile = opcode_profile(naive_sum)
# Each loop iteration = ~4 opcodes × N iterations — this is why pure-Python
# loops are O(N) bytecode dispatches while sum(data) is a single C call
print(profile.most_common(5))
# [('LOAD_FAST', ...), ('STORE_FAST', ...), ('BINARY_OP', ...), ...]

# The GIL (Global Interpreter Lock) means only ONE thread executes CPython
# bytecode at any instant — even on a 64-core machine. This is because
# CPython's reference counting (refcount in every PyObject header) is not
# thread-safe without a global lock.
#
# Consequence: threading gives NO speedup for CPU-bound pure Python.
# Use multiprocessing (separate interpreters, separate GILs) for CPU parallelism.
# Use threading/asyncio for I/O-bound work (GIL released during I/O waits).

import threading, time, multiprocessing as mp

def cpu_bound(n):
    return sum(i * i for i in range(n))

if __name__ == "__main__":
    N = 20_000_000

    # Sequential baseline
    t0 = time.perf_counter(); cpu_bound(N); cpu_bound(N)
    print(f"sequential: {time.perf_counter() - t0:.2f}s")

    # Threading — NO parallelism for CPU-bound work (GIL serializes)
    t0 = time.perf_counter()
    threads = [threading.Thread(target=cpu_bound, args=(N,)) for _ in range(2)]
    for t in threads: t.start()
    for t in threads: t.join()
    print(f"2 threads (CPU-bound): {time.perf_counter() - t0:.2f}s  ← ~same as sequential")

    # Multiprocessing — TRUE parallelism (separate processes, separate GILs)
    t0 = time.perf_counter()
    with mp.Pool(2) as pool:
        pool.map(cpu_bound, [N, N])
    print(f"2 processes (CPU-bound): {time.perf_counter() - t0:.2f}s  ← ~half")

# ── Production-grade Python environment bootstrap ──
# Never use system Python for development — macOS ships 3.9 for OS tooling,
# Ubuntu ships whatever the distro pinned. Both are stale and shared with OS tools.

# Option A: uv (recommended 2025+) — manages interpreters AND venvs in one tool
curl -LsSf https://astral.sh/uv/install.sh | sh
eval "$(uv generate-shell-support)"   # or restart shell

uv python install 3.12.4               # downloads + installs a standalone CPython
uv python pin 3.12.4                    # writes .python-version for the project
uv venv .venv                           # creates isolated venv with its own site-packages
source .venv/bin/activate
uv pip install -e ".[dev]"              # editable install + dev extras from pyproject.toml

# Option B: pyenv + venv (traditional, works everywhere)
curl https://pyenv.run | bash
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

pyenv install 3.12.4
pyenv local 3.12.4                     # writes .python-version — pinned per-directory
python -m venv .venv                   # stdlib venv: own interpreter + own site-packages
source .venv/bin/activate
python -m pip install --upgrade pip    # bundled pip may lag by months

# Verify the environment is correctly isolated — critical for debugging import issues
which python                           # must resolve INSIDE .venv/bin/, not system
python -c "import sys; print(sys.executable)"  # the actual interpreter binary path
python -c "import sys; print(sys.prefix)"       # venv root — differs from base_prefix
python -c "import sys; print(sys.path)"        # site-packages should be .venv-local
pip show pip | grep Location            # confirms installs land in the right place

python

>>> 2 + 2
4
>>> import math
>>> math.sqrt(16)
4.0
>>> name = "Ada"
>>> f"Hello, {name}!"
'Hello, Ada!'
>>> exit()   # or Ctrl+D

pip install ipython
ipython

In [1]: %timeit sum(range(1000))
6.53 µs ± 45.1 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)

In [2]: import requests   # tab-completion, ? for docs
In [3]: requests.get?     # shows docstring and signature

print("Hello, World!")

python hello.py
# Hello, World!

# Run as a module (adds the script's directory to sys.path differently —
# matters for relative imports, see chapter 17)
python -m hello

# Pass arguments
python hello.py arg1 arg2   # available via sys.argv

#!/usr/bin/env python3
print("Hello from an executable script!")

chmod +x greet.py
./greet.py

# Force-see the bytecode cache
python -c "import mymodule"
ls __pycache__/
# mymodule.cpython-312.pyc

# Inspect bytecode directly
python -c "
import dis
def add(a, b):
    return a + b
dis.dis(add)
"

  2           0 RESUME                   0
  3           2 LOAD_FAST                0 (a)
              4 LOAD_FAST                1 (b)
              6 BINARY_OP                0 (+)
             10 RETURN_VALUE

# The performance gap, demonstrated — same algorithm, different execution paths
import time

N = 5_000_000

# Pure-Python loop — millions of bytecode dispatches, each with type dispatch overhead
t0 = time.perf_counter()
total = 0
for i in range(N):
    total += i
python_loop = time.perf_counter() - t0     # ~0.3s — each += is 4+ VM opcodes

# Built-in sum() — single C function call, loop runs in compiled C, no per-element dispatch
t0 = time.perf_counter()
total = sum(range(N))                       # C-level iteration, no bytecode per element
builtin_sum = time.perf_counter() - t0      # ~0.03s — 10× faster, same algorithm

# numpy — SIMD-vectorized C, operates on contiguous memory blocks
import numpy as np
t0 = time.perf_counter()
total = int(np.arange(N).sum())              # single C call over a contiguous int64 buffer
numpy_sum = time.perf_counter() - t0         # ~0.005s — 60× faster than the Python loop

print(f"python loop:  {python_loop:.4f}s  ({N:,} bytecode dispatches)")
print(f"builtin sum:  {builtin_sum:.4f}s  (1 C call)")
print(f"numpy sum:    {numpy_sum:.4f}s  (SIMD-vectorized C)")

my-project/
├── pyproject.toml       # modern project metadata, deps, build config (ch. 25)
├── README.md
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── main.py
│       └── utils.py
├── tests/
│   └── test_utils.py
└── .python-version      # pyenv local version pin

# project layout:
# project/
#   src/
#     app/
#       __init__.py
#       main.py      # does `from app.utils import helper`
#       utils.py

cd project/src/app
python main.py