Python pip — Container ImportError from Global Packages

# ── CREATING A VIRTUAL ENVIRONMENT ─────────────────────────────────────────
# The 'venv' module ships with Python 3.3+ — no separate install needed
# Always create inside your project folder so it's self-contained
python3 -m venv venv

# ── ACTIVATION ──────────────────────────────────────────────────────────────
# Mac/Linux: updates PATH to point to venv's Python and pip
source venv/bin/activate

# Windows Command Prompt:
# venv\Scripts\activate

# Windows PowerShell:
# venv\Scripts\Activate.ps1

# Your terminal prompt changes to show (venv) — visual confirmation you're isolated

# ── VERIFY YOU'RE IN THE RIGHT ENVIRONMENT ──────────────────────────────────
# Both should point INSIDE your project folder, not /usr/bin or /usr/local
which python
# Good: /home/user/myproject/venv/bin/python
# Bad:  /usr/bin/python3  (you're still global)

which pip
# Good: /home/user/myproject/venv/bin/pip
# Bad:  /usr/local/bin/pip  (wrong environment)

# ── INSTALL PACKAGES ────────────────────────────────────────────────────────
# Only lands inside this venv — completely invisible to other projects
pip install requests flask pytest

# Verify what's installed and where
pip list
# Shows ONLY packages in this venv, not global packages

# ── DEACTIVATION ────────────────────────────────────────────────────────────
deactivate
# PATH reverts. 'which python' now points to the system Python again.
# The packages you installed are still in venv/lib/ — they're just not active

# ── USING uv (faster alternative, Rust-based) ───────────────────────────────
# pip install uv  (or: curl -LsSf https://astral.sh/uv/install.sh | sh)
uv venv .venv          # creates a venv at .venv/ — significantly faster than python -m venv
source .venv/bin/activate
uv pip install requests  # 5-10x faster than pip for most packages

# ── APPROACH 1: pip freeze (simple, good for apps) ─────────────────────────
# Captures everything currently installed at exact versions
# Best for: application deployments where you need byte-for-byte reproducibility

pip freeze > requirements.txt
# Output includes direct AND transitive deps, all pinned:
# certifi==2024.2.2
# charset-normalizer==3.3.2
# idna==3.6
# requests==2.31.0

# ── APPROACH 2: Hand-written with ranges (good for libraries) ──────────────
# Only list your direct dependencies with reasonable version constraints
# Best for: libraries others will install alongside their own packages

cat > requirements.txt << 'EOF'
requests>=2.28,<3
flask>=3.0
pytest>=7.0
EOF

# ── APPROACH 3: pip-tools (best of both worlds, production standard) ────────
pip install pip-tools

# Create requirements.in — your direct dependencies with loose constraints
# This is the human-editable file you commit and maintain
cat > requirements.in << 'EOF'
requests>=2.28
flask>=3.0
pytest>=7.0
EOF

# pip-compile resolves the full dependency graph and generates requirements.txt
# --generate-hashes adds SHA256 hashes for supply chain security (optional but recommended)
pip-compile requirements.in
# or with hashes:
pip-compile --generate-hashes requirements.in

# pip-sync installs EXACTLY what's in requirements.txt AND removes anything not listed
# This guarantees your environment matches the lockfile exactly
pip-sync requirements.txt

# ── UPDATING DEPENDENCIES ───────────────────────────────────────────────────
# To update a specific package to a newer version:
pip-compile --upgrade-package requests requirements.in
# Updates requests and adjusts any transitive deps that change as a result

# To update everything to the latest compatible versions:
pip-compile --upgrade requirements.in

# ── CHECKING FOR SECURITY VULNERABILITIES ───────────────────────────────────
# pip-audit checks all installed packages against the Python Advisory Database
pip install pip-audit
pip-audit
# Reports any known CVEs in your installed dependencies

# pyproject.toml — the single source of truth for your Python project
# Replaces setup.py, setup.cfg, and MANIFEST.in entirely

[build-system]
# Which tools are needed to BUILD this package
# pip downloads and uses these in an isolated temporary environment
# before building — no pre-installed tools required
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "weather-fetcher"              # The name users will 'pip install'
version = "1.0.0"                     # Follow semantic versioning: MAJOR.MINOR.PATCH
description = "Fetch weather data from public APIs with a clean interface"
readme = "README.md"                  # Displayed on PyPI project page
license = {file = "LICENSE"}
requires-python = ">=3.9"             # Minimum Python version your code supports
authors = [
    {name = "Your Name", email = "you@example.com"}
]
keywords = ["weather", "api", "cli"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

# Direct dependencies — use ranges, never exact pins
# These are installed automatically when someone 'pip install weather-fetcher'
dependencies = [
    "requests>=2.28,<3",
    "python-dotenv>=1.0",
]

[project.urls]
Homepage = "https://github.com/yourname/weather-fetcher"
Documentation = "https://weather-fetcher.readthedocs.io"
Changelog = "https://github.com/yourname/weather-fetcher/blob/main/CHANGELOG.md"
Issues = "https://github.com/yourname/weather-fetcher/issues"

# Optional dependency groups — users install with: pip install weather-fetcher[dev]
# Keep dev tools out of the main dependency list
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "black>=24.0",
    "mypy>=1.0",
    "ruff>=0.3",
]
docs = [
    "sphinx>=7.0",
    "sphinx-rtd-theme>=2.0",
]

# Entry points: registers a 'weather' command in the user's terminal after install
# Python maps 'weather' to: call the main() function in weather_fetcher/cli.py
[project.scripts]
weather = "weather_fetcher.cli:main"
# After 'pip install .': user can type 'weather London' in any terminal

# ── Project layout that matches this pyproject.toml ─────────────────────────
# weather-fetcher/
# ├── pyproject.toml
# ├── README.md
# ├── LICENSE
# ├── CHANGELOG.md
# └── src/
#     └── weather_fetcher/
#         ├── __init__.py
#         └── cli.py

# The src/ layout is recommended — it prevents accidental imports from the
# project root during development, ensuring you're always testing the installed package

# ── Local development install ────────────────────────────────────────────────
# pip install -e .        (install core only)
# pip install -e .[dev]   (install core + dev tools)
# The -e flag means 'editable' — edit source files and changes are immediately
# reflected without reinstalling the package

# ── PREREQUISITES ────────────────────────────────────────────────────────────
# Create accounts at:
#   https://test.pypi.org   (for testing)
#   https://pypi.org        (for production)
# Enable 2FA on both accounts — PyPI requires it for new publishers

pip install build twine

# ── STEP 1: BUILD ────────────────────────────────────────────────────────────
# Reads pyproject.toml and builds both wheel and source dist
# Creates files in the dist/ folder
python -m build
# Output:
#   dist/weather_fetcher-1.0.0-py3-none-any.whl   (wheel — fast install)
#   dist/weather_fetcher-1.0.0.tar.gz              (sdist — fallback)

# ── STEP 2: VERIFY before uploading ─────────────────────────────────────────
# Catches malformed README, missing metadata, and packaging mistakes
# before they become permanent PyPI entries
twine check dist/*
# Expected output: PASSED for both files

# ── STEP 3: TEST on TestPyPI — always do this first ─────────────────────────
twine upload --repository testpypi dist/*
# You'll be prompted for TestPyPI credentials or API token

# Verify the TestPyPI install works end-to-end:
pip install \
    --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    weather-fetcher
# --extra-index-url allows pip to find dependencies on real PyPI
# since test.pypi.org doesn't have all packages

# Test the entry point works:
weather London

# ── STEP 4: PUBLISH to real PyPI when satisfied ──────────────────────────────
twine upload dist/*
# After this, the package is live at https://pypi.org/project/weather-fetcher/
# Anyone can now: pip install weather-fetcher

# ── API TOKENS (strongly recommended over passwords) ─────────────────────────
# Go to pypi.org > Account Settings > API Tokens
# Create a token scoped to this specific project (not account-wide)
# Then pass it to twine:
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmcA...  # your actual token
twine upload dist/*

# Or store in ~/.pypirc to avoid env vars:
# [pypi]
# username = __token__
# password = pypi-AgEIcHlwaS5vcmcA...

# ── AUTOMATING WITH GITHUB ACTIONS ──────────────────────────────────────────
# .github/workflows/publish.yml
# Triggers on: push of tags matching v*.*.* (e.g., v1.0.0)
# Steps: checkout → build → test on TestPyPI → publish to PyPI
# Use PyPI's Trusted Publishers (OIDC) to skip token management entirely
# See: https://docs.pypi.org/trusted-publishers/