Skip to content

A generic Python Application plugin the asdf version manager.

License

Notifications You must be signed in to change notification settings

amrox/asdf-pyapp

Repository files navigation

asdf-pyapp Build Lint

A generic Python Application plugin the asdf version manager.

What is a "Python Application"?

For purposes of this plugin, a Python Application is program that happens to be written in Python, but otherwise behaves like a regular command-line tool. The term "Python Application" comes from pipx.

Examples of Python Applications are awscli and conan. See below for more compatible applications.

Dependencies

  • python/python3 >= 3.6 with pip and venv
  • OR asdf-python installed

Install

Plugin:

asdf plugin add <python app> https://github.com/amrox/asdf-pyapp.git
# for example
asdf plugin add cowsay https://github.com/amrox/asdf-pyapp.git

Example using cowsay:

# Show all installable versions
asdf list-all cowsay

# Install specific version
asdf install cowsay latest

# Set a version globally (on your ~/.tool-versions file)
asdf global cowsay latest

# Now cowsay commands are available
cowsay "Hi!"

Compatible Python Applications

This is a non-exhaustive list of Python Applications that work with this plugin.

App Command to add Plugin Notes
ansible ASDF_PYAPP_INCLUDE_DEPS=1 asdf plugin add ansible https://github.com/amrox/asdf-pyapp.git (info)
awscli asdf plugin add awscli https://github.com/amrox/asdf-pyapp.git
awsebcli asdf plugin add awsebcli https://github.com/amrox/asdf-pyapp.git
aws-sam-cli asdf plugin add aws-sam-cli https://github.com/amrox/asdf-pyapp.git
aws-ssm-tools asdf plugin add aws-ssm-tools https://github.com/amrox/asdf-pyapp.git
black asdf plugin add black https://github.com/amrox/asdf-pyapp.git
bpython asdf plugin add bpython https://github.com/amrox/asdf-pyapp.git
conan asdf plugin add conan https://github.com/amrox/asdf-pyapp.git
cowsay asdf plugin add cowsay https://github.com/amrox/asdf-pyapp.git
dbt ASDF_PYAPP_INCLUDE_DEPS=1 asdf plugin add dbt https://github.com/amrox/asdf-pyapp.git (info)
doit asdf plugin add doit https://github.com/amrox/asdf-pyapp.git
flake8 asdf plugin add flake8 https://github.com/amrox/asdf-pyapp.git
hy asdf plugin add hy https://github.com/amrox/asdf-pyapp.git The latest stable version of hy (0.20.0 atm) requires python > 3.8
meson asdf plugin add meson https://github.com/amrox/asdf-pyapp.git
mypy asdf plugin add mypy https://github.com/amrox/asdf-pyapp.git
pipenv asdf plugin add pipenv https://github.com/amrox/asdf-pyapp.git
pre-commit asdf plugin add pre-commit https://github.com/amrox/asdf-pyapp.git
salt asdf plugin add salt https://github.com/amrox/asdf-pyapp.git
sphinx asdf plugin add sphinx https://github.com/amrox/asdf-pyapp.git
yawsso asdf plugin add sphinx https://github.com/amrox/asdf-pyapp.git
youtube-dl asdf plugin add sphinx https://github.com/amrox/asdf-pyapp.git

Check asdf readme for more instructions on how to install & manage versions.

How it Works

asdf-pyapp is a lot more complex than most asdf plugins since it's designed to work with generic Python Applications, and challenges that come with Python itself.

asdf-pyapp uses the same technique as asdf-hashicorp to use a single plugin for multiple tools.

When installing a tool, asdf-pyapp creates a fresh virtual environment and pip-installs the package matching the plugin name. Then it uses pipx under the hood to extract the entrypoints for the package exposes them to asdf.

Python Resolution

To run Python Applications, you need Python:

  1. If ASDF_PYAPP_DEFAULT_PYTHON_PATH is set - use it
  2. Else if the asdf-python plugin is installed - use the global python3**.
  3. Finally, just use python3 in our path.

** We use the global python3 to avoid picking up local python versions inside projects, which would result in inconsistent tool installations. If you want to install a tool with a specific version of Python see the following section on asdf-python Integration.

asdf-python Integration (Experimental)

Here we color outside the lines a bit :)

asdf-python supports installing a Python App with a specific Python version using a special syntax. This feature requires the asdf-python plugin to be installed.

The general form is:

asdf <app> install <app-version>@<python-version>

For example, to install cowsay 3.0 with Python 3.9.1:

asdf cowsay install [email protected]

Python Apps with different python versions and python itself can all happily co-exist in the same project. For example, take this .tool-versions:

python 3.8.5
awscli 1.19.93
cowsay [email protected]
conan [email protected]
  • awscli will be installed with the global Python (see Python Resolution), in an isolated virtual environment
  • Python 3.9.1 will be installed, and then cowsay will be installed using that Python (in a venv)
  • conan will be installed with Python 3.8.5, but isolated from the project's Python, which is also 3.8.5.

Configuration

Environment Variables

  • ASDF_PYAPP_INCLUDE_DEPS - when set to 1, this plugin will consider the executables of the dependencies of the installed package as well. For example, when installing ansible, the ansible command actually comes from its depency, ansible-core. This is the same as Pipx's --include-deps flag.
  • ASDF_PYAPP_DEFAULT_PYTHON_PATH - Path to a python/python3 binary this plugin should use. Default is unset. See Python Resolution section for more details.
  • ASDF_PYAPP_VENV_COPY_MODE:
    • 0: (default) Add --copies flag to venvs created with a specific Python version. Symlinks otherwise.
    • 1: Prefer --copies whenever possible (--copies does not work with /usr/bin/python3 on macOS).
  • ASDF_PYAPP_DEBUG - Set to 1 for additional logging

Background and Inspiration

asdf-pyapp was inspired by asdf-hashicorp and pipx - which is also used under the hood. Big thanks to the creators, contributors, and maintainers of both these projects.

Contributing

Contributions of any kind welcome! See the contributing guide.

Thanks goes to these contributors!

License

See LICENSE © Andy Mroczkowski

About

A generic Python Application plugin the asdf version manager.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •