From fdc515ed75b44d63c38481c08e0ecb4dcf3cef88 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Fri, 13 Sep 2024 19:51:27 +1200 Subject: [PATCH] pipx/pipx_info: refactor doc fragment --- .github/BOTMETA.yml | 2 ++ plugins/doc_fragments/pipx.py | 37 +++++++++++++++++++++++++++++++++ plugins/modules/pipx.py | 39 +++++++++-------------------------- plugins/modules/pipx_info.py | 23 +-------------------- 4 files changed, 50 insertions(+), 51 deletions(-) create mode 100644 plugins/doc_fragments/pipx.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index bc34755b31..c9326fa75a 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -131,6 +131,8 @@ files: maintainers: $team_huawei $doc_fragments/nomad.py: maintainers: chris93111 apecnascimento + $doc_fragments/pipx.py: + maintainers: russoz $doc_fragments/xenserver.py: labels: xenserver maintainers: bvitnik diff --git a/plugins/doc_fragments/pipx.py b/plugins/doc_fragments/pipx.py new file mode 100644 index 0000000000..112695f24f --- /dev/null +++ b/plugins/doc_fragments/pipx.py @@ -0,0 +1,37 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) 2024, Alexei Znamensky +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + DOCUMENTATION = r''' +options: + global: + description: + - The module will pass the C(--global) argument to C(pipx), to execute actions in global scope. + - The C(--global) is only available in C(pipx>=1.6.0), so make sure to have a compatible version when using this option. + Moreover, a nasty bug with C(--global) was fixed in C(pipx==1.7.0), so it is strongly recommended you used that version or newer. + type: bool + default: false + executable: + description: + - Path to the C(pipx) installed in the system. + - > + If not specified, the module will use C(python -m pipx) to run the tool, + using the same Python interpreter as ansible itself. + type: path +notes: + - This module requires C(pipx) version 0.16.2.1 or above. From community.general 11.0.0 onwards, the module will require C(pipx>=1.7.0). + - Please note that C(pipx) requires Python 3.6 or above. + - This module does not install the C(pipx) python package, however that can be easily done with the module M(ansible.builtin.pip). + - This module does not require C(pipx) to be in the shell C(PATH), but it must be loadable by Python as a module. + - > + This module will honor C(pipx) environment variables such as but not limited to E(PIPX_HOME) and E(PIPX_BIN_DIR) + passed using the R(environment Ansible keyword, playbooks_environment). + - See also the C(pipx) documentation at U(https://pypa.github.io/pipx/). +''' diff --git a/plugins/modules/pipx.py b/plugins/modules/pipx.py index 4793dd49ea..c5dbcb5e96 100644 --- a/plugins/modules/pipx.py +++ b/plugins/modules/pipx.py @@ -18,6 +18,7 @@ description: - Manage Python applications installed in isolated virtualenvs using pipx. extends_documentation_fragment: - community.general.attributes + - community.general.pipx attributes: check_mode: support: full @@ -54,17 +55,18 @@ options: name: type: str description: - - > - The name of the application to be installed. It must to be a simple package name. - For passing package specifications or installing from URLs or directories, - please use the O(source) option. + - The name of the application. In C(pipx) documentation it is also referred to as + the name of the virtual environment where the application will be installed. + - If O(name) is a simple package name without version specifiers, + then that name is used as the Python package name to be installed. + - Use O(source) for passing package specifications or installing from URLs or directories. source: type: str description: - - > - If the application source, such as a package with version specifier, or an URL, - directory or any other accepted specification. See C(pipx) documentation for more details. - - When specified, the C(pipx) command will use O(source) instead of O(name). + - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other states. + - Use O(source) when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed file. + - The value of this option is passed as-is to C(pipx). + - O(name) is still required when using O(source) to establish the application name without fetching the package from a remote source. install_apps: description: - Add apps from the injected packages. @@ -114,13 +116,6 @@ options: type: bool default: false version_added: 6.6.0 - executable: - description: - - Path to the C(pipx) installed in the system. - - > - If not specified, the module will use C(python -m pipx) to run the tool, - using the same Python interpreter as ansible itself. - type: path editable: description: - Install the project in editable mode. @@ -139,12 +134,6 @@ options: type: str version_added: 9.3.0 global: - description: - - The module will pass the C(--global) argument to C(pipx), to execute actions in global scope. - - The C(--global) is only available in C(pipx>=1.6.0), so make sure to have a compatible version when using this option. - Moreover, a nasty bug with C(--global) was fixed in C(pipx==1.7.0), so it is strongly recommended you used that version or newer. - type: bool - default: false version_added: 9.4.0 spec_metadata: description: @@ -154,19 +143,11 @@ options: type: path version_added: 9.4.0 notes: - - This module requires C(pipx) version 0.16.2.1 or above. From community.general 11.0.0 onwards, the module will require C(pipx>=1.7.0). - - Please note that C(pipx) requires Python 3.6 or above. - - This module does not install the C(pipx) python package, however that can be easily done with the module M(ansible.builtin.pip). - - This module does not require C(pipx) to be in the shell C(PATH), but it must be loadable by Python as a module. - - > - This module will honor C(pipx) environment variables such as but not limited to C(PIPX_HOME) and C(PIPX_BIN_DIR) - passed using the R(environment Ansible keyword, playbooks_environment). - > This first implementation does not verify whether a specified version constraint has been installed or not. Hence, when using version operators, C(pipx) module will always try to execute the operation, even when the application was previously installed. This feature will be added in the future. - - See also the C(pipx) documentation at U(https://pypa.github.io/pipx/). author: - "Alexei Znamensky (@russoz)" ''' diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py index 816729f9a6..a1bb35032c 100644 --- a/plugins/modules/pipx_info.py +++ b/plugins/modules/pipx_info.py @@ -19,6 +19,7 @@ description: extends_documentation_fragment: - community.general.attributes - community.general.attributes.info_module + - community.general.pipx options: name: description: @@ -40,30 +41,8 @@ options: - The raw output is not affected by O(include_deps) or O(include_injected). type: bool default: false - executable: - description: - - Path to the C(pipx) installed in the system. - - > - If not specified, the module will use C(python -m pipx) to run the tool, - using the same Python interpreter as ansible itself. - type: path global: - description: - - The module will pass the C(--global) argument to C(pipx), to execute actions in global scope. - - The C(--global) is only available in C(pipx>=1.6.0), so make sure to have a compatible version when using this option. - Moreover, a nasty bug with C(--global) was fixed in C(pipx==1.7.0), so it is strongly recommended you used that version or newer. - type: bool - default: false version_added: 9.3.0 -notes: - - This module requires C(pipx) version 0.16.2.1 or above. From community.general 11.0.0 onwards, the module will require C(pipx>=1.7.0). - - Please note that C(pipx) requires Python 3.6 or above. - - This module does not install the C(pipx) python package, however that can be easily done with the module M(ansible.builtin.pip). - - This module does not require C(pipx) to be in the shell C(PATH), but it must be loadable by Python as a module. - - > - This module will honor C(pipx) environment variables such as but not limited to E(PIPX_HOME) and E(PIPX_BIN_DIR) - passed using the R(environment Ansible keyword, playbooks_environment). - - See also the C(pipx) documentation at U(https://pypa.github.io/pipx/). author: - "Alexei Znamensky (@russoz)" '''