Metadata-Version: 2.4
Name: python-env-repair
Version: 0.1.0
Summary: Detect and repair console_scripts launchers of a Python environment without reinstalling packages
License-Expression: GPL-3.0-only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: python_env_repair/_launchers/LICENSE.txt
Dynamic: license-file

# python-env-repair

Detect and repair `console_scripts` launchers of a Python environment after the environment has been moved or copied, without reinstalling, downloading, or modifying any package.

Package metadata is the authority: only entry points declared in the environment's own `*.dist-info` / `*.egg-info` are considered, and an existing file is replaced only when it is a recognized wrapper for that same entry point. Standalone binaries in the scripts directory (uv, ruff, git, node, ...) are never modified or executed.

Design documents: [implementation plan](docs/implementation-plan.md), [repair design](docs/python-console-script-repair-design.md), [logging design](docs/python-console-script-repair-logging-design.md), [Ruff/ty configuration](docs/python-console-script-repair-tooling-design.md), [compatibility note](docs/compatibility.md), [implementation status](docs/implementation-status.md).

## Deployment

The utility operates on the environment of the interpreter that runs it, and it never installs anything itself. It has no runtime dependencies: the script generator is built in, and the Windows console launcher stubs are shipped inside the package (copied unmodified from distlib 0.4.3, PSF-2.0; see `python_env_repair/_launchers/`). Ways to provide it:

- install the wheel into the target environment ahead of time, or
- put `python_env_repair/` (a directory or a zip) on `PYTHONPATH` for the repair run.

## Usage

Always call the target interpreter by its absolute path, not a console script that may itself be broken:

```bash
/path/to/venv/bin/python -B -m python_env_repair detect
/path/to/venv/bin/python -B -m python_env_repair repair --dry-run --json > plan.json
/path/to/venv/bin/python -B -m python_env_repair repair
/path/to/venv/bin/python -B -m python_env_repair repair --verbose
/path/to/venv/bin/python -B -m python_env_repair repair --log-dir ./repair-logs
/path/to/venv/bin/python -B -m python_env_repair verify --json
```

`-B` stops the utility's own imports from writing bytecode. It does not sandbox package code; only explicitly configured startup checks run package code.

On Windows, after moving or copying an environment, use `--relocated` (see [Windows launchers](#windows-launchers-and-relocation-evidence)):

```powershell
C:\path\to\venv\Scripts\python.exe -B -m python_env_repair repair --dry-run --relocated
C:\path\to\venv\Scripts\python.exe -B -m python_env_repair repair --relocated
```

### Output

- stderr: phase-tagged progress (`--verbose` adds evidence and tracebacks, `--quiet` shows warnings and errors only).
- Color: logs and the text summary are colored by default, including when redirected. `NO_COLOR` (any non-empty value) or `TERM=dumb` turns it off. `--color auto` colors only terminals, `--color always` ignores `NO_COLOR`, and `--color never` disables it. JSON output and diagnostic files are never colored. On Windows, ANSI support is switched on for the console first; legacy consoles that cannot enable it get plain text.
- stdout: the final result as a text summary, or with `--json` exactly one JSON report object.
- Files: none by default. `--log-dir PATH` alone enables `events.jsonl` (DEBUG events), `manifest.json` (plan saved before the first modification) and `report.json` in a new `PATH/<UTC timestamp>-<id>/` directory. `--dry-run --log-dir` is rejected, because a dry run writes nothing.

### Verification

Default verification is structural: generated bytes, interpreter binding (Unix), execute permission, and the replacement outcome. The output then says "structural verification passed; startup not checked". To also run a CLI, approve a command for each entry explicitly:

```bash
python -B -m python_env_repair repair --verification execute --verify-command "mytool=--version" --verify-timeout 20
```

Commands run by absolute artifact path, without a shell, with no stdin, a timeout, and at most 64 KiB kept per output stream. An entry without an approved command is reported as `unverified`. There is no automatic fallback to `--help`, `--version`, or importing the entry point.

If a required check fails after writing, the original file is restored from the recovery copy, and both the write and the rollback are reported. If the rollback itself fails, the recovery copy is kept and its path is printed.

### Windows launchers and relocation evidence

The interpreter path inside a Windows `.exe` launcher is not parsed. An existing, owned launcher is `unknown` unless explicit evidence is given. Without evidence, `repair` on Windows only creates missing launchers and leaves every existing one unchanged, even when the environment was moved.

**Recommended on Windows:** whenever the environment has been moved or copied, run `repair` with `--relocated`. Missing launchers are created without the flag, but existing ones are rebuilt only with it. Launchers are regenerated only when metadata declares them and the existing file is a recognized launcher for that same entry point, so standalone binaries and unrecognized files stay untouched. Run `repair --dry-run --relocated` first to see the list.

- `--relocated`: the caller asserts the environment was moved; owned launchers are rebuilt. On Linux and macOS it changes nothing, because shebangs are inspected directly.
- `--previous-manifest PATH`: a `manifest.json` or `report.json` from an earlier run (or `{"python": ..., "console_scripts": [...]}`). A different recorded Python means rebuild. The same Python plus an unchanged hash means valid, and only hashes of entries that run reported as `repaired` or `valid` count. Paths in the file are never used as write targets.

Nothing is saved automatically to help later runs. Keep `report.json` (from a `--log-dir` run) if you want future evidence.

### Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Command completed. Finding candidates in `detect`/`--dry-run` is not a failure; read the report. |
| 1 | A repair or required verification failed or did not complete (`verify` also fails on `unverified` entries). |
| 2 | Invalid or conflicting arguments. |
| 3 | Run-level failure: environment not identifiable, environment busy (another repair holds the lock), requested diagnostics could not be written. |
| 130 | Interrupted. |

Priority when several apply: 130, then 3, then 1.

## Library use

```python
from python_env_repair import Operation, RunOptions, run

report = run(RunOptions(operation=Operation.DETECT))
print(report.exit_code, [(r.script.name, r.overall_status.value) for r in report.results])
```

`run()` does not configure logging. Events go to the `python_env_repair.*` loggers, which have only a `NullHandler` unless the host attaches one.

## Known limitations

- Launcher repair is not full environment relocation. `pyvenv.cfg`, `.pth` files, `.egg-link`, package configuration, and native dependencies are out of scope. Python documents venvs as non-portable.
- Regenerated scripts are not written back to `RECORD`, so their recorded hash can go stale. Validity never depends on the recorded hash.
- Unsupported wrapper forms (for example `#!/usr/bin/env python`, relocatable `$(dirname ...)` wrappers, legacy Windows `-script.py` sidecar layouts) are reported as `unknown` and left unchanged.
- pip/setuptools installer aliases (`pip`, `pipX`, `pipX.Y`, `easy_install-X.Y`) follow pip's naming rules. Missing aliases are not created, because installers may omit them on purpose.
- Repairs run one at a time. Replacing several files is not one atomic transaction, and recovery after a machine crash is not provided.
- The lock only coordinates instances of this utility, not package installers or other Python processes. Running processes are never terminated.
- Native validation has been run on Linux only; see [implementation status](docs/implementation-status.md).

## License

GPL-3.0-only; see [LICENSE](LICENSE). The Windows launcher stubs in `python_env_repair/_launchers/` are copied from distlib and keep their PSF-2.0 license ([LICENSE.txt](python_env_repair/_launchers/LICENSE.txt)).

## Development

```bash
python -m ruff check python_env_repair tests
python -m ruff format --check python_env_repair tests
python -m ty check --python <dev-python> python_env_repair tests
python -B -m pytest tests
```

Install with `pip install -e . --group dev` (pip 25.1 or newer). Development tools are listed without version constraints in `[dependency-groups]` in `pyproject.toml`, so the latest releases are installed. `distlib` is a test-only dependency: `tests/test_generator.py` checks that the built-in generator's output is byte-for-byte identical to distlib's, and is skipped when distlib is not installed. The check that the vendored stubs equal distlib's files runs only against distlib 0.4.3, the stubs' source release.
