a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs with references to man pages (#8983) 

* update docs with references to man pages

* reformat module docs

* gconftool2/_info: docs adjustments
pull/9012/head
Alexei Znamensky 2024-10-08 09:00:26 +13:00 committed by GitHub
parent 29a2df8e6b
commit 5b4f41748d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 461 additions and 434 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
plugins/doc_fragments/pipx.py
View File

@ -33,5 +33,10 @@ notes:
- >
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/).
seealso:
- name: C(pipx) command manual page
description: Manual page for the command.
link: https://pipx.pypa.io/latest/docs/
'''

211
plugins/modules/ansible_galaxy_install.py
View File

@ -9,23 +9,29 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
module: ansible_galaxy_install
author:
- "Alexei Znamensky (@russoz)"
- "Alexei Znamensky (@russoz)"
short_description: Install Ansible roles or collections using ansible-galaxy
version_added: 3.5.0
description:
- This module allows the installation of Ansible collections or roles using C(ansible-galaxy).
- This module allows the installation of Ansible collections or roles using C(ansible-galaxy).
notes:
- Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0.
- >
The module will try and run using the C(C.UTF-8) locale.
If that fails, it will try C(en_US.UTF-8).
If that one also fails, the module will fail.
- Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0.
- >
The module will try and run using the C(C.UTF-8) locale.
If that fails, it will try C(en_US.UTF-8).
If that one also fails, the module will fail.
seealso:
- name: C(ansible-galaxy) command manual page
description: Manual page for the command.
link: https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html
requirements:
- ansible-core 2.11 or newer
- ansible-core 2.11 or newer
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: none
@ -34,62 +40,63 @@ attributes:
options:
state:
description:
- >
If O(state=present) then the collection or role will be installed.
Note that the collections and roles are not updated with this option.
- >
Currently the O(state=latest) is ignored unless O(type=collection), and it will
ensure the collection is installed and updated to the latest available version.
- Please note that O(force=true) can be used to perform upgrade regardless of O(type).
- >
If O(state=present) then the collection or role will be installed.
Note that the collections and roles are not updated with this option.
- >
Currently the O(state=latest) is ignored unless O(type=collection), and it will
ensure the collection is installed and updated to the latest available version.
- Please note that O(force=true) can be used to perform upgrade regardless of O(type).
type: str
choices: [ present, latest ]
choices: [present, latest]
default: present
version_added: 9.1.0
type:
description:
- The type of installation performed by C(ansible-galaxy).
- If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections.
- "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices."
- The type of installation performed by C(ansible-galaxy).
- If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections.
- "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices."
type: str
choices: [collection, role, both]
required: true
name:
description:
- Name of the collection or role being installed.
- >
Versions can be specified with C(ansible-galaxy) usual formats.
For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0).
- O(name) and O(requirements_file) are mutually exclusive.
- Name of the collection or role being installed.
- >
Versions can be specified with C(ansible-galaxy) usual formats.
For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0).
- O(name) and O(requirements_file) are mutually exclusive.
type: str
requirements_file:
description:
- Path to a file containing a list of requirements to be installed.
- It works for O(type) equals to V(collection) and V(role).
- O(name) and O(requirements_file) are mutually exclusive.
- Path to a file containing a list of requirements to be installed.
- It works for O(type) equals to V(collection) and V(role).
- O(name) and O(requirements_file) are mutually exclusive.
type: path
dest:
description:
- The path to the directory containing your collections or roles, according to the value of O(type).
- >
Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file)
contains both roles and collections and O(dest) is specified.
- The path to the directory containing your collections or roles, according to the value of O(type).
- >
Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file)
contains both roles and collections and O(dest) is specified.
type: path
no_deps:
description:
- Refrain from installing dependencies.
- Refrain from installing dependencies.
version_added: 4.5.0
type: bool
default: false
force:
description:
- Force overwriting existing roles and/or collections.
- It can be used for upgrading, but the module output will always report C(changed=true).
- Using O(force=true) is mandatory when downgrading.
- Force overwriting existing roles and/or collections.
- It can be used for upgrading, but the module output will always report C(changed=true).
- Using O(force=true) is mandatory when downgrading.
type: bool
default: false
"""
EXAMPLES = """
---
- name: Install collection community.network
community.general.ansible_galaxy_install:
type: collection
@ -111,76 +118,76 @@ EXAMPLES = """
type: collection
name: community.network:3.0.2
force: true
"""
RETURN = """
type:
description: The value of the O(type) parameter.
type: str
returned: always
name:
description: The value of the O(name) parameter.
type: str
returned: always
dest:
description: The value of the O(dest) parameter.
type: str
returned: always
requirements_file:
description: The value of the O(requirements_file) parameter.
type: str
returned: always
force:
description: The value of the O(force) parameter.
type: bool
returned: always
installed_roles:
description:
- If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
- If O(name) is specified, returns that role name and the version installed per path.
type: dict
returned: always when installing roles
contains:
"<path>":
description: Roles and versions for that path.
type: dict
sample:
/home/user42/.ansible/roles:
ansistrano.deploy: 3.9.0
baztian.xfce: v0.0.3
/custom/ansible/roles:
ansistrano.deploy: 3.8.0
installed_collections:
description:
- If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
- If O(name) is specified, returns that collection name and the version installed per path.
type: dict
returned: always when installing collections
contains:
"<path>":
description: Collections and versions for that path
type: dict
sample:
/home/az/.ansible/collections/ansible_collections:
community.docker: 1.6.0
community.general: 3.0.2
/custom/ansible/ansible_collections:
community.general: 3.1.0
new_collections:
description: New collections installed by this module.
returned: success
type: dict
sample:
community.general: 3.1.0
community.docker: 1.6.1
new_roles:
description: New roles installed by this module.
returned: success
type: dict
sample:
ansistrano.deploy: 3.8.0
---
type:
description: The value of the O(type) parameter.
type: str
returned: always
name:
description: The value of the O(name) parameter.
type: str
returned: always
dest:
description: The value of the O(dest) parameter.
type: str
returned: always
requirements_file:
description: The value of the O(requirements_file) parameter.
type: str
returned: always
force:
description: The value of the O(force) parameter.
type: bool
returned: always
installed_roles:
description:
- If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
- If O(name) is specified, returns that role name and the version installed per path.
type: dict
returned: always when installing roles
contains:
"<path>":
description: Roles and versions for that path.
type: dict
sample:
/home/user42/.ansible/roles:
ansistrano.deploy: 3.9.0
baztian.xfce: v0.0.3
/custom/ansible/roles:
ansistrano.deploy: 3.8.0
installed_collections:
description:
- If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
- If O(name) is specified, returns that collection name and the version installed per path.
type: dict
returned: always when installing collections
contains:
"<path>":
description: Collections and versions for that path
type: dict
sample:
/home/az/.ansible/collections/ansible_collections:
community.docker: 1.6.0
community.general: 3.0.2
/custom/ansible/ansible_collections:
community.general: 3.1.0
new_collections:
description: New collections installed by this module.
returned: success
type: dict
sample:
community.general: 3.1.0
community.docker: 1.6.1
new_roles:
description: New roles installed by this module.
returned: success
type: dict
sample:
ansistrano.deploy: 3.8.0
baztian.xfce: v0.0.3
"""
import re

74
plugins/modules/cpanm.py
View File

@ -10,14 +10,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
module: cpanm
short_description: Manages Perl library dependencies
description:
- Manage Perl library dependencies using cpanminus.
- Manage Perl library dependencies using cpanminus.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: none
@ -27,76 +27,82 @@ options:
name:
type: str
description:
- The Perl library to install. Valid values change according to the O(mode), see notes for more details.
- Note that for installing from a local path the parameter O(from_path) should be used.
- The Perl library to install. Valid values change according to the O(mode), see notes for more details.
- Note that for installing from a local path the parameter O(from_path) should be used.
aliases: [pkg]
from_path:
type: path
description:
- The local directory or C(tar.gz) file to install from.
- The local directory or C(tar.gz) file to install from.
notest:
description:
- Do not run unit tests.
- Do not run unit tests.
type: bool
default: false
locallib:
description:
- Specify the install base to install modules.
- Specify the install base to install modules.
type: path
mirror:
description:
- Specifies the base URL for the CPAN mirror to use.
- Specifies the base URL for the CPAN mirror to use.
type: str
mirror_only:
description:
- Use the mirror's index file instead of the CPAN Meta DB.
- Use the mirror's index file instead of the CPAN Meta DB.
type: bool
default: false
installdeps:
description:
- Only install dependencies.
- Only install dependencies.
type: bool
default: false
version:
description:
- Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted.
- Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted.
type: str
executable:
description:
- Override the path to the cpanm executable.
- Override the path to the cpanm executable.
type: path
mode:
description:
- Controls the module behavior. See notes below for more details.
- The default changed from V(compatibility) to V(new) in community.general 9.0.0.
- Controls the module behavior. See notes below for more details.
- The default changed from V(compatibility) to V(new) in community.general 9.0.0.
type: str
choices: [compatibility, new]
default: new
version_added: 3.0.0
name_check:
description:
- When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified).
- When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified).
type: str
version_added: 3.0.0
notes:
- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
- "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)."
- >
O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility.
This was the default mode before community.general 9.0.0.
O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version)
when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL.
C(cpanm) version specifiers do not work in this mode.
- >
O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file,
a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized.
This is the default mode from community.general 9.0.0 onwards.
author:
- "Franck Cuny (@fcuny)"
- "Alexei Znamensky (@russoz)"
'''
- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
- "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)."
- >
O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility.
This was the default mode before community.general 9.0.0.
O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version)
when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL.
C(cpanm) version specifiers do not work in this mode.
- >
O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file,
a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized.
This is the default mode from community.general 9.0.0 onwards.
EXAMPLES = '''
seealso:
- name: C(cpanm) command manual page
description: Manual page for the command.
link: https://metacpan.org/dist/App-cpanminus/view/bin/cpanm
author:
- "Franck Cuny (@fcuny)"
- "Alexei Znamensky (@russoz)"
"""
EXAMPLES = """
---
- name: Install Dancer perl package
community.general.cpanm:
name: Dancer
@ -134,7 +140,7 @@ EXAMPLES = '''
community.general.cpanm:
name: Dancer
version: '1.0'
'''
"""
import os

91
plugins/modules/gconftool2.py
View File

@ -9,16 +9,21 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
module: gconftool2
author:
- Kenneth D. Evensen (@kevensen)
- Kenneth D. Evensen (@kevensen)
short_description: Edit GNOME Configurations
description:
- This module allows for the manipulation of GNOME 2 Configuration via
gconftool-2. Please see the gconftool-2(1) man pages for more details.
- This module allows for the manipulation of GNOME 2 Configuration via gconftool-2. Please see the gconftool-2(1) man pages for more details.
seealso:
- name: C(gconftool-2) command manual page
description: Manual page for the command.
link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
@ -28,42 +33,36 @@ options:
key:
type: str
description:
- A GConf preference key is an element in the GConf repository
that corresponds to an application preference. See man gconftool-2(1).
- A GConf preference key is an element in the GConf repository that corresponds to an application preference.
required: true
value:
type: str
description:
- Preference keys typically have simple values such as strings,
integers, or lists of strings and integers.
This is ignored unless O(state=present). See man gconftool-2(1).
- Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is ignored unless O(state=present).
value_type:
type: str
description:
- The type of value being set.
This is ignored unless O(state=present). See man gconftool-2(1).
choices: [ bool, float, int, string ]
- The type of value being set. This is ignored unless O(state=present).
choices: [bool, float, int, string]
state:
type: str
description:
- The action to take upon the key/value.
required: true
choices: [ absent, present ]
choices: [absent, present]
config_source:
type: str
description:
- Specify a configuration source to use rather than the default path.
See man gconftool-2(1).
direct:
description:
- Access the config database directly, bypassing server. If O(direct) is
specified then the O(config_source) must be specified as well.
See man gconftool-2(1).
- Access the config database directly, bypassing server. If O(direct) is specified then the O(config_source) must be specified as well.
type: bool
default: false
'''
"""
EXAMPLES = """
---
- name: Change the widget font to "Serif 12"
community.general.gconftool2:
key: "/desktop/gnome/interface/font_name"
@ -71,33 +70,33 @@ EXAMPLES = """
value: "Serif 12"
"""
RETURN = '''
key:
description: The key specified in the module parameters.
returned: success
type: str
sample: /desktop/gnome/interface/font_name
value_type:
description: The type of the value that was changed.
returned: success
type: str
sample: string
value:
description:
- The value of the preference key after executing the module or V(null) if key is removed.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
previous_value:
description:
- The value of the preference key before executing the module.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
...
'''
RETURN = """
---
key:
description: The key specified in the module parameters.
returned: success
type: str
sample: /desktop/gnome/interface/font_name
value_type:
description: The type of the value that was changed.
returned: success
type: str
sample: string
value:
description:
- The value of the preference key after executing the module or V(null) if key is removed.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
previous_value:
description:
- The value of the preference key before executing the module.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
"""
from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner

42
plugins/modules/gconftool2_info.py
View File

@ -7,46 +7,50 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
module: gconftool2_info
author:
- "Alexei Znamensky (@russoz)"
- "Alexei Znamensky (@russoz)"
short_description: Retrieve GConf configurations
version_added: 5.1.0
description:
- This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2).
- This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2).
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
- community.general.attributes
- community.general.attributes.info_module
options:
key:
description:
- The key name for an element in the GConf database.
type: str
required: true
notes:
- See man gconftool-2(1) for more details.
seealso:
- name: gconf repository (archived)
description: Git repository for the project. It is an archived project, so the repository is read-only.
link: https://gitlab.gnome.org/Archive/gconf
'''
- name: C(gconftool-2) command manual page
description: Manual page for the command.
link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
- name: gconf repository (archived)
description: Git repository for the project. It is an archived project, so the repository is read-only.
link: https://gitlab.gnome.org/Archive/gconf
"""
EXAMPLES = """
---
- name: Get value for a certain key in the database.
community.general.gconftool2_info:
key: /desktop/gnome/background/picture_filename
register: result
"""
RETURN = '''
value:
description:
- The value of the property.
returned: success
type: str
sample: Monospace 10
'''
RETURN = """
---
value:
description:
- The value of the property.
returned: success
type: str
sample: Monospace 10
"""
from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner

70
plugins/modules/gio_mime.py
View File

@ -7,16 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
module: gio_mime
author:
- "Alexei Znamensky (@russoz)"
- "Alexei Znamensky (@russoz)"
short_description: Set default handler for MIME type, for applications using Gnome GIO
version_added: 7.5.0
description:
- This module allows configuring the default handler for a specific MIME type, to be used by applications built with th Gnome GIO API.
- This module allows configuring the default handler for a specific MIME type, to be used by applications built with th Gnome GIO API.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
@ -25,24 +26,28 @@ attributes:
options:
mime_type:
description:
- MIME type for which a default handler will be set.
- MIME type for which a default handler will be set.
type: str
required: true
handler:
description:
- Default handler will be set for the MIME type.
- Default handler will be set for the MIME type.
type: str
required: true
notes:
- This module is a thin wrapper around the C(gio mime) command (and subcommand).
- See man gio(1) for more details.
- This module is a thin wrapper around the C(gio mime) command (and subcommand).
- See man gio(1) for more details.
seealso:
- name: GIO Documentation
description: Reference documentation for the GIO API..
link: https://docs.gtk.org/gio/
'''
- name: C(gio) command manual page
description: Manual page for the command.
link: https://man.archlinux.org/man/gio.1
- name: GIO Documentation
description: Reference documentation for the GIO API..
link: https://docs.gtk.org/gio/
"""
EXAMPLES = """
---
- name: Set chrome as the default handler for https
community.general.gio_mime:
mime_type: x-scheme-handler/https
@ -50,26 +55,27 @@ EXAMPLES = """
register: result
"""
RETURN = '''
handler:
description:
- The handler set as default.
returned: success
type: str
sample: google-chrome.desktop
stdout:
description:
- The output of the C(gio) command.
returned: success
type: str
sample: Set google-chrome.desktop as the default for x-scheme-handler/https
stderr:
description:
- The error output of the C(gio) command.
returned: failure
type: str
sample: 'gio: Failed to load info for handler "never-existed.desktop"'
'''
RETURN = """
---
handler:
description:
- The handler set as default.
returned: success
type: str
sample: google-chrome.desktop
stdout:
description:
- The output of the C(gio) command.
returned: success
type: str
sample: Set google-chrome.desktop as the default for x-scheme-handler/https
stderr:
description:
- The error output of the C(gio) command.
returned: failure
type: str
sample: 'gio: Failed to load info for handler "never-existed.desktop"'
"""
from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
from ansible_collections.community.general.plugins.module_utils.gio_mime import gio_mime_runner, gio_mime_get

46
plugins/modules/mksysb.py
View File

@ -10,15 +10,20 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
author: Kairo Araujo (@kairoaraujo)
module: mksysb
short_description: Generates AIX mksysb rootvg backups
description:
- This module manages a basic AIX mksysb (image) of rootvg.
- This module manages a basic AIX mksysb (image) of rootvg.
seealso:
- name: C(mksysb) command manual page
description: Manual page for the command.
link: https://www.ibm.com/docs/en/aix/7.3?topic=m-mksysb-command
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
@ -27,72 +32,73 @@ attributes:
options:
backup_crypt_files:
description:
- Backup encrypted files.
- Backup encrypted files.
type: bool
default: true
backup_dmapi_fs:
description:
- Back up DMAPI filesystem files.
- Back up DMAPI filesystem files.
type: bool
default: true
create_map_files:
description:
- Creates a new MAP files.
- Creates a new MAP files.
type: bool
default: false
exclude_files:
description:
- Excludes files using C(/etc/rootvg.exclude).
- Excludes files using C(/etc/rootvg.exclude).
type: bool
default: false
exclude_wpar_files:
description:
- Excludes WPAR files.
- Excludes WPAR files.
type: bool
default: false
extended_attrs:
description:
- Backup extended attributes.
- Backup extended attributes.
type: bool
default: true
name:
type: str
description:
- Backup name
- Backup name
required: true
new_image_data:
description:
- Creates a new file data.
- Creates a new file data.
type: bool
default: true
software_packing:
description:
- Exclude files from packing option listed in
C(/etc/exclude_packing.rootvg).
- Exclude files from packing option listed in C(/etc/exclude_packing.rootvg).
type: bool
default: false
storage_path:
type: str
description:
- Storage path where the mksysb will stored.
- Storage path where the mksysb will stored.
required: true
use_snapshot:
description:
- Creates backup using snapshots.
- Creates backup using snapshots.
type: bool
default: false
'''
"""
EXAMPLES = '''
EXAMPLES = """
---
- name: Running a backup image mksysb
community.general.mksysb:
name: myserver
storage_path: /repository/images
exclude_files: true
exclude_wpar_files: true
'''
"""
RETURN = '''
RETURN = """
---
changed:
description: Return changed for mksysb actions as true or false.
returned: always
@ -101,7 +107,7 @@ msg:
description: Return message regarding the action.
returned: always
type: str
'''
"""
import os

274
plugins/modules/pipx.py
View File

@ -9,150 +9,150 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
module: pipx
short_description: Manages applications installed with pipx
version_added: 3.8.0
description:
- Manage Python applications installed in isolated virtualenvs using pipx.
- Manage Python applications installed in isolated virtualenvs using pipx.
extends_documentation_fragment:
- community.general.attributes
- community.general.pipx
- community.general.attributes
- community.general.pipx
attributes:
check_mode:
support: full
diff_mode:
support: full
check_mode:
support: full
diff_mode:
support: full
options:
state:
type: str
choices:
- present
- absent
- install
- install_all
- uninstall
- uninstall_all
- inject
- uninject
- upgrade
- upgrade_shared
- upgrade_all
- reinstall
- reinstall_all
- latest
- pin
- unpin
default: install
description:
- Desired state for the application.
- The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively.
- The state V(latest) is equivalent to executing the task twice, with state V(install) and then V(upgrade).
It was added in community.general 5.5.0.
- The states V(install_all), V(uninject), V(upgrade_shared), V(pin) and V(unpin) are only available in C(pipx>=1.6.0),
make sure to have a compatible version when using this option. These states have been added in community.general 9.4.0.
name:
type: str
description:
- 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:
- 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.
- Only used when O(state=inject).
type: bool
default: false
version_added: 6.5.0
install_deps:
description:
- Include applications of dependent packages.
- Only used when O(state=install), O(state=latest), or O(state=inject).
type: bool
default: false
inject_packages:
description:
- Packages to be injected into an existing virtual environment.
- Only used when O(state=inject).
type: list
elements: str
force:
description:
- Force modification of the application's virtual environment. See C(pipx) for details.
- Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject).
type: bool
default: false
include_injected:
description:
- Upgrade the injected packages along with the application.
- Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest).
- This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0.
type: bool
default: false
index_url:
description:
- Base URL of Python Package Index.
- Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject).
type: str
python:
description:
- Python version to be used when creating the application virtual environment. Must be 3.6+.
- Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all).
type: str
system_site_packages:
description:
- Give application virtual environment access to the system site-packages directory.
- Only used when O(state=install) or O(state=latest).
type: bool
default: false
version_added: 6.6.0
editable:
description:
- Install the project in editable mode.
type: bool
default: false
version_added: 4.6.0
pip_args:
description:
- Arbitrary arguments to pass directly to C(pip).
type: str
version_added: 4.6.0
suffix:
description:
- Optional suffix for virtual environment and executable names.
- "B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change."
type: str
version_added: 9.3.0
global:
version_added: 9.4.0
spec_metadata:
description:
- Spec metadata file for O(state=install_all).
- This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info)
with O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output).
type: path
version_added: 9.4.0
state:
type: str
choices:
- present
- absent
- install
- install_all
- uninstall
- uninstall_all
- inject
- uninject
- upgrade
- upgrade_shared
- upgrade_all
- reinstall
- reinstall_all
- latest
- pin
- unpin
default: install
description:
- Desired state for the application.
- The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively.
- The state V(latest) is equivalent to executing the task twice, with state V(install) and then V(upgrade). It was added in community.general
5.5.0.
- The states V(install_all), V(uninject), V(upgrade_shared), V(pin) and V(unpin) are only available in C(pipx>=1.6.0), make sure to have a
compatible version when using this option. These states have been added in community.general 9.4.0.
name:
type: str
description:
- 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:
- 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.
- Only used when O(state=inject).
type: bool
default: false
version_added: 6.5.0
install_deps:
description:
- Include applications of dependent packages.
- Only used when O(state=install), O(state=latest), or O(state=inject).
type: bool
default: false
inject_packages:
description:
- Packages to be injected into an existing virtual environment.
- Only used when O(state=inject).
type: list
elements: str
force:
description:
- Force modification of the application's virtual environment. See C(pipx) for details.
- Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject).
type: bool
default: false
include_injected:
description:
- Upgrade the injected packages along with the application.
- Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest).
- This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0.
type: bool
default: false
index_url:
description:
- Base URL of Python Package Index.
- Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject).
type: str
python:
description:
- Python version to be used when creating the application virtual environment. Must be 3.6+.
- Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all).
type: str
system_site_packages:
description:
- Give application virtual environment access to the system site-packages directory.
- Only used when O(state=install) or O(state=latest).
type: bool
default: false
version_added: 6.6.0
editable:
description:
- Install the project in editable mode.
type: bool
default: false
version_added: 4.6.0
pip_args:
description:
- Arbitrary arguments to pass directly to C(pip).
type: str
version_added: 4.6.0
suffix:
description:
- Optional suffix for virtual environment and executable names.
- "B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change."
type: str
version_added: 9.3.0
global:
version_added: 9.4.0
spec_metadata:
description:
- Spec metadata file for O(state=install_all).
- This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info) with
O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output).
type: path
version_added: 9.4.0
notes:
- >
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.
- >
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.
author:
- "Alexei Znamensky (@russoz)"
'''
- "Alexei Znamensky (@russoz)"
"""
EXAMPLES = '''
EXAMPLES = """
---
- name: Install tox
community.general.pipx:
name: tox
@ -181,14 +181,14 @@ EXAMPLES = '''
- name: Install multiple packages from list
vars:
pipx_packages:
- pycowsay
- black
- tox
- pycowsay
- black
- tox
community.general.pipx:
name: "{{ item }}"
state: latest
with_items: "{{ pipx_packages }}"
'''
"""
import json

77
plugins/modules/pipx_info.py
View File

@ -9,45 +9,46 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = """
---
module: pipx_info
short_description: Rretrieves information about applications installed with pipx
version_added: 5.6.0
description:
- Retrieve details about Python applications installed in isolated virtualenvs using pipx.
- Retrieve details about Python applications installed in isolated virtualenvs using pipx.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
- community.general.pipx
- community.general.attributes
- community.general.attributes.info_module
- community.general.pipx
options:
name:
description:
- Name of an application installed with C(pipx).
type: str
include_deps:
description:
- Include dependent packages in the output.
type: bool
default: false
include_injected:
description:
- Include injected packages in the output.
type: bool
default: false
include_raw:
description:
- Returns the raw output of C(pipx list --json).
- The raw output is not affected by O(include_deps) or O(include_injected).
type: bool
default: false
global:
version_added: 9.3.0
name:
description:
- Name of an application installed with C(pipx).
type: str
include_deps:
description:
- Include dependent packages in the output.
type: bool
default: false
include_injected:
description:
- Include injected packages in the output.
type: bool
default: false
include_raw:
description:
- Returns the raw output of C(pipx list --json).
- The raw output is not affected by O(include_deps) or O(include_injected).
type: bool
default: false
global:
version_added: 9.3.0
author:
- "Alexei Znamensky (@russoz)"
'''
- "Alexei Znamensky (@russoz)"
"""
EXAMPLES = '''
EXAMPLES = """
---
- name: retrieve all installed applications
community.general.pipx_info: {}
@ -65,9 +66,10 @@ EXAMPLES = '''
community.general.pipx_info:
name: ansible-lint
include_deps: true
'''
"""
RETURN = '''
RETURN = """
---
application:
description: The list of installed applications
returned: success
@ -107,15 +109,8 @@ cmd:
returned: success
type: list
elements: str
sample: [
"/usr/bin/python3.10",
"-m",
"pipx",
"list",
"--include-injected",
"--json"
]
'''
sample: ["/usr/bin/python3.10", "-m", "pipx", "list", "--include-injected", "--json"]
"""
import json

3
plugins/modules/xfconf.py
View File

@ -16,8 +16,7 @@ author:
- "Alexei Znamensky (@russoz)"
short_description: Edit XFCE4 Configurations
description:
- This module allows for the manipulation of Xfce 4 Configuration with the help of xfconf-query. Please see the xfconf-query(1) man page for more
details.
- This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query).
seealso:
- name: xfconf-query(1) man page
description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.