Skip to main content

Development Setup

Development Setup

Python 3.11+

Prepare an editable scanner environment with pytest, Ruff, Black, pre-commit, and packaging tools.

Commandpython -m pip install -e ".[dev]"

Category

Developer Guide

Quick Command

create venv -> install dev tools -> enable hooks
editable installpytestRuffBlackpre-commit
Package Python
3.11 or newer
Standard Dev Runtime
Python 3.14
Install Mode
Editable
Optional Helper
GNU Make

Goal​

Install the active checkout with its dev dependency group. A runtime-only pip install -e . does not install the quality tools used by this contributor workflow.

Requirements

Requirements

Python 3.11+

Required
The package supports Python 3.11 or newer; Python 3.14 is the standard development and container runtime.

pip and venv

Required
Use an isolated interpreter and install through python -m pip.

Git

Required
Required for source control and the pre-commit hook workflow.

GNU Make

Optional
Provides repeatable setup, quality, Docker, and Compose targets.

Docker

Optional
Required only for container and Compose validation.

Manual Setup

Create and install
bash
python -m venv venv

# Windows PowerShell

venv\Scripts\Activate.ps1

# Linux or macOS

# source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Add the docs extra only when working with the repository's MkDocs source: python -m pip install -e ".[dev,docs]".

Makefile Setup

Setup helpers
bash
make venv
make upgrade-pip
make install-dev

# Combined environment setup and Git-hook installation

make setup

The Make workflow expects the repository's conventional venv/ directory.

Pre-Commit Workflow

The scanner hook configuration runs Ruff fixes, Ruff formatting, Black, trailing-whitespace cleanup, and final-newline correction. Ruff and Black use their project policies from pyproject.toml.

Install and run hooks
bash
make pre-commit-install-hooks
make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Verify the Environment

Before You Begin

  • Python is supportedRequired

    python --version reports a supported interpreter.

  • Editable CLI resolvesRequired

    path-header-scanner --help loads from the selected environment.

  • Quality tools resolveRequired

    pytest, Ruff, Black, and pre-commit run through python -m.

  • Scanner safety remains explicitRequired

    Use preview or --dry-run against temporary targets before validating --apply.

Environment check
bash
python --version
python -m pip show path-header-scanner
path-header-scanner --help
python -m pytest --version
python -m ruff --version
python -m black --version
python -m pre_commit --version

Related Commands

Commands commonly used together with this command.

Testing

Validate scanning and language behavior.