community.general.pipx 模块 – 使用 pipx 管理已安装的应用程序

注意

此模块是 community.general 集合 (版本 10.1.0) 的一部分。

如果您正在使用 ansible 包，则您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.general。

要在 playbook 中使用它，请指定： community.general.pipx。

community.general 3.8.0 中的新增功能

概要 

使用 pipx 管理在隔离的虚拟环境中安装的 Python 应用程序。

参数 

参数	注释
editable 布尔值 community.general 4.6.0 中新增	以可编辑模式安装项目。选项 `false` ← (默认) `true`
executable 路径	系统中安装的 `pipx` 的路径。如果未指定，模块将使用 `python -m pipx` 来运行工具，使用与 Ansible 本身相同的 Python 解释器。
force 布尔值	强制修改应用程序的虚拟环境。详情请参阅 `pipx`。仅当 `state=install`、`state=upgrade`、`state=upgrade_all`、`state=latest` 或 `state=inject` 时使用。选项 `false` ← (默认) `true`
global 布尔值 community.general 9.4.0 中新增	模块将向 `pipx` 传递 `--global` 参数，以便在全局范围内执行操作。 `--global` 仅在 `pipx>=1.6.0` 中可用，因此在使用此选项时，请确保使用兼容的版本。此外，`pipx==1.7.0` 修复了 `--global` 的一个严重错误，因此强烈建议您使用该版本或更高版本。选项 `false` ← (默认) `true`
include_injected 布尔值	与应用程序一起升级注入的包。仅当 `state=upgrade`、`state=upgrade_all` 或 `state=latest` 时使用。自 community.general 6.6.0 起，此选项与 `state=upgrade` 和 `state=latest` 一起使用。选项 `false` ← (默认) `true`
index_url 字符串	Python 包索引的基 URL。仅当 `state=install`、`state=upgrade`、`state=latest` 或 `state=inject` 时使用。
inject_packages 列表 / 元素=字符串	要注入到现有虚拟环境中的包。仅当 `state=inject` 时使用。
install_apps 布尔值 community.general 6.5.0 中新增	添加来自注入包的应用程序。仅当 `state=inject` 时使用。选项 `false` ← (默认) `true`
install_deps 布尔值	包含依赖包的应用程序。仅当 `state=install`、`state=latest` 或 `state=inject` 时使用。选项 `false` ← (默认) `true`
name 字符串	应用程序的名称。在 `pipx` 文档中，它也称为将安装应用程序的虚拟环境的名称。如果 `name` 是一个简单的包名，没有版本说明符，则该名称用作要安装的 Python 包名。使用 `source` 传递包规范或从 URL 或目录安装。
pip_args 字符串 community.general 4.6.0 中新增	直接传递给 `pip` 的任意参数。
python 字符串	创建应用程序虚拟环境时使用的 Python 版本。必须为 3.6 或更高版本。仅在 `state=install`、`state=latest`、`state=reinstall` 或 `state=reinstall_all` 时使用。
源代码字符串	包的源代码。此选项在 `state=install` 或 `state=latest` 时使用，在其他状态下会被忽略。安装具有版本说明符的 Python 包，或从本地路径、VCS URL 或压缩文件安装时，请使用 `source`。此选项的值将按原样传递给 `pipx`。使用 `source` 从远程源获取包时，仍然需要 `name` 来确定应用程序名称。
规范元数据路径 community.general 9.4.0 中新增	用于 `state=install_all` 的规范元数据文件。该文件的内容通常使用 `pipx list --json` 生成，并且可以使用 community.general.pipx_info 和 `include_raw=true` 获取，然后从 `raw_output` 中获取内容。
状态字符串	应用程序的所需状态。状态 `present` 和 `absent` 分别是 `install` 和 `uninstall` 的别名。状态 `latest` 等效于执行两次任务，状态分别为 `install` 和 `upgrade`。它在 community.general 5.5.0 中添加。状态 `install_all`、`uninject`、`upgrade_shared`、`pin` 和 `unpin` 仅在 `pipx>=1.6.0` 中可用，使用此选项时，请确保具有兼容的版本。这些状态已在 community.general 9.4.0 中添加。选项 `"present"` `"absent"` `"install"` ← (默认) `"install_all"` `"uninstall"` `"uninstall_all"` `"inject"` `"uninject"` `"upgrade"` `"upgrade_shared"` `"upgrade_all"` `"reinstall"` `"reinstall_all"` `"latest"` `"pin"` `"unpin"`
后缀字符串在 community.general 9.3.0 中添加	虚拟环境和可执行文件名称的可选后缀。警告：`pipx` 文档指出这是一个实验性功能，可能会发生更改。
系统站点包布尔值在 community.general 6.6.0 中添加	允许应用程序虚拟环境访问系统站点包目录。仅在 `state=install` 或 `state=latest` 时使用。选项 `false` ← (默认) `true`

属性 

属性	支持	描述
check_mode	支持：完全支持	可以在 `check_mode` 中运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：完全支持	处于差异模式时，将返回有关已更改内容（或在 `check_mode` 中可能需要更改的内容）的详细信息。

注释 

注意

第一个实现并不验证是否已安装指定的版本约束。因此，在使用版本运算符时，即使应用程序先前已安装，pipx 模块也会始终尝试执行操作。此功能将在未来添加。
此模块需要 pipx 版本 0.16.2.1 或更高版本。从 community.general 11.0.0 开始，此模块将需要 pipx>=1.7.0。
请注意，pipx 需要 Python 3.6 或更高版本。
此模块不会安装 pipx python 包，但是可以使用 ansible.builtin.pip 模块轻松完成此操作。
此模块不需要 pipx 位于 shell 的 PATH 中，但它必须能够被 Python 作为模块加载。
此模块将遵循 pipx 环境变量，例如但不限于使用 environment Ansible 关键字传递的 PIPX_HOME 和 PIPX_BIN_DIR。

另请参阅 

另请参阅

C(pipx) 命令手册页: 命令的手册页。

示例 

---
- name: Install tox
  community.general.pipx:
    name: tox

- name: Install tox from git repository
  community.general.pipx:
    name: tox
    source: git+https://github.com/tox-dev/tox.git

- name: Upgrade tox
  community.general.pipx:
    name: tox
    state: upgrade

- name: Reinstall black with specific Python version
  community.general.pipx:
    name: black
    state: reinstall
    python: 3.7

- name: Uninstall pycowsay
  community.general.pipx:
    name: pycowsay
    state: absent

- name: Install multiple packages from list
  vars:
    pipx_packages:
    - pycowsay
    - black
    - tox
  community.general.pipx:
    name: "{{ item }}"
    state: latest
  with_items: "{{ pipx_packages }}"

返回值 

常见的返回值已在此处记录，以下是此模块特有的字段

键	描述
版本字符串在 community.general 10.1.0 中添加	pipx 的版本。返回：始终返回示例：`"1.7.1"`

作者

Alexei Znamensky (@russoz)