Python Project Workflow

What You'll Learn

How to organize a Python project from scratch so it's easy to share, maintain, and run on any machine.

A Clean Project Layout

For a typical script or small project:

my-project/
├── venv/                  ← virtual environment (not committed to git)
├── src/
│   └── my_script.py       ← main code
├── tests/
│   └── test_my_script.py  ← tests
├── requirements.txt       ← packages this project needs
├── .gitignore             ← files git should ignore
└── README.md              ← what the project does and how to run it

For a larger project with multiple modules:

my-project/
├── venv/
├── myapp/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   └── utils.py
├── tests/
│   └── test_main.py
├── requirements.txt
├── pyproject.toml         ← modern project metadata
└── README.md

Step-by-Step: Starting a New Project

# 1. Create project directory
mkdir my-project
cd my-project

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Create project structure
mkdir -p src tests
touch src/main.py requirements.txt README.md .gitignore

# 4. Initialize git
git init
echo "venv/" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore

# 5. Install your first dependency
pip install requests
pip freeze > requirements.txt

The Standard .gitignore for Python

# Virtual environment
venv/
.venv/
env/

# Python cache
__pycache__/
*.pyc
*.pyo
*.pyd

# Distribution
dist/
build/
*.egg-info/

# IDE files
.vscode/
.idea/
*.swp

# Environment variables
.env

Writing a README

Every project needs a README that answers:

# Project Name

What does this project do in one sentence?

## Requirements

- Python 3.11+

## Setup

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Usage

python3 src/main.py --help
python3 src/main.py input.csv

What It Does

Step-by-step description of what the script does.

## The Development Cycle

1. Write a small piece of code ↓
2. Run it and observe the output ↓
3. Fix errors or adjust logic ↓
4. Add a test if it's complex ↓
5. Commit to git ↓ Repeat

Keep each step small. Don't write 200 lines before running.

## Running Your Script

```bash
# Basic
python3 src/main.py

# With arguments
python3 src/main.py --input data.csv --verbose

# As a module (useful when code is in a package)
python3 -m myapp.main

Checking Code Quality

Before sharing your code, run these:

# Check for syntax errors without running
python3 -m py_compile src/main.py

# Auto-format code (install first: pip install black)
black src/

# Check for common issues (install first: pip install ruff)
ruff check src/

# Run type checks (install first: pip install mypy)
mypy src/

requirements.txt vs pyproject.toml

File	Purpose	When to Use
requirements.txt	Simple list of packages	Scripts, small projects
pyproject.toml	Modern project metadata + deps	Libraries, larger apps

For most scripts and automation, requirements.txt is all you need.

Quick Workflow Commands

# Start working on existing project
cd my-project
source venv/bin/activate

# Install new package and save it
pip install httpx
pip freeze > requirements.txt

# Run script
python3 src/main.py

# Check and commit
python3 -m py_compile src/main.py
git add -A
git commit -m "Add main script"

# Done for the day
deactivate

Common Mistakes

Mistake	Fix
Committing venv/	Add to .gitignore
No requirements.txt	Run pip freeze > requirements.txt
Hardcoded paths (/home/alice/data)	Use pathlib.Path or argparse
No README	Write at least setup + usage

What's Next

→ Lesson 5: Reading Python Errors