[PR #8859/e4472b32 backport][stable-9] pipx/pipx_info: refactor doc fragment (#8869)

pipx/pipx_info: refactor doc fragment (#8859)

* pipx/pipx_info: refactor doc fragment

* pipx/pipx_info: refactor common options to module_utils

(cherry picked from commit e4472b322b)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

.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

plugins/doc_fragments/pipx.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Alexei Znamensky <russoz@gmail.com>
+# 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/).
+'''

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',

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. In C(pipx) documentation it is also referred to as
-              The name of the application to be installed. It must to be a simple package name.
+              the name of the virtual environment where the application will be installed.
-              For passing package specifications or installing from URLs or directories,
+            - If O(name) is a simple package name without version specifiers,
-              please use the O(source) option.
+              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:
-            - >
+            - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other states.
-              If the application source, such as a package with version specifier, or an URL,
+            - Use O(source) when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed file.
-              directory or any other accepted specification. See C(pipx) documentation for more details.
+            - The value of this option is passed as-is to C(pipx).
-            - When specified, the C(pipx) command will use O(source) instead of O(name).
+            - 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,

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,