Python Project Workflow: Init, Dependencies, and Debug

Knowing Python syntax is only half the picture. The other half is knowing how to actually run a project day to day: how to start a new one cleanly, how to add packages without breaking other projects, how to debug when things go wrong, and how to keep your configuration files honest. This page gives you the practical workflow you will use every single day.

Initialising a new project

With uv (recommended)
Manual setup

uv scaffolds a complete project in one command and is dramatically faster than pip for everything it does.

# Create a new project folder with everything set up
uv init weather-analysis
cd weather-analysis

uv init creates:

weather-analysis/
├── .python-version     # pins the Python version (e.g. 3.12)
├── .gitignore
├── pyproject.toml
├── README.md
└── main.py

Create the virtual environment and install dependencies in one step:

uv sync          # creates .venv and installs everything in pyproject.toml

To add a package:

uv add requests pandas matplotlib

This updates pyproject.toml and uv.lock automatically — no manual editing needed.

If you prefer the standard toolchain:

# 1. Create the project folder
mkdir weather-analysis && cd weather-analysis

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\Activate.ps1     # Windows PowerShell

# 3. Upgrade pip
pip install --upgrade pip

# 4. Install dependencies
pip install requests pandas matplotlib

# 5. Freeze the exact versions you used
pip freeze > requirements.txt

Create a minimal pyproject.toml by hand:

[project]
name = "weather-analysis"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
    "pandas>=2.0",
    "matplotlib>=3.8",
]

Managing multiple Python versions

Different projects often need different Python versions. uv handles this transparently:

# Pin a specific Python version for the current project
uv python pin 3.12

# Install that version if it is not already present
uv python install 3.12

# Check which version is active
python --version

uv writes the pinned version to .python-version. Commit this file so every contributor uses the same interpreter. If you work with many Python versions regularly, pyenv is an alternative that works independently of uv.

Running scripts

Always run scripts from the project root directory using the -m flag. This guarantees that your package is on sys.path and that relative paths in your code resolve correctly.

# From the project root:
python -m weather_analysis.main

# With uv (runs inside the project's venv automatically):
uv run python -m weather_analysis.main

# Or run a standalone script:
uv run python scripts/fetch_data.py

If you double-click a .py file or run python src/weather_analysis/main.py from the wrong directory, your imports will likely fail. The -m flag plus running from the project root is the single habit that prevents 90% of path errors.

Adding a new feature — end-to-end workflow

Here is the workflow you will follow every time you add a new capability to your project:

Create a new module

Add a new file for the feature’s logic. Keep it focused — one clear responsibility per file.

touch src/weather_analysis/alerts.py

# src/weather_analysis/alerts.py

def check_frost_risk(min_temp_c: float, threshold: float = 2.0) -> bool:
    """Return True if the minimum temperature is near or below freezing."""
    return min_temp_c <= threshold

def summarise_alerts(temperatures: list[float]) -> list[str]:
    """Return a list of human-readable alert strings."""
    alerts = []
    for i, temp in enumerate(temperatures, start=1):
        if check_frost_risk(temp):
            alerts.append(f"Day {i}: frost risk ({temp:.1f}°C)")
    return alerts

Write the functions and add a test

Create the corresponding test file immediately — not after everything is working.

touch tests/test_alerts.py

# tests/test_alerts.py
from weather_analysis.alerts import check_frost_risk, summarise_alerts

def test_frost_risk_detected():
    assert check_frost_risk(1.5) is True

def test_no_frost_risk():
    assert check_frost_risk(10.0) is False

def test_summarise_alerts_count():
    temps = [5.0, 1.0, -2.0, 12.0, 0.5]
    alerts = summarise_alerts(temps)
    assert len(alerts) == 3   # days 2, 3, and 5

Run the tests:

pytest tests/test_alerts.py -v

Import the new module in main.py

Wire the new feature into your entry point once you are satisfied with the tests.

# src/weather_analysis/main.py
from weather_analysis.data_fetcher import fetch_weather
from weather_analysis.data_processor import calculate_stats
from weather_analysis.alerts import summarise_alerts     # ← new import

def run():
    data = fetch_weather(city="Paris")
    stats = calculate_stats(data["min_temp"])
    alerts = summarise_alerts(data["min_temp"])          # ← new usage

    print(f"Average low: {stats['average']:.1f}°C")
    if alerts:
        print("\n⚠️  Frost alerts:")
        for alert in alerts:
            print(f"   {alert}")

Update pyproject.toml if you added a dependency

If the new feature uses a third-party package, record it properly:

# With uv — updates pyproject.toml and uv.lock automatically
uv add some-new-package

# With pip — install then freeze
pip install some-new-package
pip freeze > requirements.txt

Never assume a package is “already there”. Document every dependency you use.

Updating dependencies

With uv
With pip

# Update all packages to their latest allowed versions
uv lock --upgrade

# Update a single package
uv lock --upgrade-package pandas

# After updating the lock file, sync your environment
uv sync

# List outdated packages
pip list --outdated

# Upgrade a specific package
pip install --upgrade pandas

# Regenerate requirements.txt after upgrading
pip freeze > requirements.txt

Always run your test suite after updating dependencies. A minor version bump in a library can introduce breaking changes. Run pytest before committing updated lock files.

Reading error tracebacks effectively

Python tracebacks look intimidating but follow a consistent pattern. Read them from the bottom up — the last line is the actual error, and the lines above it are the call stack that led there.

Traceback (most recent call last):
  File "src/weather_analysis/main.py", line 12, in run    ← outermost call
    stats = calculate_stats(data["min_temp"])
  File "src/weather_analysis/data_processor.py", line 8, in calculate_stats
    return sum(temperatures) / len(temperatures)           ← where it happened
ZeroDivisionError: division by zero                        ← the actual error

Your reading checklist:

What is the error type? (ZeroDivisionError, KeyError, TypeError …)
What is the error message? (often tells you exactly what went wrong)
Which file and line number is at the bottom of the stack? (that is where to fix it)
Work upward through the call stack to understand why the bad value arrived there

Debugging workflow

Quick debugging with print statements

For simple problems, print is fast and requires no setup:

def calculate_stats(temperatures):
    print(f"DEBUG: received {len(temperatures)} temperatures: {temperatures[:5]}")  # add this
    if not temperatures:
        raise ValueError("Temperature list is empty")
    return {
        "average": sum(temperatures) / len(temperatures),
        "min": min(temperatures),
        "max": max(temperatures),
    }

Remove print debugging before committing. Use the logging module for persistent diagnostic output instead:

import logging

logging.basicConfig(level=logging.DEBUG, format="%(levelname)s: %(message)s")
logger = logging.getLogger(__name__)

def calculate_stats(temperatures):
    logger.debug("Received %d temperatures", len(temperatures))
    # ...

VS Code debugger

For harder bugs, the VS Code debugger lets you pause execution and inspect any variable without modifying your code.

Set a breakpoint

Click in the gutter (left of the line numbers) on the line where you want execution to pause. A red dot appears.

Start the debugger

Press F5, or open the Run & Debug panel (Ctrl+Shift+D / ⇧⌘D) and click Run and Debug. Choose Python File.

Inspect variables

When execution pauses at your breakpoint, hover over any variable to see its value, or expand the Variables panel on the left. Use the toolbar buttons to step over, step into, or continue.

Create a .vscode/launch.json to configure the debugger for your project:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run weather-analysis",
      "type": "python",
      "request": "launch",
      "module": "weather_analysis.main",
      "cwd": "${workspaceFolder}",
      "justMyCode": true
    }
  ]
}

Keeping `pyproject.toml` tidy

Your pyproject.toml is the source of truth for your project. Keep it honest:

[project]
name = "weather-analysis"
version = "0.1.0"
description = "Fetch and analyse weather data from Open-Meteo"
requires-python = ">=3.11"

# Runtime dependencies — needed to run the project
dependencies = [
    "requests>=2.31",
    "pandas>=2.0",
    "matplotlib>=3.8",
]

[project.optional-dependencies]
# Development tools — needed only by contributors, not by end-users
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.9",
]

[tool.ruff]
line-length = 88
select = ["E", "F", "I"]   # pycodestyle, pyflakes, isort

[tool.pytest.ini_options]
testpaths = ["tests"]

Install dev dependencies separately so they do not ship in your production environment:

uv add --dev pytest ruff mypy
# or with pip:
pip install pytest ruff mypy

Weather Data Analysis Project

Apply everything you have learned by building a real weather analysis tool

Project Development

SQL & Databases

Data Analysis

Python Project Workflow: Init, Dependencies, and Debug

Initialising a new project

Managing multiple Python versions

Running scripts

Adding a new feature — end-to-end workflow

Updating dependencies

Reading error tracebacks effectively

Debugging workflow

Quick debugging with print statements

VS Code debugger

Keeping `pyproject.toml` tidy

Weather Data Analysis Project

​Initialising a new project

​Managing multiple Python versions

​Running scripts

​Adding a new feature — end-to-end workflow

​Updating dependencies

​Reading error tracebacks effectively

​Debugging workflow

​Quick debugging with print statements

​VS Code debugger

​Keeping pyproject.toml tidy

Weather Data Analysis Project

Initialising a new project

Managing multiple Python versions

Running scripts

Adding a new feature — end-to-end workflow

Updating dependencies

Reading error tracebacks effectively

Debugging workflow

Quick debugging with print statements

VS Code debugger

Keeping `pyproject.toml` tidy