direnv-python-project recipe

Personal direnv layout recipe (layout pyproject) that wraps stdlib layout python and one-shot bootstraps a Python project to my preferences.

Install

mkdir -p ~/.config/direnv/lib
ln -sf /absolute/path/to/slinkp-pyproject-recipe/pyproject.sh ~/.config/direnv/lib/pyproject.sh

The lib resolves templates via the real path of that symlink, so keep the clone where the link points.

Usage

In a project directory:

echo 'layout pyproject' > .envrc   # or: layout pyproject python3.14
direnv allow

Every load

• git init . if the directory is not already a git work tree (runs before anything else)
• Stdlib layout python behavior (venv under .direnv/python-$version, on PATH)
• Upgrade pip when the venv was just created
• PATH_add scripts (so freeze-requirements / lint work after bootstrap)
• On the first bootstrap, install githooks/pre-commit as the repository's Git hooks path after any initial skeleton commit

One-shot bootstrap (no .direnv/pyproject-bootstrapped marker)

Scaffold missing files only (STDERR warning per skip; never overwrite):

• requirements-minimal.txt (seed lint/test/LSP deps + workflow comment)
• pyproject.toml (Black / flake8 / mypy tool config only)
• README.md, .gitignore, scripts/freeze-requirements, scripts/lint, githooks/pre-commit

Then sync deps:

1. No requirements.txt: pip install -r requirements-minimal.txt → pip freeze > requirements.txt
2. Has requirements.txt: install lockfile → if minimal exists, install minimal + freeze (catch forgotten pins); if minimal was removed, warn and skip that pair

Write marker .direnv/pyproject-bootstrapped (UTC timestamp + recipe URL). Fresh clones lack .direnv/, so they bootstrap again and install.

On the initial bootstrap, only files newly created by the scaffold (including a newly generated requirements.txt) are added. This automatic commit is made only when this invocation just initialized the repository and it has no commits. Otherwise, a notice is printed to STDERR and the files are left unstaged.

After the marker exists: no scaffold, no auto-install/freeze. Missing files are assumed intentional.

Day-to-day deps

1. Edit requirements-minimal.txt (unversioned)
2. pip install -r requirements-minimal.txt
3. freeze-requirements → regenerates requirements.txt from the project venv
4. lint → runs Black, flake8, optional secrets scanners, and mypy
5. Commits run lint --check through githooks/pre-commit; bypass with git commit --no-verify

Likely follow-ups

Parked for later (no design detail yet):

• Wrapper script to standardize how tests are run
• Rules/conventions files so agents do things my way