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 boolean 在 community.general 4.6.0 中添加	以可编辑模式安装项目。选择 `false` ← (默认) `true`
executable path	系统中安装的 `pipx` 的路径。如果未指定，该模块将使用 `python -m pipx` 来运行该工具，使用与 Ansible 本身相同的 Python 解释器。
force boolean	强制修改应用程序的虚拟环境。有关详细信息，请参阅 `pipx`。仅当 `state=install`、`state=upgrade`、`state=upgrade_all`、`state=latest` 或 `state=inject` 时使用。选择 `false` ← (默认) `true`
global boolean 在 community.general 9.4.0 中添加	该模块将 `--global` 参数传递给 `pipx`，以在全局范围内执行操作。 `--global` 仅在 `pipx>=1.6.0` 中可用，因此请确保在使用此选项时具有兼容的版本。此外，`--global` 的一个讨厌的 bug 已在 `pipx==1.7.0` 中修复，因此强烈建议您使用该版本或更新的版本。选择 `false` ← (默认) `true`
include_injected boolean	将注入的软件包与应用程序一起升级。仅当 `state=upgrade`、`state=upgrade_all` 或 `state=latest` 时使用。自 community.general 6.6.0 起，此选项与 `state=upgrade` 和 `state=latest` 一起使用。选择 `false` ← (默认) `true`
index_url string	Python 包索引的基本 URL。仅当 `state=install`、`state=upgrade`、`state=latest` 或 `state=inject` 时使用。
inject_packages list / elements=string	要注入到现有虚拟环境中的软件包。仅当 `state=inject` 时使用。
install_apps boolean 在 community.general 6.5.0 中添加	从注入的软件包中添加应用程序。仅当 `state=inject` 时使用。选择 `false` ← (默认) `true`
install_deps boolean	包含依赖包的应用程序。仅当 `state=install`, `state=latest` 或 `state=inject` 时使用。选择 `false` ← (默认) `true`
name string	应用程序的名称。在 `pipx` 文档中，它也被称为将要安装应用程序的虚拟环境的名称。如果 `name` 是一个没有版本说明符的简单包名称，则该名称将用作要安装的 Python 包名称。使用 `source` 来传递包规范或从 URL 或目录安装。
pip_args string 在 community.general 4.6.0 中添加	直接传递给 `pip` 的任意参数。
python string	创建应用程序虚拟环境时要使用的 Python 版本。必须是 3.6+。仅当 `state=install`、 `state=latest`、`state=reinstall` 或 `state=reinstall_all` 时使用。
source string	包的来源。当 `state=install` 或 `state=latest` 时使用此选项，对于其他状态则忽略此选项。当安装带有版本说明符的 Python 包，或从本地路径、VCS URL 或压缩文件安装时，请使用 `source`。此选项的值将按原样传递给 `pipx`。当使用 `source` 来建立应用程序名称而不从远程源获取包时，仍然需要 `name`。
spec_metadata path 在 community.general 9.4.0 中添加	`state=install_all` 的规范元数据文件。该文件的内容通常使用 `pipx list --json` 生成，并且可以使用 community.general.pipx_info 和 `include_raw=true` 获取，并从 `raw_output` 中获取内容。
state string	应用程序的期望状态。状态 `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"`
suffix string 在 community.general 9.3.0 中添加	虚拟环境和可执行文件名称的可选后缀。警告：`pipx` 文档指出这是一个实验性功能，可能会发生变化。
system_site_packages boolean 在 community.general 6.6.0 中添加	允许应用程序虚拟环境访问系统 site-packages 目录。仅当 `state=install` 或 `state=latest` 时使用。选择 `false` ← (默认) `true`

属性 

属性	支持	描述
check_mode	支持：完全	可以在 `check_mode` 中运行，并返回已更改状态的预测，而无需修改目标。
diff_mode	支持：完全	在 diff 模式下，将返回有关已更改（或可能需要在 `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 }}"

返回值 

通用返回值在此处记录 here，以下是此模块独有的字段

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

作者

Alexei Znamensky (@russoz)