Skip to content

Development Environment Setup

This guide walks you through setting up the development environment for this project.

Prerequisites

Quick Start

# 1. Clone the repository
git clone https://github.com/JoJo275/simple-python-boilerplate.git
cd simple-python-boilerplate

# 2. Confirm Python 3.11+ and Hatch are installed
python --version
hatch --version

# 3. Enter the Hatch-managed dev environment
hatch shell

# 4. Verify installation
spb              # Run the CLI entry point
hatch run test    # Run tests

That's it. Hatch automatically creates a virtual environment, installs the package in editable mode, and installs all dev dependencies declared in pyproject.toml.

Option B: Using pip + venv (manual)

# 1. Clone the repository
git clone https://github.com/JoJo275/simple-python-boilerplate.git
cd simple-python-boilerplate

# 2. Confirm Python 3.11+ is installed
python --version

# 3. Ensure .venv/ is in .gitignore (should already be there)
git check-ignore .venv/

# 4. Create and activate virtual environment
python -m venv .venv

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

# macOS/Linux
source .venv/bin/activate

# 5. Update pip
python -m pip install --upgrade pip

# 6. Install the package in editable mode with dev dependencies
python -m pip install -e ".[dev]"

# 7. Verify installation
spb  # Run the CLI entry point
python -m pytest  # Run tests

Detailed Setup

1. Confirm Python Installation

# Ensure Python 3.11+ is installed
python --version

2. Ensure .venv/ is Ignored

Before creating a virtual environment, make sure .venv/ is in your .gitignore:

# Check if .venv is ignored
git check-ignore .venv/

# If not ignored, add it in .gitignore file
Type the following into .gitignore:
.venv/

Your .gitignore should include:

.venv/
__pycache__/
*.egg-info/
dist/
build/
.mypy_cache/
.pytest_cache/
.ruff_cache/

3. Update pip

python -m pip install --upgrade pip

4. Virtual Environment

Always use a virtual environment to isolate project dependencies:

# Create virtual environment
python -m venv .venv

# Activate it (choose your platform)
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1

# Windows CMD:
.venv\Scripts\activate.bat

# macOS/Linux/Git Bash:
source .venv/bin/activate

Tip: Your terminal prompt should show (.venv) when activated.

5. Confirm You're in the venv

python -c "import sys; print(sys.executable); print(sys.prefix)"
python -m pip -V

6. Install Dependencies

# Install package + dev dependencies (pytest, ruff, mypy, etc.)
python -m pip install -e ".[dev]"

# Or install just the package (no dev tools)
python -m pip install -e .

The -e flag installs in "editable" mode - changes to source code take effect immediately without reinstalling.

7. Verify Installation

# Check the package is installed
python -m pip show simple-python-boilerplate

# Run the CLI
spb

# Run tests
python -m pytest

# Run linter
python -m ruff check src/

# Run type checker
python -m mypy src/

8. Helpful Commands

# Editable installs confirmation
python -m pip list --editable

# See all packages installed in the venv
python -m pip list

# Freeze list (good for reproducing exact versions)
python -m pip freeze

# See exactly what pip thinks your project requires
python -m pip show simple-python-boilerplate

Lots of other useful commands from installs are in pyproject.toml.

Project Structure

simple-python-boilerplate/
├── src/
│   └── simple_python_boilerplate/  # Main package code
│       ├── __init__.py
│       ├── _version.py             # Auto-generated by hatch-vcs
│       ├── main.py                 # CLI entry points
│       ├── cli.py                  # Argument parsing
│       ├── engine.py               # Core logic
│       ├── api.py                  # HTTP/REST (placeholder)
│       ├── py.typed                # PEP 561 type marker
│       ├── dev_tools/              # Developer utilities
│       └── sql/                    # SQL utilities
├── tests/                          # Test files
│   ├── unit/                       # Unit tests
│   └── integration/                # Integration tests
├── scripts/                        # Utility scripts
├── docs/                           # Documentation (MkDocs)
├── db/                             # Database files (schema, migrations, seeds)
├── pyproject.toml                  # Project configuration (single source of truth)
├── Taskfile.yml                    # Task runner shortcuts
└── README.md

Available Commands

Command Description
spb Run the CLI entry point
python -m pytest Run all tests
python -m pytest -v Run tests with verbose output
python -m pytest --cov Run tests with coverage report
python -m ruff check src/ Lint source code
python -m ruff format src/ Format source code
python -m mypy src/ Type check source code

IDE Setup

  1. Open the workspace file: simple-python-boilerplate.code-workspace
  2. Install recommended extensions when prompted
  3. Select the Python interpreter from .venv:
    • Ctrl+Shift+P → "Python: Select Interpreter" → Choose .venv

Recommended Extensions:

  • Python (ms-python.python)
  • Pylance (ms-python.vscode-pylance)
  • Ruff (charliermarsh.ruff)

PyCharm

  1. Open the project folder
  2. Go to Settings → Project → Python Interpreter
  3. Add interpreter → Existing environment → Select .venv/Scripts/python.exe (Windows) or .venv/bin/python (macOS/Linux)

Troubleshooting

"spb" command not found

Make sure:

  1. Virtual environment is activated (you see (.venv) in prompt)
  2. Package is installed: python -m pip install -e ".[dev]"

Import errors in IDE

  1. Ensure VS Code is using the correct Python interpreter from .venv
  2. Reload the window: Ctrl+Shift+P → "Developer: Reload Window"

Permission denied (Windows PowerShell)

If you can't activate the virtual environment:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

pip install fails

Ensure pip is up to date:

python -m pip install --upgrade pip

Next Steps