Metadata-Version: 2.4
Name: ducktools-pytui
Version: 0.2.6
Summary: A TUI for managing Python runtimes and installs
Author: David C Ellis
Project-URL: Homepage, https://github.com/davidcellis/ducktools-pytui
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: License :: OSI Approved :: MIT License
Requires-Python: >=3.8.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ducktools-classbuilder>=0.8.3
Requires-Dist: ducktools-pythonfinder>=0.8.6
Requires-Dist: ducktools-lazyimporter>=0.7.3
Requires-Dist: textual>=3.2.0
Requires-Dist: shellingham~=1.5
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Dynamic: license-file

# Ducktools: PyTUI #

A terminal based user interface for managing Python installs and virtual environments.

## Usage ##

The easiest way to install ducktools.pytui is as a tool from PyPI using `uv` or `pipx`.

`uv tool install ducktools-pytui` or `pipx install ducktools-pytui`

Run with `pytui` or `ducktools-pytui`.

There is also now a zipapp available on
[the releases page](https://github.com/DavidCEllis/ducktools-pytui/releases/latest)
and should be usable as long as you have Python 3.8 or newer.

## Example ##

![screenshot showing ducktools-pytui displaying a list of venvs and runtimes](images/pytui_menu.png)

## Features ##

* List Python Virtual Environments relative to the current folder
* List Python Runtimes discovered by [ducktools-pythonfinder](https://github.com/DavidCEllis/ducktools-pythonfinder)
* Launch a Terminal with a selected venv activated
  * Currently only 'tested' with bash (and limited git bash on Windows), zsh (on macos), powershell and cmd
  * Other shells will almost certainly break the environment variable changes
  * This isn't the standard `activate` script, as it puts PyTUI in the background and launches a new shell
  * Use `exit` to close the shell and return to PyTUI
* Launch a REPL with the selected venv
* Launch a REPL with the selected runtime
* List installed packages in a venv (Python 3.9 or later)
* Create a venv from a specific runtime in the working directory or a global folder (Python 3.4 or later)
* Delete a selected venv
* Install a runtime (Requires either the Windows Python Manager or UV to be available)
* Uninstall a runtime (Only those managed by the Windows Python Manager or UV)

### Notes on Defaults ###

* venvs are created with `--upgrade-deps` where it exists
  * If you don't need `pip` in your virtualenv, change the config for `include_pip` to `false`
  * This will make venv creation **much** faster, but means `python -m pip` won't work, which is
    why it is not the default
* venvs are searched for based on the current working directory and parent directories.
* 'Global' venvs are created in a ducktools specific folder

## Basic Configuration ##

Some configuration is available by editing the config.json file located here:

* Windows: `%LOCALAPPDATA%\ducktools\pytui\config.json`
* Linux/Mac/Other: `~/.config/ducktools/pytui/config.json`

### Config Values ###
* `venv_search_mode` - Where to search for VEnv folders
  * `"cwd"` - Search in the working directory only
  * `"parents"` - Search in the working directory and each parent folder (default)
  * `"recursive"` - Search in the working directory and subfolders recursively
  * `"recursive_parents"` - Combine the "recursive" and "parents" options (only the CWD is recursively searched)
* `include_pip` - Whether to include `pip` (and `setuptools` where appropriate) in created VEnvs (default: `True`)
* `latest_pip` - Download the latest `pip` for Python versions where it is available (default: `True`)
* `global_venv_folder` - The folder to use for global pytui venvs, `~/.local/share/ducktools/pytui/venvs` by default

### Possible Extras ###

* Support other common shells
* Highlight broken venvs where the base install no longer exists

### Not Planned ###

* Handle PEP-723 inline scripts
  * `ducktools-env` is my project for managing these
  * Potentially that could gain a TUI, but I'm not sure I'd want to merge the two things
* Handle Conda environments
  * Conda environments are a completely separate ecosystem,
    while everything this supports uses the standard PyPI ecosystem
  * Supporting Conda would basically require a whole separate parallel set of commands
* Manage `ducktools-pytui` specific runtimes
  * I don't want to add *yet another* place Python can be installed
  * `ducktools-pytui` is intended to help manage the chaos of Python runtime installs and environments,
    not add a new dimension to it
