Metadata-Version: 2.4
Name: portableenv
Version: 2.0.5
Summary: A tool to create virtual environments using an embedded Python interpreter.
Home-page: https://github.com/abdulrahimpds/portableenv
Author: AbdulRahim Khan
Author-email: abdulrahimpds@gmail.com
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: virtualenv
Requires-Dist: click
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# portableenv

`portableenv` creates virtual environments from an embedded Python runtime that is cached under your user profile. Its goal is deterministic, isolated environments that do not silently drift when system Python changes.

## Key behavior

- Uses embedded CPython runtime archives from `python.org`.
- Tracks runtime identity with `implementation + version + abi + platform` (for example `cpython-3.10.9-cp310-win_amd64`).
- Writes runtime metadata for embedded runtimes and environment metadata for created environments.
- Runs a post-create health check (`doctor`) to detect ABI drift (for example `cp310` binaries inside a `cp314` env).
- Defaults to `--copies` for stronger isolation.

### Version request heuristic

- If you request a patch version (for example `3.11.5`), `portableenv` tries that exact version first, then other discovered `3.11.x` patches.
- If you request a minor version (for example `3.11`), `portableenv` probes available patch versions (`3.11.x`) and tries them in order.
- If no usable embedded `3.11.x` runtime is found, it falls back to the current system Python interpreter.
- You can still force system fallback at any time with `--allow-system-fallback`.

## Installation

```bash
pip install portableenv
```

## Usage

### Create an environment

```bash
python -m portableenv myenv
```

### Pin a specific Python version

```bash
python -m portableenv myenv -v 3.10.9
```

### Request a minor line and let portableenv choose a patch

```bash
python -m portableenv myenv -v 3.11
```

### Explicit system fallback control

```bash
python -m portableenv myenv -v 3.10.9 --allow-system-fallback
```

### Use symlinks instead of copies

```bash
python -m portableenv myenv -v 3.10.9 --symlinks
```

### Validate an environment (doctor mode)

```bash
python -m portableenv myenv --doctor
```

If ABI mismatches are found, recreate the environment with a consistent runtime.

## Notes

- Existing environments are not modified in place.
- If an embedded runtime setup fails and no fallback route is allowed/applicable, creation fails fast.

## Requirements

- Python 3.7 or higher
- `virtualenv` (installed automatically inside the selected runtime)
- Internet connection for first-time runtime and pip bootstrap downloads

## License

MIT License. See [LICENSE](LICENSE).

## Links

- [GitHub Repository](https://github.com/abdulrahimpds/portableenv)
- [PyPI Package](https://pypi.org/project/portableenv)
