Article 2: Development Environment Setup

Introduction

A well-configured development environment is like a craftsman's workshop—everything has its place, tools are sharp, and work flows smoothly. Through setting up environments for countless Python projects, I've learned that investing time upfront in proper configuration pays dividends throughout the project lifecycle.

This article covers setting up a professional Python development environment, from virtual environments to IDE configuration, establishing the foundation for everything we build in this series.

Development Environment Overview

Python Installation

Using pyenv for Version Management

I recommend pyenv for managing Python versions—it allows multiple versions to coexist and switch between them easily.

# Install pyenv (macOS)
brew install pyenv

# Install pyenv (Linux)
curl https://pyenv.run | bash

# Add to shell configuration (~/.zshrc or ~/.bashrc)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Restart shell
exec "$SHELL"

Installing Python Versions

# List available versions
pyenv install --list | grep "3.11"

# Install Python 3.11
pyenv install 3.11.7

# Set global default
pyenv global 3.11.7

# Set local version for a project
cd my-project
pyenv local 3.11.7  # Creates .python-version file

# Verify installation
python --version

Python Version Selection

Version

Status

Recommendation

3.9

Maintenance

Legacy projects only

3.10

Active

Good for compatibility

3.11

Active

Recommended for new projects

3.12

Active

Latest features, good for greenfield

Virtual Environments

Why Virtual Environments?

Virtual environments:

Isolate dependencies - Each project has its own packages
Ensure reproducibility - Same versions across environments
Prevent conflicts - Different projects can use different versions
Keep system Python clean - No global package pollution

Creating Virtual Environments

Using venv (Built-in)

# Create virtual environment
python -m venv venv

# Activate (macOS/Linux)
source venv/bin/activate

# Activate (Windows)
.\venv\Scripts\activate

# Deactivate
deactivate

# Verify you're in the virtual environment
which python  # Should show path in venv/

Using uv (Modern, Fast)

uv is a modern Python package installer that's significantly faster than pip:

# Install uv
pip install uv

# Create virtual environment
uv venv

# Activate
source .venv/bin/activate

# Install packages (much faster than pip)
uv pip install pytest black ruff

Virtual Environment Best Practices

# Project structure with virtual environment
my-project/
├── .venv/              # Virtual environment (don't commit)
├── .python-version     # pyenv version file
├── src/
│   └── my_project/
├── tests/
├── pyproject.toml      # Project configuration
└── requirements.txt    # Or use pyproject.toml

Always add virtual environment to .gitignore:

# Virtual environments
venv/
.venv/
ENV/

Dependency Management

requirements.txt (Traditional)

# Generate from current environment
pip freeze > requirements.txt

# Install from requirements
pip install -r requirements.txt

Example requirements.txt:

# requirements.txt
pytest>=7.4.0
black>=23.0.0
ruff>=0.1.0
mypy>=1.5.0

pyproject.toml (Modern)

The modern approach uses pyproject.toml for all project configuration:

# pyproject.toml
[project]
name = "task-manager"
version = "0.1.0"
description = "A task management CLI"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "[email protected]"}
]

dependencies = [
    "click>=8.1.0",
    "rich>=13.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
    "pytest-cov>=4.1.0",
]

[project.scripts]
task = "task_manager.cli:main"

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

Installing with pyproject.toml:

# Install project in editable mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Dependency Version Pinning

Specifier

Meaning

Use Case

>=1.0.0

Minimum version

Flexibility

==1.0.0

Exact version

Production stability

~=1.0.0

Compatible release

Balance

>=1.0.0,<2.0.0

Range

Major version lock

Project Structure

Standard Python Project Layout

task-manager/
├── src/
│   └── task_manager/         # Main package
│       ├── __init__.py
│       ├── cli.py            # Entry point
│       ├── models.py         # Data models
│       ├── storage.py        # Persistence
│       └── validators.py     # Validation logic
├── tests/
│   ├── __init__.py
│   ├── conftest.py           # pytest fixtures
│   ├── test_models.py
│   ├── test_storage.py
│   └── test_validators.py
├── docs/
│   └── index.md
├── .github/
│   └── workflows/
│       └── ci.yml
├── .venv/                    # Virtual environment
├── .gitignore
├── .python-version           # pyenv version
├── pyproject.toml            # Project configuration
├── README.md
└── LICENSE

The src Layout

I recommend the src/ layout for several reasons:

# src layout benefits:
# 1. Prevents importing from local directory during testing
# 2. Forces proper installation
# 3. Matches production import behavior

Without src/:

$ python -c "import task_manager"  # Works (but shouldn't during dev)

With src/:

$ python -c "import task_manager"  # ImportError (correct!)
$ pip install -e .
$ python -c "import task_manager"  # Works after installation

Package Initialization

# src/task_manager/__init__.py
"""Task Manager - A CLI for managing tasks."""

__version__ = "0.1.0"

from task_manager.models import Task
from task_manager.storage import TaskStorage

__all__ = ["Task", "TaskStorage", "__version__"]

IDE Configuration (VS Code)

Essential Extensions

// .vscode/extensions.json
{
    "recommendations": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "charliermarsh.ruff",
        "ms-python.black-formatter",
        "tamasfe.even-better-toml"
    ]
}

Workspace Settings

// .vscode/settings.json
{
    // Python settings
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.analysis.typeCheckingMode": "basic",
    
    // Formatting
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit"
        }
    },
    
    // Linting with Ruff
    "ruff.lint.run": "onSave",
    
    // Testing
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": [
        "tests"
    ],
    
    // Editor preferences
    "editor.rulers": [88],
    "files.trimTrailingWhitespace": true,
    "files.insertFinalNewline": true
}

Launch Configuration

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        },
        {
            "name": "Python: Task Manager CLI",
            "type": "debugpy",
            "request": "launch",
            "module": "task_manager.cli",
            "console": "integratedTerminal",
            "args": ["--help"]
        },
        {
            "name": "Python: Debug Tests",
            "type": "debugpy",
            "request": "launch",
            "module": "pytest",
            "args": ["-v", "tests/"],
            "console": "integratedTerminal"
        }
    ]
}

Environment Variables

Using .env Files

# .env (never commit this file!)
DATABASE_URL=postgresql://user:pass@localhost/db
API_KEY=your-secret-api-key
DEBUG=true
LOG_LEVEL=debug

Loading Environment Variables

# Using python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()  # Load from .env file

database_url = os.getenv("DATABASE_URL")
api_key = os.getenv("API_KEY")
debug = os.getenv("DEBUG", "false").lower() == "true"

Environment Template

Create a template for other developers:

# .env.example (commit this file)
DATABASE_URL=postgresql://user:pass@localhost/db
API_KEY=your-api-key-here
DEBUG=false
LOG_LEVEL=info

Add .env to .gitignore:

# Environment
.env
.env.local
.env.*.local

Pre-commit Hooks

Setting Up Pre-commit

Pre-commit hooks run checks before each commit:

# Install pre-commit
pip install pre-commit

# Create configuration
touch .pre-commit-config.yaml

# Install hooks
pre-commit install

# Run against all files
pre-commit run --all-files

Configuration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-merge-conflict

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: []

Pre-commit Workflow

Development Workflow

Complete Setup Script

#!/bin/bash
# setup.sh - Project setup script

set -e

echo "🔧 Setting up development environment..."

# Check Python version
python_version=$(python --version 2>&1 | cut -d' ' -f2 | cut -d'.' -f1,2)
if [[ "$python_version" < "3.11" ]]; then
    echo "❌ Python 3.11+ required. Found: $python_version"
    exit 1
fi

# Create virtual environment
echo "📦 Creating virtual environment..."
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Upgrade pip
echo "⬆️  Upgrading pip..."
pip install --upgrade pip

# Install dependencies
echo "📥 Installing dependencies..."
pip install -e ".[dev]"

# Install pre-commit hooks
echo "🪝 Installing pre-commit hooks..."
pre-commit install

# Verify setup
echo "✅ Verifying setup..."
python -c "import task_manager; print(f'Installed: task_manager v{task_manager.__version__}')"
pytest --version
black --version
ruff --version
mypy --version

echo ""
echo "✨ Setup complete! Activate the environment with:"
echo "   source .venv/bin/activate"

Makefile for Common Tasks

# Makefile
.PHONY: help install test lint format clean

help:
	@echo "Available commands:"
	@echo "  install  - Install dependencies"
	@echo "  test     - Run tests"
	@echo "  lint     - Run linter"
	@echo "  format   - Format code"
	@echo "  clean    - Remove build artifacts"

install:
	pip install -e ".[dev]"
	pre-commit install

test:
	pytest -v --cov=src/task_manager --cov-report=term-missing

lint:
	ruff check src tests
	mypy src

format:
	ruff format src tests
	ruff check --fix src tests

clean:
	rm -rf build dist *.egg-info
	rm -rf .pytest_cache .mypy_cache .ruff_cache
	find . -type d -name __pycache__ -exec rm -rf {} +
	find . -type f -name "*.pyc" -delete

Practical Exercise

Exercise 1: Complete Project Setup

# Create new project
mkdir task-manager && cd task-manager

# Initialize git
git init

# Create project structure
mkdir -p src/task_manager tests docs .github/workflows

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

# Create pyproject.toml
cat > pyproject.toml << 'EOF'
[project]
name = "task-manager"
version = "0.1.0"
description = "A task management CLI"
requires-python = ">=3.11"

dependencies = [
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

[project.scripts]
task = "task_manager.cli:main"

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
EOF

# Create package init
cat > src/task_manager/__init__.py << 'EOF'
"""Task Manager - A CLI for managing tasks."""
__version__ = "0.1.0"
EOF

# Create CLI entry point
cat > src/task_manager/cli.py << 'EOF'
"""Command line interface for Task Manager."""
import click

@click.group()
@click.version_option()
def main():
    """Task Manager - Manage your tasks from the command line."""
    pass

@main.command()
@click.argument("title")
def add(title: str):
    """Add a new task."""
    click.echo(f"Added task: {title}")

if __name__ == "__main__":
    main()
EOF

# Install in development mode
pip install -e ".[dev]"

# Verify installation
task --help

Exercise 2: Configure Development Tools

# Create .gitignore
cat > .gitignore << 'EOF'
# Virtual environment
.venv/
venv/

# Python
__pycache__/
*.pyc
*.pyo
*.egg-info/
dist/
build/

# IDE
.vscode/
.idea/

# Testing
.pytest_cache/
.coverage
htmlcov/

# Type checking
.mypy_cache/

# Environment
.env
EOF

# Create VS Code settings
mkdir -p .vscode
cat > .vscode/settings.json << 'EOF'
{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter"
    },
    "python.testing.pytestEnabled": true
}
EOF

# Create pre-commit config
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
EOF

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Test the setup
pre-commit run --all-files

Exercise 3: First Test

# Create conftest.py
cat > tests/conftest.py << 'EOF'
"""Pytest configuration and fixtures."""
import pytest

@pytest.fixture
def sample_task_data():
    """Sample task data for testing."""
    return {
        "title": "Learn Python",
        "description": "Complete the software engineering course"
    }
EOF

# Create first test
cat > tests/test_cli.py << 'EOF'
"""Tests for CLI module."""
from click.testing import CliRunner
from task_manager.cli import main

def test_cli_help():
    """Test CLI help command."""
    runner = CliRunner()
    result = runner.invoke(main, ["--help"])
    assert result.exit_code == 0
    assert "Task Manager" in result.output

def test_add_task():
    """Test adding a task."""
    runner = CliRunner()
    result = runner.invoke(main, ["add", "Test Task"])
    assert result.exit_code == 0
    assert "Added task: Test Task" in result.output
EOF

# Run tests
pytest -v

Environment Checklist

Use this checklist for new projects:

Python version installed (pyenv recommended)
Virtual environment created and activated
pyproject.toml configured
Dependencies installed (pip install -e ".[dev]")
.gitignore includes venv, cache, IDE files
VS Code settings configured
Pre-commit hooks installed
First test passing
README with setup instructions

Key Takeaways

Use virtual environments - Always isolate project dependencies
Prefer pyproject.toml - Modern, centralized configuration
Configure your IDE - Format on save, linting, testing integration
Automate with pre-commit - Catch issues before they're committed
Document the setup - Make it easy for others (and future you)

What's Next?

With your development environment ready, it's time to add quality tools. In Article 3: Code Quality Tools, we'll configure linting with Ruff, formatting with Black, and type checking with mypy to catch issues early and maintain consistent code.

This article is part of the Software Engineering 101 series.

PreviousArticle 1: Version Control with Git NextArticle 3: Code Quality Tools

Last updated 15 hours ago

hashtagIntroduction

hashtagDevelopment Environment Overview

hashtagPython Installation

hashtagUsing pyenv for Version Management

hashtagInstalling Python Versions

hashtagPython Version Selection

hashtagVirtual Environments

hashtagWhy Virtual Environments?

hashtagCreating Virtual Environments

hashtagUsing venv (Built-in)

hashtagUsing uv (Modern, Fast)

hashtagVirtual Environment Best Practices

hashtagDependency Management

hashtagrequirements.txt (Traditional)

hashtagpyproject.toml (Modern)

hashtagDependency Version Pinning

hashtagProject Structure

hashtagStandard Python Project Layout

hashtagThe src Layout

hashtagPackage Initialization

hashtagIDE Configuration (VS Code)

hashtagEssential Extensions

hashtagWorkspace Settings

hashtagLaunch Configuration

hashtagEnvironment Variables

hashtagUsing .env Files

hashtagLoading Environment Variables

hashtagEnvironment Template

hashtagPre-commit Hooks

hashtagSetting Up Pre-commit

hashtagConfiguration

hashtagPre-commit Workflow

hashtagDevelopment Workflow

hashtagComplete Setup Script

hashtagMakefile for Common Tasks

hashtagPractical Exercise

hashtagExercise 1: Complete Project Setup

hashtagExercise 2: Configure Development Tools

hashtagExercise 3: First Test

hashtagEnvironment Checklist

hashtagKey Takeaways

hashtagWhat's Next?

Introduction

Development Environment Overview

Python Installation

Using pyenv for Version Management

Installing Python Versions

Python Version Selection

Virtual Environments

Why Virtual Environments?

Creating Virtual Environments

Using venv (Built-in)

Using uv (Modern, Fast)

Virtual Environment Best Practices

Dependency Management

requirements.txt (Traditional)

pyproject.toml (Modern)

Dependency Version Pinning

Project Structure

Standard Python Project Layout

The src Layout

Package Initialization

IDE Configuration (VS Code)

Essential Extensions

Workspace Settings

Launch Configuration

Environment Variables

Using .env Files

Loading Environment Variables

Environment Template

Pre-commit Hooks

Setting Up Pre-commit

Configuration

Pre-commit Workflow

Development Workflow

Complete Setup Script

Makefile for Common Tasks

Practical Exercise

Exercise 1: Complete Project Setup

Exercise 2: Configure Development Tools

Exercise 3: First Test

Environment Checklist

Key Takeaways

What's Next?