Metadata-Version: 2.4
Name: estrellio-py-env-tools
Version: 0.1.0
Summary: Configuration-driven Python environment helpers for AutoScripts-style repos
Author: shade
License-Expression: MIT
Project-URL: Homepage, https://github.com/jiangnanqw12/py_env_tools
Project-URL: Repository, https://github.com/jiangnanqw12/py_env_tools
Project-URL: Issues, https://github.com/jiangnanqw12/py_env_tools/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# 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:

```console
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:

```console
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](docs/usage.md), [Testing](docs/testing.md), and
[Publishing](docs/publishing.md) 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:

```bash
# 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
bash libs/py_env_tools/scripts/install_minimal_repo.sh --repo-root . --force
```

```powershell
.\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.

```bash
python -m pytest -q tests
```

For target-platform and portable interpreter paths, see [runtime resolution for standalone runners](docs/usage.md#runtime-resolution-for-standalone-runners).
