Development Setup

🚀Development Setup

Python 3.14+

Prepare an isolated editable installation for changing and testing Custy itself.

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

📦Category

Developer Guide

🚀Quick Command

create venv -> install dev tools -> verify

---

editable installpytestRuffBlackpre-commit

---

🐍

Required Python

3.14 or newer

📦

Install Mode

Editable

📁

Environment

venv recommended

🚀

Optional Helper

GNU Make

Goal

Use an isolated environment whose custy executable points to the working source checkout. Editable installation means a Python source edit is available to the next invocation without rebuilding or reinstalling the package.

---

Requirements

📌Requirements

Python 3.14+

Required

The current package metadata requires Python 3.14 or newer.

Git

Required

The application and its tests exercise repository, tag, commit, branch, and remote behavior.

pip

Required

Install through the selected virtual-environment interpreter.

Virtual Environment

Recommended

Use the repository's conventional venv directory for predictable Make and command resolution.

GNU Make

Optional

Use the repository helpers for setup and quality checks; every essential action also has a direct Python command.

Docker

Optional

Use the development image or Compose service when native Python setup is not appropriate.

---

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]"

The dev dependency group installs pytest and coverage, Ruff, Black, build and publishing tools, pre-commit, and Commitizen. Add docs only when working with the Custy repository's legacy MkDocs source: python -m pip install -e ".[dev,docs]".

---

Makefile Setup

The repository Makefile expects a venv/ environment and invokes its Python and pip executables directly.

Equivalent setup helpers

bash

make venv
make upgrade-pip
make install-dev

# Or run the combined setup, including docs and pre-commit

make setup

Run make help-local to review the active local helper groups before using less familiar targets.

---

Pre-Commit Workflow

The Make helpers invoke pre-commit through the repository's venv/ Python interpreter. Install the Git hook once, validate its configuration after an edit, and choose either staged-file or all-file checks for daily work.

Pre-commit setup and checks

bash

# Install the Git hook and its isolated hook environments
make pre-commit-install-hooks

# Validate .pre-commit-config.yaml

make pre-commit-validate

# Check files currently staged for commit

make pre-commit-run-staged

# Check every tracked repository file

make pre-commit-run

⚠️Reserve refresh for intentional hook upgrades

make pre-commit-refresh runs autoupdate, clears cached hook environments, reinstalls the hook environments, and runs every hook against all files. It can change .pre-commit-config.yaml and active source files, and may require network access. Review and validate the resulting diff before keeping it.

---

Verify the Environment

📌Before You Begin

• Python is supportedRequired

  python --version reports Python 3.14 or newer.

• Custy resolves from the environmentRequired

  custy --help renders from the editable installation.

• The module entry point worksRequired

  python -m app --help distinguishes application issues from executable PATH issues.

• Developer tools are installedRequired

  pytest, Ruff, Black, and pre-commit can be invoked through python -m.

Environment check

bash

python --version
python -m pip show custy
custy --version
custy --help
python -m app --help
python -m pytest --version
python -m ruff --version
python -m black --version
python -m pre_commit --version

---

⚠️Use the environment executable in automation

Activating a virtual environment is convenient for an interactive shell, but scripts and diagnostics are more predictable when they invoke the selected environment's Python directly, such as venv\Scripts\python.exe on Windows.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Testing

Run the smallest useful test set, then the broader checks.

Installation

Compare contributor setup with end-user installation methods.

Docker

Use the repository's container development path.

Contributing

Prepare a reviewable change from scope through handoff.