Python Packaging and pip Explained — Virtual Envs, requirements.txt and pyproject.toml

# Step 1: Create a virtual environment named 'venv' inside your project folder
# The 'venv' module ships with Python 3.3+ — no install needed
python3 -m venv venv

# Step 2: Activate it (Mac/Linux)
source venv/bin/activate

# Step 3: On Windows, activation looks different
# venv\Scripts\activate

# Your terminal prompt now shows (venv) to confirm isolation is active
# (venv) $ python --version

# Step 4: Verify pip points to the ISOLATED version, not the global one
which pip
# Output: /your/project/path/venv/bin/pip  <-- this is what you want

# Step 5: Install a package — it ONLY lives inside this virtual env
pip install requests

# Step 6: Deactivate when you're done with this project
deactivate

# After deactivating, 'which pip' points back to your global Python
# The 'requests' package you installed is GONE from the global scope
# It still lives safely inside the venv/ folder

# --- GENERATING requirements.txt ---

# Option A: Capture everything currently installed (exact versions)
# Good for: applications, deployment pipelines
pip freeze > requirements.txt

# Option B: Write it by hand with version ranges
# Good for: libraries, shared team projects with some flexibility
# Contents of requirements.txt would look like:
# requests>=2.28,<3.0
# flask>=2.3
# pytest>=7.0

# --- INSTALLING FROM requirements.txt ---

# On a new machine or fresh virtual environment:
pip install -r requirements.txt
# pip reads every line and installs the matching package version

# --- USING pip-tools FOR THE BEST OF BOTH WORLDS ---
# pip-tools separates your 'what I want' from 'what got installed'

pip install pip-tools

# Create requirements.in — you only list YOUR direct dependencies here
cat > requirements.in << 'EOF'
requests>=2.28
flask>=2.3
pytest>=7.0
EOF

# pip-compile reads requirements.in and resolves ALL transitive deps
# It writes a fully-pinned requirements.txt automatically
pip-compile requirements.in

# Now install from the generated, fully-pinned file
pip-sync requirements.txt
# pip-sync also REMOVES packages not in the file — keeps env clean

# pyproject.toml — the single source of truth for your Python project

[build-system]
# Declare what tools are needed to BUILD this package
# pip downloads these in an isolated environment before building
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "weather-fetcher"          # The name users will pip install
version = "1.0.0"
description = "Fetch weather data from public APIs with a clean interface"
readme = "README.md"
license = {file = "LICENSE"}
requires-python = ">=3.9"         # Minimum Python version supported

# Direct dependencies — use ranges, not pinned versions
dependencies = [
    "requests>=2.28,<3",
    "python-dotenv>=1.0",
]

# Optional dependency groups — installed with: pip install weather-fetcher[dev]
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
    "mypy>=1.0",
]

# Entry points: creates a 'weather' command in the terminal after install
[project.scripts]
weather = "weather_fetcher.cli:main"
# After `pip install .`, users can type `weather London` in their terminal
# Python maps this to: call the main() function in weather_fetcher/cli.py

# ---- Project structure that goes with this pyproject.toml ----
# weather-fetcher/
# ├── pyproject.toml
# ├── README.md
# ├── LICENSE
# └── src/
#     └── weather_fetcher/
#         ├── __init__.py
#         └── cli.py

# ---- Install locally in editable mode (changes reflect immediately) ----
# pip install -e .
# The -e flag means 'editable' — you can edit source files and test
# without reinstalling the package each time

# Install the build and upload tools
pip install build twine

# Step 1: BUILD your package
# This reads pyproject.toml and creates two files in the dist/ folder
python -m build
# Creates:
#   dist/weather_fetcher-1.0.0-py3-none-any.whl  (wheel — fast install)
#   dist/weather_fetcher-1.0.0.tar.gz             (source dist — fallback)

# Step 2: CHECK your package metadata before uploading
# twine check catches common mistakes like malformed README
twine check dist/*

# Step 3: TEST on TestPyPI first — always do this before the real thing
# Create a free account at https://test.pypi.org first
twine upload --repository testpypi dist/*
# You'll be prompted for your TestPyPI username and password (or API token)

# Step 4: Verify it installs correctly from TestPyPI
pip install --index-url https://test.pypi.org/simple/ weather-fetcher

# Step 5: When you're satisfied, publish to the REAL PyPI
# Create a free account at https://pypi.org first
twine upload dist/*

# After this, anyone in the world can install your package with:
# pip install weather-fetcher

# --- USING API TOKENS (recommended over passwords) ---
# 1. Go to pypi.org > Account Settings > API Tokens
# 2. Create a token scoped to your specific project
# 3. Store it in ~/.pypirc or use environment variables:
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmcA...  # your actual token
twine upload dist/*