Home

Awesome

<div align="center">

asdf-pyapp Build Lint

A generic Python Application plugin the asdf version manager.

</div>

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

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.

AppCommand to add PluginNotes
ansibleASDF_PYAPP_INCLUDE_DEPS=1 asdf plugin add ansible https://github.com/amrox/asdf-pyapp.git(info)
awscliasdf plugin add awscli https://github.com/amrox/asdf-pyapp.git
awsebcliasdf plugin add awsebcli https://github.com/amrox/asdf-pyapp.git
aws-sam-cliasdf plugin add aws-sam-cli https://github.com/amrox/asdf-pyapp.git
aws-ssm-toolsasdf plugin add aws-ssm-tools https://github.com/amrox/asdf-pyapp.git
blackasdf plugin add black https://github.com/amrox/asdf-pyapp.git
bpythonasdf plugin add bpython https://github.com/amrox/asdf-pyapp.git
conanasdf plugin add conan https://github.com/amrox/asdf-pyapp.git
cowsayasdf plugin add cowsay https://github.com/amrox/asdf-pyapp.git
dbtASDF_PYAPP_INCLUDE_DEPS=1 asdf plugin add dbt https://github.com/amrox/asdf-pyapp.git(info)
doitasdf plugin add doit https://github.com/amrox/asdf-pyapp.git
flake8asdf plugin add flake8 https://github.com/amrox/asdf-pyapp.git
hyasdf plugin add hy https://github.com/amrox/asdf-pyapp.gitThe latest stable version of hy (0.20.0 atm) requires python > 3.8
mesonasdf plugin add meson https://github.com/amrox/asdf-pyapp.git
mypyasdf plugin add mypy https://github.com/amrox/asdf-pyapp.git
pipenvasdf plugin add pipenv https://github.com/amrox/asdf-pyapp.git
pre-commitasdf plugin add pre-commit https://github.com/amrox/asdf-pyapp.git
saltasdf plugin add salt https://github.com/amrox/asdf-pyapp.git
sphinxasdf plugin add sphinx https://github.com/amrox/asdf-pyapp.git
yawssoasdf plugin add sphinx https://github.com/amrox/asdf-pyapp.git
youtube-dlasdf 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 3.0@3.9.1

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 3.0@3.9.1
conan 1.36.0@3.8.5

Configuration

Environment Variables

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