py_env_tools

Python API and CLI for configuration-driven environment resolution and setup. Requires Python 3.10+ with no third-party runtime dependencies.

Python package (release preparation)

Version 0.1.0 is being prepared; this change does not publish it to PyPI. For local installation from this repository root:

python -m pip install .
py-env-tool --help

After the first release is published, install with python -m pip install estrellio-py-env-tools==0.1.0.

The installed py-env-tool command supports resolve-env, describe-config, resolve-python, create-venv, and install-pipx. Pass --config and --project-dir explicitly; pip installation does not create project config. For example, with an existing configuration:

py-env-tool resolve-env --config config/py_env.json --project-dir . --format json

Python integrations can use PyEnvError, resolve_env_data, and resolve_python_runtime from py_env_tools, and the existing configuration and setup helpers from py_env_tools.core. Configuration precedence remains shared config, current-platform overrides, then the sibling local config.

Repository scripts and templates

The wheel does not install the Bash/PowerShell launchers, minimal templates, or installer scripts. write-env, run-module, bootstrap Python discovery, and template installation still require the source/submodule layout. The Python CLI has its existing output contract, including AUTOSCRIPTS_* JSON keys; it is not a replacement for the shell wrappers' generic output contract.

Repository entrypoints remain scripts/py_env.sh, scripts/py_env.ps1, and scripts/install_minimal_repo.sh / .ps1. They use the host repository's config/py_env.json by default; wrappers can override PY_ENV_CONFIG_PATH. scripts/py_env_tool.py is a source launcher for py_env_tools.cli, allowing repository scripts to work before the package is installed.

See Usage, Testing, and Publishing for the supported interfaces and release checks.

Common Submodule Operations

When this repository is used under a parent repo as libs/py_env_tools, Git tracks two different states:

• the commit pinned by the parent repository
• the latest commit on this repository's own remote branch

Common commands from the parent repository root:

# Inspect the submodule state recorded by the parent repo
git submodule status
git diff --submodule=log -- libs/py_env_tools

# Reset the submodule to the commit currently pinned by the parent repo
git submodule update --init --recursive

# Move the submodule itself to the latest origin/main commit
git -C libs/py_env_tools checkout main
git -C libs/py_env_tools pull --ff-only

# Record the updated submodule pointer in the parent repo
git add libs/py_env_tools
git commit -m "Update py_env_tools submodule"

git submodule update --init --recursive does not mean "pull the latest remote changes for this submodule". It checks out the commit currently recorded by the parent repository and commonly leaves the submodule in a detached HEAD state.

Minimal Repo Template

If a new repository only needs Python environment management, it does not need the full AutoScripts wrapper layout. A minimal cross-platform setup is available in:

• templates/minimal_repo/py_env.sh
• templates/minimal_repo/py_env.ps1
• templates/minimal_repo/config/py_env.json
• templates/minimal_repo/config/requirements/default.txt

Copy py_env.sh and/or py_env.ps1 to the new repository root, copy config/py_env.json into a config/ directory, and vendor or initialize libs/py_env_tools/ in the new repository. The template entrypoints expose:

• resolve-env
• write-env
• install-pipx
• create-venv

The template keeps the existing py_env.json schema but maps environment outputs to generic names such as PY_ENV_PROJECT_DIR and PY_ENV_VENV_ROOT. resolve-env still reports those values, but write-env only persists cross-repository-safe state such as PY_BASE, PY_ENV_BOOTSTRAP_PYTHON, and PATH updates for the pipx shim directory.

py_env.json now also supports an optional top-level platforms mapping with windows, linux, and macos branches. The effective config is resolved in this order:

1. Shared config
2. platforms.<current-platform>
3. py_env_local.json

Use the shared config for machine-independent defaults, platform branches for OS-specific paths such as pythonBase, venvRoot, and pipxShimPath, and py_env_local.json for one-off machine overrides.

If the host repository keeps its public entrypoints under scripts/, use the helper installer instead of copying files manually:

bash libs/py_env_tools/scripts/install_minimal_repo.sh --repo-root . --force

.\libs\py_env_tools\scripts\install_minimal_repo.ps1 -RepoRoot . -Force

That command adapts the minimal template for the scripts/ layout and writes:

• scripts/py_env.sh
• scripts/py_env.ps1
• scripts/config/py_env.json
• scripts/config/requirements/default.txt

It is intended for repositories that only need the minimal environment management surface. If your host repo also needs run-module wrappers, keep a repository-specific py_env entry layer instead of overwriting it with the minimal template.

Tests

The submodule keeps its own pytest suite under tests/ so it can be validated without relying on the parent repository test tree.

python -m pytest -q tests

For target-platform and portable interpreter paths, see runtime resolution for standalone runners.