pepm

pepm is an experimental C++ package/environment manager for Python projects. It borrows the structured-project idea from npm, while keeping the first version small and transparent.

Build

cmake -S . -B build
cmake --build build

The executable will be at build/pepm.

Commands

pepm init [name]
pepm add requests 2.32.3
pepm remove requests
pepm use 3.12.5
pepm python 3.12.5
pepm python install 3.11.9
pepm python list
pepm python remove 3.11.9
pepm doctor
pepm install
pepm run main.py
pepm list
pepm track --port 8000
pepm track --host 0.0.0.0 --port 8000 --watch-ms 750

The PyPI package installs and uses uv as its runtime backend, so Python versions are downloaded as prebuilt managed distributions instead of compiled locally. pepm python <version> and pepm use <version> select that version, update .python-version and pepm.json, and rebuild .venv when its interpreter changes. Native packages without uv keep the pinned pyenv implementation as a compatibility fallback.

Pyenv builds most CPython releases from source. Run pepm doctor to check for Git, Make, curl, and a C compiler before installing a version. Operating-system development libraries may still be required for complete Python builds.

pepm install creates .venv from the selected pepm-managed Python and installs the packages exported to requirements.txt.

pepm run <file.py> [args...] prepares the environment and then runs Python code. It creates .venv when needed, installs requirements.txt, then runs with .venv/bin/python. Common import/package mismatches are normalized, such as cv2 or python-opencv becoming opencv-python.

pepm init [name] creates pepm.json, requirements.txt, .python-version, a starter main.py when one does not already exist, flow.toml, and .venv in the current directory. Existing main.py files are never overwritten. On a minimal system without python3, initialization bootstraps managed Python 3.12.3; otherwise it starts from the available system Python version and installs the matching managed interpreter.

flow.toml is the persistent code-understanding model. It records files, imports, functions/classes, line ranges, high-level explanations, calls, source, and rule-based line explanations. It is regenerated only when its generated content changes.

pepm track starts an animated tabbed dashboard. It shows:

• the selected Python version
• configured dependencies
• a compact main-function flow for source files
• an expandable mind map rooted at main, revealing only direct calls at each depth
• an animated per-function statement flow with editable example inputs
• project-local function execution with typed JSON arguments and captured output
• an architecture board grouped into Entry, Input, Processing, State, Output, and Infrastructure
• file roles, plain-English architecture notes, and dependency explanations
• a searchable function inspector that displays one component at a time
• detected classes/functions, line ranges, signatures, purpose, call sites, and exact source
• optional line-by-line code explanations generated from syntax and operations rather than comments
• function contracts showing parameters, output, side effects, and next project calls
• a separate git-flow tab with create, checkout, merge, abort, resolve, commit, working-tree status, branch graph, and commit timeline
• a merge-conflict tab with conflict marker reasons, browser editing for resolved content, and commit controls

While pepm track is running, the dashboard checks for saved source changes and refreshes automatically. The selected tab and function are restored after refresh whenever they still exist.

Use --no-watch to disable browser polling. The server binds to 127.0.0.1 by default; use --host 0.0.0.0 only when the dashboard must be reachable from another machine.

Packaging

The CMake install target places pepm in the selected install prefix's bin directory. Debian/Ubuntu packaging instructions and the reproducible Docker build are in packaging/README.md. A validated native-architecture package can be produced with:

docker build -f packaging/Dockerfile.deb -t pepm-deb-builder:0.3.0 .