From e4472b322bdd1e23f3f876110692a2128e0a9db8 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Sat, 14 Sep 2024 19:27:12 +1200 Subject: [PATCH] pipx/pipx_info: refactor doc fragment (#8859) * pipx/pipx_info: refactor doc fragment * pipx/pipx_info: refactor common options to module_utils --- .github/BOTMETA.yml | 2 ++ plugins/doc_fragments/pipx.py | 37 +++++++++++++++++++++++++++++ plugins/module_utils/pipx.py | 6 +++++ plugins/modules/pipx.py | 44 ++++++++++------------------------- plugins/modules/pipx_info.py | 28 +++------------------- 5 files changed, 60 insertions(+), 57 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/module_utils/pipx.py b/plugins/module_utils/pipx.py index 9ae7b5381c..513b9081f6 100644 --- a/plugins/module_utils/pipx.py +++ b/plugins/module_utils/pipx.py @@ -9,6 +9,12 @@ __metaclass__ = type from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt as fmt +pipx_common_argspec = { + "global": dict(type='bool', default=False), + "executable": dict(type='path'), +} + + _state_map = dict( install='install', install_all='install-all', diff --git a/plugins/modules/pipx.py b/plugins/modules/pipx.py index 4793dd49ea..4b94dee2ac 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)" ''' @@ -213,7 +194,7 @@ EXAMPLES = ''' import json from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper -from ansible_collections.community.general.plugins.module_utils.pipx import pipx_runner +from ansible_collections.community.general.plugins.module_utils.pipx import pipx_runner, pipx_common_argspec from ansible.module_utils.facts.compat import ansible_facts @@ -240,13 +221,12 @@ class PipX(StateModuleHelper): index_url=dict(type='str'), python=dict(type='str'), system_site_packages=dict(type='bool', default=False), - executable=dict(type='path'), editable=dict(type='bool', default=False), pip_args=dict(type='str'), suffix=dict(type='str'), spec_metadata=dict(type='path'), ) - argument_spec["global"] = dict(type='bool', default=False) + argument_spec.update(pipx_common_argspec) module = dict( argument_spec=argument_spec, diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py index 816729f9a6..0e0cc0fe14 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)" ''' @@ -141,7 +120,7 @@ cmd: import json from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper -from ansible_collections.community.general.plugins.module_utils.pipx import pipx_runner +from ansible_collections.community.general.plugins.module_utils.pipx import pipx_runner, pipx_common_argspec from ansible.module_utils.facts.compat import ansible_facts @@ -153,9 +132,8 @@ class PipXInfo(ModuleHelper): include_deps=dict(type='bool', default=False), include_injected=dict(type='bool', default=False), include_raw=dict(type='bool', default=False), - executable=dict(type='path'), ) - argument_spec["global"] = dict(type='bool', default=False) + argument_spec.update(pipx_common_argspec) module = dict( argument_spec=argument_spec, supports_check_mode=True,