Metadata-Version: 2.4
Name: psa-cli
Version: 26.1
Summary: Pure-Python CLI to list, download, and extract astral-sh python-build-standalone distributions.
Keywords: python,standalone,python-build-standalone,version-manager,cli
Author-email: Carlton Gibson <carlton.gibson@noumenal.es>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
License-File: LICENSE
Requires-Dist: sphinx>=7.0 ; extra == "docs"
Requires-Dist: furo ; extra == "docs"
Requires-Dist: zstandard>=0.22.0 ; extra == "extract"
Provides-Extra: docs
Provides-Extra: extract

# psa — Python Standalone Manager

Pure-Python CLI to list, download, and extract [astral-sh/python-build-standalone](https://github.com/astral-sh/python-build-standalone) prebuilt Python distributions.

`psa`'s job is to bootstrap Python on a system. Projects then create their venvs with the interpreter they need (`--python=python3.13`); `psa` deliberately has no project-management features.

Supported platforms:

- macOS Apple Silicon (`aarch64-apple-darwin`)
- Linux x86_64 glibc (`x86_64-unknown-linux-gnu`)

It focuses on the `install_only` / `install_only_stripped` archives, and has no mandatory dependencies beyond the standard library.

## Quick start

```bash
pip install psa-cli                       # package is psa-cli; command is psa
psa install 3.13                          # newest 3.13.x: download, extract, link
echo 'eval "$(psa shellenv)"' >> ~/.zshrc # put ~/.python/bin on PATH
python3.13 -m venv .venv                  # projects take it from there
```

`psa install` maintains symlinks in `~/.python/bin`: `python3.X` per installed minor (newest patch wins), and `python3` pointing at the highest minor — or a pinned one via `psa link --set-default 3.12`.

Or without installing:

```bash
python -m psa install 3.13
```

Optional extra for in-Python extraction of `.tar.zstd` without a zstd-capable system `tar`:

```bash
pip install "psa-cli[extract]"
```

## Layout

Base directory defaults to `~/.python` (override with `--base-dir`):

```
~/.python/
  downloads/            # raw downloaded archives
  versions/<version>/   # extracted trees
  bin/                  # managed symlinks (python3, python3.X)
  config.toml           # optional settings (default = "3.X")
```

## Documentation

Full command reference lives in `docs/` (Sphinx):

```bash
pip install -e ".[docs]"
sphinx-build -M html docs docs/_build
```

## Project structure

```
src/psa/
  cli.py        # argparse commands
  releases.py   # remote: release metadata, asset parsing, downloads
  store.py      # local: extraction, installed versions, symlinks, config
tests/          # pytest suite (offline pieces: parsing, selection, linking)
docs/           # Sphinx documentation
notes/          # design notes and history
```

## Tests

```bash
python -m pytest
```

## License

MIT

