_pipx

#compdef pipx

# -----------------------------------------------------------------------------
#
# Copyright 2020, The zsh-completions Authors.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# * Neither the name of que nor the names of its
#   contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#
# -----------------------------------------------------------------------------
#
# pipxproject/pipx: Install and Run Python Applications in Isolated Environments
# https://github.com/pipxproject/pipx
#
# $ pipx --version
# 0.15.6.0.dev0
#
# -----------------------------------------------------------------------------

# # Run something, muting output or redirecting it to the debug stream
# # depending on the value of _ARC_DEBUG.
# # If ARGCOMPLETE_USE_TEMPFILES is set, use tempfiles for IPC.
# __python_argcomplete_run() {
#     if [[ -z "${ARGCOMPLETE_USE_TEMPFILES-}" ]]; then
#         __python_argcomplete_run_inner "$@"
#         return
#     fi
#     local tmpfile="$(mktemp)"
#     _ARGCOMPLETE_STDOUT_FILENAME="$tmpfile" __python_argcomplete_run_inner "$@"
#     local code=$?
#     cat "$tmpfile"
#     rm "$tmpfile"
#     return $code
# }
# 
# __python_argcomplete_run_inner() {
#     if [[ -z "${_ARC_DEBUG-}" ]]; then
#         "$@" 8>&1 9>&2 1>/dev/null 2>&1
#     else
#         "$@" 8>&1 9>&2 1>&9 2>&1
#     fi
# }
# 
# _python_argcomplete() {
#     local IFS=$'\013'
#     local SUPPRESS_SPACE=0
#     if compopt +o nospace 2> /dev/null; then
#         SUPPRESS_SPACE=1
#     fi
#     COMPREPLY=( $(IFS="$IFS" \
#                   COMP_LINE="$COMP_LINE" \
#                   COMP_POINT="$COMP_POINT" \
#                   COMP_TYPE="$COMP_TYPE" \
#                   _ARGCOMPLETE_COMP_WORDBREAKS="$COMP_WORDBREAKS" \
#                   _ARGCOMPLETE=1 \
#                   _ARGCOMPLETE_SUPPRESS_SPACE=$SUPPRESS_SPACE \
#                   __python_argcomplete_run "$1") )
#     if [[ $? != 0 ]]; then
#         unset COMPREPLY
#     elif [[ $SUPPRESS_SPACE == 1 ]] && [[ "${COMPREPLY-}" =~ [=/:]$ ]]; then
#         compopt -o nospace
#     fi
# }
# complete -o nospace -o default -o bashdefault -F _python_argcomplete pipx
#
# -----------------------------------------------------------------------------

function _pipx() {
  local context curcontext=$curcontext state line expl ret=1
  declare -A opt_args

  local -a commands
  commands=(
    "install:Install a package"
    "inject:Install packages into an existing Virtual Environment"
    "upgrade:Upgrade a package"
    "upgrade-all:Upgrade all packages. Runs \`pip install -U <pkgname>\` for each package."
    "uninstall:Uninstall a package"
    "uninstall-all:Uninstall all packages"
    "reinstall:Reinstall a package"
    "reinstall-all:Reinstall all packages"
    "list:List installed packages"
    "run:Download the latest version of a package to a temporary virtual environment, then run an app from it. Also compatible with local \`__pypackages__\` directory (experimental)."
    "runpip:Run pip in an existing pipx-managed Virtual Environment"
    "ensurepath:Ensure directories necessary for pipx operation are in your PATH environment variable."
    "completions:Print instructions on enabling shell completions for pipx"
  )

  _arguments -C \
    "1: :{_describe 'pipx commands' commands}" \
    '*:: :->args' \
    && ret=0

  local _global_flags help="--help"
  _global_flags=(
    "(: -)--help[Help for $words[1]]"
    "--verbose[verbose output]"
  )

  case $state in
    args)

      case $words[1] in
        install)
          _arguments \
            $_global_flags \
            "($help)--include-deps[Include apps of dependent packages]" \
            "($help -f --force)"{-f,--force}"[Modify existing virtual environment and files in PIPX_BIN_DIR]" \
            "($help)--suffix[Optional suffix for virtual environment and executable names.]:suffix" \
            "($help)--python[The Python executable used to create the Virtual Environment and run the associated app/apps. Must be v3.5+.]:Python executable:_command_names" \
            "($help)--system-site-packages[Give the virtual environment access to the system site-packages dir.]" \
            "($help -i --index-url)"{-i,--index-url}"[Base URL of Python Package Index]:index_url:_urls" \
            "($help -e --editable)"{-e,--editable}"[Install a project in editable mode]" \
            "($help)--pip-args[Arbitrary pip arguments to pass directly to pip install/upgrade commands]:pip_args:_pip" \
            "($help -)*:package spec" \
            && ret=0
          ;;

        inject)
          _arguments \
            $_global_flags[@] \
            "($help)--include-apps[Add apps from the injected packages onto your PATH]" \
            "($help)--include-deps[Include apps of dependent packages]" \
            "($help)--system-site-packages[Give the virtual environment access to the system site-packages dir.]" \
            "($help -i --index-url)"{-i,--index-url}="[Base URL of Python Package Index]:index_url:_urls" \
            "($help -e --editable)"{-e,--editable}"[Install a project in editable mode]" \
            "($help)--pip-args=[Arbitrary pip arguments to pass directly to pip install/upgrade commands]:pip_args:_pip" \
            "($help -f --force)"{-f,--force}"[Modify existing virtual environment and files in PIPX_BIN_DIR]" \
            "($help -)1:package\: Name of the existing pipx-managed Virtual Environment to inject into" \
            "($help -)*:dependencies#\: the packages to inject into the Virtual Environment. either package name or pip package spec" \
            && ret=0
          ;;

        upgrade)
          _arguments \
            $_global_flags \
            "($help -f --force)"{-f,--force}"[Modify existing virtual environment and files in PIPX_BIN_DIR]" \
            "($help)--system-site-packages[Give the virtual environment access to the system site-packages dir.]" \
            "($help -i --index-url)"{-i,--index-url}"[Base URL of Python Package Index]:index_url:_urls" \
            "($help -e --editable)"{-e,--editable}"[Install a project in editable mode]" \
            "($help)--pip-args[Arbitrary pip arguments to pass directly to pip install/upgrade commands]:pip_args:_pip" \
            "($help -)1:package" \
            && ret=0
          ;;

        upgrade-all)
          _arguments \
            $_global_flags \
            "(: -)--skip[skip these packages]:skip package" \
            "($help -f --force)"{-f,--force}"[Modify existing virtual environment and files in PIPX_BIN_DIR]" \
            && ret=0
          ;;

        uninstall)
          _arguments \
            $_global_flags \
            "($help -)1:package" \
            && ret=0
          ;;

        uninstall-all)
          _arguments \
            $_global_flags \
            "($help -)1:package" \
            && ret=0
          ;;

        reinstall)
          _arguments \
            $_global_flags \
            "($help)--python[The Python executable used to create the Virtual Environment and run the associated app/apps. Must be v3.5+.]:Python executable:_command_names" \
            && ret=0
          ;;

        reinstall-all)
          _arguments \
            $_global_flags \
            "($help)--python[The Python executable used to create the Virtual Environment and run the associated app/apps. Must be v3.5+.]:Python executable:_command_names" \
            "(: -)--skip[skip these packages]:skip package" \
            && ret=0
          ;;

        list)
          _arguments \
            $_global_flags \
            "($help)--include-injected[Show packages injected into the main app's environment]" \
            && ret=0
          ;;

        run)
          _arguments \
            $_global_flags \
            "($help)--no-cache[Do not re-use cached virtual environment if it exists]" \
            "($help)--pypackages[Require app to be run from local __pypackages__ directory]" \
            "($help)--spec[The package name or specific installation source passed to pip.]:pip spec" \
            "($help)--python[The Python version to run package's CLI app with. Must be v3.5+.]:Python executable:_command_names" \
            "($help)--system-site-packages[Give the virtual environment access to the system site-packages dir.]" \
            "($help -i --index-url)"{-i,--index-url}"[Base URL of Python Package Index]:index_url:_urls" \
            "($help -e --editable)"{-e,--editable}"[Install a project in editable mode]" \
            "($help)--pip-args[Arbitrary pip arguments to pass directly to pip install/upgrade commands]:pip_args:_pip" \
            "($help -)*:app" \
            && ret=0
          ;;

        runpip)
          _arguments \
            $_global_flags \
            "($help -)1[Name of the existing pipx-managed Virtual Environment to run pip in]:package" \
            "($help -)*:pipargs" \
            && ret=0
          ;;

        ensurepath)
          _arguments \
            $_global_flags \
            "($help -f --force)"{-f,--force}"[Add text to your shell's config file even if it looks like your PATH already contains paths to pipx and pipx-install apps.]" \
            && ret=0
          ;;
      esac
      ;;
  esac

  return ret
}

_pipx "$*"

# -----------------------------------------------------------------------------
#
# usage: pipx [-h] [--version]
#             {install,inject,upgrade,upgrade-all,uninstall,uninstall-all,reinstall,reinstall-all,list,run,runpip,ensurepath,completions}
#             ...
# 
# Install and execute apps from Python packages.
# 
# Binaries can either be installed globally into isolated Virtual Environments
# or run directly in an temporary Virtual Environment.
# 
# Virtual Environment location is /usr/local/var/pipx/venvs.
# Symlinks to apps are placed in /usr/local/share/pipx.
# 
# optional environment variables:
#   PIPX_HOME             Overrides default pipx location. Virtual Environments
#                         will be installed to $PIPX_HOME/venvs.
#   PIPX_BIN_DIR          Overrides location of app installations. Apps are
#                         symlinked or copied here.
#   USE_EMOJI             Overrides emoji behavior. Default value varies based
#                         on platform.
#   PIPX_DEFAULT_PYTHON   Overrides default python used for commands.
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --version             Print version and exit
# 
# subcommands:
#   Get help for commands with pipx COMMAND --help
# 
#   {install,inject,upgrade,upgrade-all,uninstall,uninstall-all,reinstall,reinstall-all,list,run,runpip,ensurepath,completions}
#     install             Install a package
#     inject              Install packages into an existing Virtual Environment
#     upgrade             Upgrade a package
#     upgrade-all         Upgrade all packages. Runs `pip install -U <pkgname>`
#                         for each package.
#     uninstall           Uninstall a package
#     uninstall-all       Uninstall all packages
#     reinstall           Reinstall a package
#     reinstall-all       Reinstall all packages
#     list                List installed packages
#     run                 Download the latest version of a package to a
#                         temporary virtual environment, then run an app from
#                         it. Also compatible with local `__pypackages__`
#                         directory (experimental).
#     runpip              Run pip in an existing pipx-managed Virtual
#                         Environment
#     ensurepath          Ensure directories necessary for pipx operation are in
#                         your PATH environment variable.
#     completions         Print instructions on enabling shell completions for
#                         pipx
#
# -----------------------------------------------------------------------------
#
# usage: pipx install [-h] [--include-deps] [--verbose] [--force]
#                     [--suffix SUFFIX] [--python PYTHON]
#                     [--system-site-packages] [--index-url INDEX_URL]
#                     [--editable] [--pip-args PIP_ARGS]
#                     package_spec
# 
# The install command is the preferred way to globally install apps
# from python packages on your system. It creates an isolated virtual
# environment for the package, then ensures the package's apps are
# accessible on your $PATH.
# 
# The result: apps you can run from anywhere, located in packages
# you can cleanly upgrade or uninstall. Guaranteed to not have
# dependency version conflicts or interfere with your OS's python
# packages. 'sudo' is not required to do this.
# 
# pipx install PACKAGE_NAME
# pipx install --python PYTHON PACKAGE_NAME
# pipx install VCS_URL
# pipx install ./LOCAL_PATH
# pipx install ZIP_FILE
# pipx install TAR_GZ_FILE
# 
# The PACKAGE_SPEC argument is passed directly to `pip install`.
# 
# The default virtual environment location is /Users/zchee/.local/pipx
# and can be overridden by setting the environment variable `PIPX_HOME`
# (Virtual Environments will be installed to `$PIPX_HOME/venvs`).
# 
# The default app location is /Users/zchee/.local/bin and can be
# overridden by setting the environment variable `PIPX_BIN_DIR`.
# 
# The default python executable used to install a package is
# /usr/local/opt/python@3.9/bin/python3.9 and can be overridden
# by setting the environment variable `PIPX_DEFAULT_PYTHON`.
# 
# positional arguments:
#   package_spec          package name or pip installation spec
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --include-deps        Include apps of dependent packages
#   --verbose
#   --force, -f           Modify existing virtual environment and files in
#                         PIPX_BIN_DIR
#   --suffix SUFFIX       Optional suffix for virtual environment and executable
#                         names. NOTE: The suffix feature is experimental and
#                         subject to change.
#   --python PYTHON       The Python executable used to create the Virtual
#                         Environment and run the associated app/apps. Must be
#                         v3.5+.
#   --system-site-packages
#                         Give the virtual environment access to the system
#                         site-packages dir.
#   --index-url INDEX_URL, -i INDEX_URL
#                         Base URL of Python Package Index
#   --editable, -e        Install a project in editable mode
#   --pip-args PIP_ARGS   Arbitrary pip arguments to pass directly to pip
#                         install/upgrade commands
#
# -----------------------------------------------------------------------------
#
# usage: pipx inject [-h] [--include-apps] [--include-deps]
#                    [--system-site-packages] [--index-url INDEX_URL]
#                    [--editable] [--pip-args PIP_ARGS] [--force] [--verbose]
#                    package dependencies [dependencies ...]
# 
# Installs packages to an existing pipx-managed virtual environment.
# 
# positional arguments:
#   package               Name of the existing pipx-managed Virtual Environment
#                         to inject into
#   dependencies          the packages to inject into the Virtual Environment--
#                         either package name or pip package spec
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --include-apps        Add apps from the injected packages onto your PATH
#   --include-deps        Include apps of dependent packages
#   --system-site-packages
#                         Give the virtual environment access to the system
#                         site-packages dir.
#   --index-url INDEX_URL, -i INDEX_URL
#                         Base URL of Python Package Index
#   --editable, -e        Install a project in editable mode
#   --pip-args PIP_ARGS   Arbitrary pip arguments to pass directly to pip
#                         install/upgrade commands
#   --force, -f           Modify existing virtual environment and files in
#                         PIPX_BIN_DIR
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx upgrade [-h] [--force] [--system-site-packages]
#                     [--index-url INDEX_URL] [--editable] [--pip-args PIP_ARGS]
#                     [--verbose]
#                     package
# 
# Upgrade a package in a pipx-managed Virtual Environment by running 'pip
# install --upgrade PACKAGE'
# 
# positional arguments:
#   package
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --force, -f           Modify existing virtual environment and files in
#                         PIPX_BIN_DIR
#   --system-site-packages
#                         Give the virtual environment access to the system
#                         site-packages dir.
#   --index-url INDEX_URL, -i INDEX_URL
#                         Base URL of Python Package Index
#   --editable, -e        Install a project in editable mode
#   --pip-args PIP_ARGS   Arbitrary pip arguments to pass directly to pip
#                         install/upgrade commands
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx upgrade-all [-h] [--skip SKIP [SKIP ...]] [--force] [--verbose]
# 
# Upgrades all packages within their virtual environments by running 'pip
# install --upgrade PACKAGE'
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --skip SKIP [SKIP ...]
#                         skip these packages
#   --force, -f           Modify existing virtual environment and files in
#                         PIPX_BIN_DIR
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx uninstall [-h] [--verbose] package
# 
# Uninstalls a pipx-managed Virtual Environment by deleting it and any files
# that point to its apps.
# 
# positional arguments:
#   package
# 
# optional arguments:
#   -h, --help  show this help message and exit
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx uninstall-all [-h] [--verbose]
# 
# Uninstall all pipx-managed packages
# 
# optional arguments:
#   -h, --help  show this help message and exit
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx reinstall [-h] [--python PYTHON] [--verbose] package
# 
# Reinstalls a package.
# 
# Package is uninstalled, then installed with pipx install PACKAGE
# with the same options used in the original install of PACKAGE.
# 
# positional arguments:
#   package
# 
# optional arguments:
#   -h, --help       show this help message and exit
#   --python PYTHON  The Python executable used to recreate the Virtual
#                    Environment and run the associated app/apps. Must be v3.5+.
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx reinstall-all [-h] [--python PYTHON] [--skip SKIP [SKIP ...]]
#                           [--verbose]
# 
# Reinstalls all packages.
# 
# Packages are uninstalled, then installed with pipx install PACKAGE
# with the same options used in the original install of PACKAGE.
# This is useful if you upgraded to a new version of Python and want
# all your packages to use the latest as well.
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --python PYTHON       The Python executable used to recreate the Virtual
#                         Environment and run the associated app/apps. Must be
#                         v3.5+.
#   --skip SKIP [SKIP ...]
#                         skip these packages
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx list [-h] [--include-injected] [--verbose]
# 
# List packages and apps installed with pipx
# 
# optional arguments:
#   -h, --help          show this help message and exit
#   --include-injected  Show packages injected into the main app's environment
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx run [-h] [--no-cache] [--pypackages] [--spec SPEC] [--verbose]
#                 [--python PYTHON] [--system-site-packages]
#                 [--index-url INDEX_URL] [--editable] [--pip-args PIP_ARGS]
#                 app ...
# 
# Download the latest version of a package to a temporary virtual environment,
# then run an app from it. The environment will be cached
# and re-used for up to 14 days. This
# means subsequent calls to 'run' for the same package will be faster
# since they can re-use the cached Virtual Environment.
# 
# In support of PEP 582 'run' will use apps found in a local __pypackages__
#  directory, if present. Please note that this behavior is experimental,
#  and is a acts as a companion tool to pythonloc. It may be modified or
#  removed in the future. See https://github.com/cs01/pythonloc.
# 
# positional arguments:
#   app ...               app/package name and any arguments to be passed to it
# 
# optional arguments:
#   -h, --help            show this help message and exit
#   --no-cache            Do not re-use cached virtual environment if it exists
#   --pypackages          Require app to be run from local __pypackages__
#                         directory
#   --spec SPEC           The package name or specific installation source
#                         passed to pip. Runs `pip install -U SPEC`. For example
#                         `--spec mypackage==2.0.0` or `--spec
#                         git+https://github.com/user/repo.git@branch`
#   --verbose
#   --python PYTHON       The Python version to run package's CLI app with. Must
#                         be v3.5+.
#   --system-site-packages
#                         Give the virtual environment access to the system
#                         site-packages dir.
#   --index-url INDEX_URL, -i INDEX_URL
#                         Base URL of Python Package Index
#   --editable, -e        Install a project in editable mode
#   --pip-args PIP_ARGS   Arbitrary pip arguments to pass directly to pip
#                         install/upgrade commands
#
# -----------------------------------------------------------------------------
#
# usage: pipx runpip [-h] [--verbose] package ...
# 
# Run pip in an existing pipx-managed Virtual Environment
# 
# positional arguments:
#   package     Name of the existing pipx-managed Virtual Environment to run pip
#               in
#   pipargs     Arguments to forward to pip command
# 
# optional arguments:
#   -h, --help  show this help message and exit
#   --verbose
#
# -----------------------------------------------------------------------------
#
# usage: pipx ensurepath [-h] [--force]
# 
# Ensure directory where pipx stores apps is in your PATH environment variable.
# Also if pipx was installed via `pip install --user`, ensure pipx itself is in
# your PATH. Note that running this may modify your shell's configuration
# file(s) such as '~/.bashrc'.
# 
# optional arguments:
#   -h, --help   show this help message and exit
#   --force, -f  Add text to your shell's config file even if it looks like your
#                PATH already contains paths to pipx and pipx-install apps.
#
# -----------------------------------------------------------------------------
#
# usage: pipx completions [-h]
# 
# Print instructions on enabling shell completions for pipx
# 
# optional arguments:
#   -h, --help  show this help message and exit
#
# -----------------------------------------------------------------------------
 
# vim:ft=zsh:et:sts=2:sw=2