gjvc-python-bootstrap

---

synopsis

This is a template Python 3.x (3.13 by default, change it in bin/settings) project for getting a new idea working quickly without wasting time on environmental setup. The intention is save you time during the first 10 hours and days, not the first 10 months or years.

assumptions

• You are running on Linux / UNIX.
• That you are using Python 3.13 from somewhere in your ${PATH} environment variable (set in bin/settings)

quick start

git clone https://github.com/gjvc/gjvc-python-bootstrap.git
bin/dev-init
bin/app-main --help

components

pipdeptree creates the deptree files, allowing for easy understanding of the package dependency hierarchy. It is required and must not be removed. cmd2 and jurigged make for a quietly powerful combination when creating command-shell driven applications. jurigged automatically reloads .py files during execution, in practice between commands being issued at the cmd2 prompt. This reduces the edit/test cycle time.

managing dependencies

The essential packages required by a basic environment are listed at etc/pip/3.13/bootstrap:

etc/pip/3.13/bootstrap

jurigged
pipdeptree
pyright
pytest
pyyaml

The root packages are listed at etc/pip/3.13/root in a flat list:

etc/pip/3.13/root

cmd2==3.2.0
jurigged==0.6.1
pg8000==1.31.5
pipdeptree==2.30.0
psutil==7.2.2
pyright==1.1.408
pytest==9.0.2
PyYAML==6.0.3

The complete set of dependencies is listed, in an indented tree, at etc/pip/3.13/deptree. This is created by pipdeptree:

etc/pip/3.13/deptree

click==8.3.1
cmd2==3.2.0
  pyperclip==1.11.0
  rich==14.3.2
    markdown-it-py==4.0.0
      mdurl==0.1.2
    Pygments==2.19.2
  rich-argparse==1.7.2
    rich==14.3.2
      markdown-it-py==4.0.0
        mdurl==0.1.2
      Pygments==2.19.2
jurigged==0.6.1
  blessed==1.30.0
    wcwidth==0.6.0
  codefind==0.1.7
  ovld==0.5.14
  watchdog==6.0.0
pg8000==1.31.5
  python-dateutil==2.9.0.post0
    six==1.17.0
  scramp==1.4.8
    asn1crypto==1.5.1
pipdeptree==2.30.0
  packaging==26.0
  pip==26.0.1
psutil==7.2.2
pyright==1.1.408
  nodeenv==1.10.0
  typing_extensions==4.15.0
pytest==9.0.2
  iniconfig==2.3.0
  packaging==26.0
  pluggy==1.6.0
  Pygments==2.19.2
PyYAML==6.0.3

adding a package

bin/venv-pip3 install mypy
bin/dev-init

removing a package

bin/venv-pip3 remove mypy
bin/dev-init

bin/dev-init regenerates the root and deptree files from the contents of the .venv/ directory.

project layout

path	purpose
bin/app-main	application entry point (calls src/python/main/app/main/main.py)
bin/app-tests	run the test suite
bin/dev-init	create / recreate .venv/ from requirements
bin/dev-clean	clean the workspace [1]
bin/venv-python3	set environment and run .venv/bin/python3
bin/venv-pip3	set environment and run .venv/bin/pip3
bin/venv-bin	run arbitrary executables from .venv/bin/
src/python/main/	source files for application
src/python/test/	source files for tests

[1] removes .pyc files and __pycache__ directories by default. If the environment variable CLEAN_ALL is set to 1, the .pip/, .venv/ directories are also removed.

The naming conventions across bin/ should be clear enough: app-* for entry points, dev-* for lifecycle, venv-* for plumbing.

As an example to be followed, bin/venv-pip3 and bin/venv-python3 optionally pass additional arguments based on the JURIGGED environment variable, enforcing uniform execution within the .venv/ context.

bin/app-main has the option to pass additional environment variables as required.

requirement files

Located under etc/pip/3.13/:

file	purpose
bootstrap	minimal packages needed to create the venv itself
root	top-level project dependencies (what you edit)
deptree	full resolved dependency tree (generated by dev-init)
pylock.toml	lock file for reproducible installs

configuration

Where possible, configuration lives in pyproject.toml to avoid littering the project root.

alternative tooling / approaches

This use of pip, pipdeptree, and venv is the minimal-but-complete set of tools required to manage a Python virtual environment. Other tools exist to do this job, and they may well be faster, do more, and may be required, depending on the scale of project you are managing. For instance, if you are a package maintainer you may wish to test on multiple versions of Python 3, and poetry or uv will help you do so. On the other hand, if you only have to maintain your personal application, and you have locally-installed versions of python on which you can rely, the approach presented here may well suit you better without having to learn more expansive tooling.

tool	strengths
poetry
uv	very fast venv creation and package management
pyenv
pipx

possible future directions

• different project setups in different branches for the following project types
  • django
  • fastapi
  • jupyter

---

© George Cox, 2020–2026