Hygeia

Hygeia is a Python interpreter manager, built with ❤ in Rust. Its goal is to allow individual projects to specify which interpreter to use using a .python-version file, and to allow developers to easily manage and switch between interpreters in the CLI.

The previous project's name was pycors.

Python packaging situation is painful. macOS comes with Python 2.7 which is coming close to being end-of-life. Additionally, it does not include pip, the package installer. pip was only included by default with Python >= 3.4.

The install instructions for pip contains a large warning against installing it in the system interpreter.

virtualenv could be used, but it needs to be installed using pip, resulting in a chicken-and-egg situation.

Hygeia will download and compile specified versions of Python and allow switching between them easily.

The project took a lot of inspiration from pyenv, which does something similar. pyenv is written in Bash though, which prevents it from being used easily on Windows. Hygeia aims to be portable across Windows, Linux and macOS.

Requirements

Since Python interpreters are downloaded and compiled, some build tools are required.

macOS / OSX

Make sure dependencies are installed:

1. Homebrew

   brew install openssl readline sqlite3 xz zlib

2. XCode

   xcode-select --install

See the Python Developer's Guide for more information.

Linux

Please refer to pyenv's wiki for more details.

Deb-based

sudo apt-get update && sudo apt-get install --no-install-recommends make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Yum-based

yum install gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz

DNF-based

dnf install make gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz

Pacman-based

pacman -S base-devel openssl zlib

Windows

Nothing (expect Hygeia itself) is required to install a Python toolchain under Windows; pre-built binaries are used.

Installation

1. Visit the release page to download the latest precompiled version for your platform (Linux, macOS, Windows).
2. Extract to a temporary location.
3. Open a terminal and execute ./hygeia setup <SHELL> (where SHELL is one of bash, zsh or powershell). This will:
   1. copy itself to ${HYGEIA_HOME} (${HOME}/.hygeia) as a shim for Python
   2. create the file ${HYGEIA_HOME}/extra-packages-to-install.txt containing a list of Python packages to pip-install when flag --extra/-e is used with install or select commands
   3. setup ~/.<SHELL>rc to add ${HOME}/.hygeia/shims in the front of your ${PATH}
4. You can delete the downloaded archive and the extracted binary.

Compilation

As simple as cargo build!

Usage

See hygeia --help for all commands:

❯ hygeia --help
hygeia 0.1.4
Nicolas Bigaouette <[email protected]>
Control which Python toolchain to use on a directory basis.

USAGE:
    hygeia [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    autocomplete    Print to stdout an autocomplete script for the specified shell
    help            Prints this message or the help of the given subcommand(s)
    install         Install version, either from the provided version or from `.python-version`
    list            List installed Python versions
    path            Get path to active interpreter
    run             Run a binary from the installed `.python-version`
    select          Select specified Python versions to use
    setup           Setup the shim
    version         Get version of active interpreter

Initial Set Up

To set up Hygeia by installing it (and its shims) to $HYGEIA_HOME and configuring a bash shell:

hygeia setup bash

This will:

• Copy the hygeia binary to $HYGEIA_HOME/shims/;
• Create hard-links to it with Python binary names;
• Create a bash completion script in $HYGEIA_HOME/hygeia.bash-completion;
• Add $HYGEIA_HOME/shims/ to $PATH through ~/.bashrc;
• Add line sourcing $HYGEIA_HOME/hygeia.bash-completion in ~/.bashrc;
• Create the file $HYGEIA_HOME/extra-packages-to-install.txt containing a list of Python packages to pip-install when flag --extra/-e is used with install or select command.

Listing Interpreters

❯ hygeia list
+--------+---------+------------------------------------------------+
| Active | Version | Location                                       |
+--------+---------+------------------------------------------------+
|        |  3.7.1  | /Users/nbigaouette/.hygeia/installed/3.7.1/bin |
+--------+---------+------------------------------------------------+
|        |  3.7.2  | /Users/nbigaouette/.hygeia/installed/3.7.2/bin |
+--------+---------+------------------------------------------------+
|        |  3.5.6  | /Users/nbigaouette/.hygeia/installed/3.5.6/bin |
+--------+---------+------------------------------------------------+
|   ✓    |  3.6.8  | /Users/nbigaouette/.hygeia/installed/3.6.8/bin |
+--------+---------+------------------------------------------------+
|        |  3.7.2  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.15  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.10  | /usr/bin                                       |
+--------+---------+------------------------------------------------+

If the file .python-version contains a version not installed, the list reports it as active but not available:

❯ hygeia list
+--------+---------+------------------------------------------------+
| Active | Version | Location                                       |
+--------+---------+------------------------------------------------+
|   ✗    | = 3.6.8 |                 Not installed                  |
+--------+---------+------------------------------------------------+
|        |  3.7.2  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.15  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.10  | /usr/bin                                       |
+--------+---------+------------------------------------------------+

To get the active interpreter's path:

hygeia path
/Users/nbigaouette/.hygeia/installed/3.6.8/bin

To get the active interpreter's version:

hygeia version
3.6.8

Set Interpreter as Active

This will create (or overwrite) the file .python-version (in the current working directory) with the latest Semantic Versioning version compatible with 3.7.

❯ hygeia select ~3.7
❯ hygeia version
3.7.2

Note that --extra can be used with select or install command to read file $HYGEIA_HOME/extra-packages-to-install.txt and pip install all packages specified. Additionally, --extra-from can also be used to specify a different file. Both flags can be used at the same time and the content of both files will be used. Lines starting with # are ignored (as comments).

The parsing is performed by Rust's semver crate. For details about the parsing, see the Requirements section in the semver crate documentation.

Uninstall an Interpreter

Or simply delete the directory containing the installed interpreter, for example $HYGEIA_HOME/installed/3.5.6 (where $HYGEIA_HOME defaults to $HOME/.hygeia).

Obtain the list of interpreters (and their installed paths) using hygeia list.

Notes

Logging

Export the RUST_LOG environment variable to set Hygeia's log level:

export RUST_LOG=hygeia=debug

See the Rust crates log and env_logger for more information.

Python Packages

Installing a Python package can be done using pip (which will call Hygeia's shim).

numpy:

pip install numpy

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Conduct

The Rust Code of Conduct shall be respected. For escalation or moderation issues please contact Nicolas ([email protected]) instead of the Rust moderation team.