From c64705474d1449cd3baa702b8fc9d3534819098f Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 08:39:12 +0100 Subject: [PATCH] [PR #9372/bef82e28 backport][stable-9] p[a-e]*: normalize docs (#9396) p[a-e]*: normalize docs (#9372) * p[a-e]*: normalize docs * Update plugins/modules/packet_volume.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit bef82e28a295dcc9f932fe972d1b79f8c2f7d44b) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/pacemaker_cluster.py | 88 +++---- plugins/modules/packet_device.py | 202 +++++++------- plugins/modules/packet_ip_subnet.py | 65 +++-- plugins/modules/packet_project.py | 33 ++- plugins/modules/packet_sshkey.py | 52 ++-- plugins/modules/packet_volume.py | 58 ++-- plugins/modules/packet_volume_attachment.py | 46 ++-- plugins/modules/pacman.py | 277 ++++++++++---------- plugins/modules/pacman_key.py | 137 +++++----- plugins/modules/pagerduty.py | 138 +++++----- plugins/modules/pagerduty_alert.py | 271 ++++++++++--------- plugins/modules/pagerduty_change.py | 15 +- plugins/modules/pagerduty_user.py | 99 ++++--- plugins/modules/pam_limits.py | 60 ++--- plugins/modules/pamd.py | 97 +++---- plugins/modules/parted.py | 75 +++--- plugins/modules/pear.py | 99 ++++--- 17 files changed, 867 insertions(+), 945 deletions(-) diff --git a/plugins/modules/pacemaker_cluster.py b/plugins/modules/pacemaker_cluster.py index 60d8656ac3..af8bb5ff56 100644 --- a/plugins/modules/pacemaker_cluster.py +++ b/plugins/modules/pacemaker_cluster.py @@ -8,71 +8,59 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pacemaker_cluster short_description: Manage pacemaker clusters author: - Mathieu Bultel (@matbu) description: - - This module can manage a pacemaker cluster and nodes from Ansible using - the pacemaker cli. + - This module can manage a pacemaker cluster and nodes from Ansible using the pacemaker CLI. extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - state: - description: - - Indicate desired state of the cluster - choices: [ cleanup, offline, online, restart ] - type: str - node: - description: - - Specify which node of the cluster you want to manage. None == the - cluster status itself, 'all' == check the status of all nodes. - type: str - timeout: - description: - - Timeout when the module should considered that the action has failed - default: 300 - type: int - force: - description: - - Force the change of the cluster state - type: bool - default: true -''' -EXAMPLES = ''' ---- + state: + description: + - Indicate desired state of the cluster. + choices: [cleanup, offline, online, restart] + type: str + node: + description: + - Specify which node of the cluster you want to manage. V(null) == the cluster status itself, V(all) == check the status of all nodes. + type: str + timeout: + description: + - Timeout when the module should considered that the action has failed. + default: 300 + type: int + force: + description: + - Force the change of the cluster state. + type: bool + default: true +""" + +EXAMPLES = r""" - name: Set cluster Online hosts: localhost gather_facts: false tasks: - - name: Get cluster state - community.general.pacemaker_cluster: - state: online -''' + - name: Get cluster state + community.general.pacemaker_cluster: + state: online +""" -RETURN = ''' -changed: - description: true if the cluster state has changed - type: bool - returned: always +RETURN = r""" out: - description: The output of the current state of the cluster. It return a - list of the nodes state. - type: str - sample: 'out: [[" overcloud-controller-0", " Online"]]}' - returned: always -rc: - description: exit code of the module - type: bool - returned: always -''' + description: The output of the current state of the cluster. It returns a list of the nodes state. + type: str + sample: 'out: [[" overcloud-controller-0", " Online"]]}' + returned: always +""" import time diff --git a/plugins/modules/packet_device.py b/plugins/modules/packet_device.py index 519a7031e1..13dbbb9ff3 100644 --- a/plugins/modules/packet_device.py +++ b/plugins/modules/packet_device.py @@ -10,26 +10,23 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: packet_device short_description: Manage a bare metal server in the Packet Host description: - - Manage a bare metal server in the Packet Host (a "device" in the API terms). - - When the machine is created it can optionally wait for public IP address, or for active state. - - This module has a dependency on packet >= 1.0. - - API is documented at U(https://www.packet.net/developers/api/devices). - - + - Manage a bare metal server in the Packet Host (a "device" in the API terms). + - When the machine is created it can optionally wait for public IP address, or for active state. + - This module has a dependency on packet >= 1.0. + - API is documented at U(https://www.packet.net/developers/api/devices). author: - - Tomas Karasek (@t0mk) - - Matt Baldwin (@baldwinSPC) - - Thibaud Morel l'Horset (@teebes) + - Tomas Karasek (@t0mk) + - Matt Baldwin (@baldwinSPC) + - Thibaud Morel l'Horset (@teebes) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: @@ -45,7 +42,7 @@ options: count: description: - - The number of devices to create. Count number can be included in hostname via the %d string formatter. + - The number of devices to create. Count number can be included in hostname using the C(%d) string formatter. default: 1 type: int @@ -122,7 +119,7 @@ options: user_data: description: - - Userdata blob made available to the machine + - Userdata blob made available to the machine. type: str wait_for_public_IPv: @@ -130,7 +127,7 @@ options: - Whether to wait for the instance to be assigned a public IPv4/IPv6 address. - If set to 4, it will wait until IPv4 is assigned to the instance. - If set to 6, wait until public IPv6 is assigned to the instance. - choices: [4,6] + choices: [4, 6] type: int wait_timeout: @@ -156,11 +153,10 @@ options: requirements: - - "packet-python >= 1.35" + - "packet-python >= 1.35" +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # All the examples assume that you have your Packet API token in environment variable PACKET_API_TOKEN. # You can also pass it to the auth_token parameter of the module instead. @@ -169,13 +165,13 @@ EXAMPLES = ''' - name: Create 1 device hosts: localhost tasks: - - community.general.packet_device: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - hostnames: myserver - tags: ci-xyz - operating_system: ubuntu_16_04 - plan: baremetal_0 - facility: sjc1 + - community.general.packet_device: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + hostnames: myserver + tags: ci-xyz + operating_system: ubuntu_16_04 + plan: baremetal_0 + facility: sjc1 # Create the same device and wait until it is in state "active", (when it's # ready for other API operations). Fail if the device is not "active" in @@ -184,64 +180,64 @@ EXAMPLES = ''' - name: Create device and wait up to 10 minutes for active state hosts: localhost tasks: - - community.general.packet_device: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - hostnames: myserver - operating_system: ubuntu_16_04 - plan: baremetal_0 - facility: sjc1 - state: active - wait_timeout: 600 + - community.general.packet_device: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + hostnames: myserver + operating_system: ubuntu_16_04 + plan: baremetal_0 + facility: sjc1 + state: active + wait_timeout: 600 - name: Create 3 ubuntu devices called server-01, server-02 and server-03 hosts: localhost tasks: - - community.general.packet_device: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - hostnames: server-%02d - count: 3 - operating_system: ubuntu_16_04 - plan: baremetal_0 - facility: sjc1 + - community.general.packet_device: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + hostnames: server-%02d + count: 3 + operating_system: ubuntu_16_04 + plan: baremetal_0 + facility: sjc1 - name: Create 3 coreos devices with userdata, wait until they get IPs and then wait for SSH hosts: localhost tasks: - - name: Create 3 devices and register their facts - community.general.packet_device: - hostnames: [coreos-one, coreos-two, coreos-three] - operating_system: coreos_stable - plan: baremetal_0 - facility: ewr1 - locked: true - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - wait_for_public_IPv: 4 - user_data: | - #cloud-config - ssh_authorized_keys: - - {{ lookup('file', 'my_packet_sshkey') }} - coreos: - etcd: - discovery: https://discovery.etcd.io/6a28e078895c5ec737174db2419bb2f3 - addr: $private_ipv4:4001 - peer-addr: $private_ipv4:7001 - fleet: - public-ip: $private_ipv4 - units: - - name: etcd.service - command: start - - name: fleet.service - command: start - register: newhosts + - name: Create 3 devices and register their facts + community.general.packet_device: + hostnames: [coreos-one, coreos-two, coreos-three] + operating_system: coreos_stable + plan: baremetal_0 + facility: ewr1 + locked: true + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + wait_for_public_IPv: 4 + user_data: | + #cloud-config + ssh_authorized_keys: + - {{ lookup('file', 'my_packet_sshkey') }} + coreos: + etcd: + discovery: https://discovery.etcd.io/6a28e078895c5ec737174db2419bb2f3 + addr: $private_ipv4:4001 + peer-addr: $private_ipv4:7001 + fleet: + public-ip: $private_ipv4 + units: + - name: etcd.service + command: start + - name: fleet.service + command: start + register: newhosts - - name: Wait for ssh - ansible.builtin.wait_for: - delay: 1 - host: "{{ item.public_ipv4 }}" - port: 22 - state: started - timeout: 500 - with_items: "{{ newhosts.devices }}" + - name: Wait for ssh + ansible.builtin.wait_for: + delay: 1 + host: "{{ item.public_ipv4 }}" + port: 22 + state: started + timeout: 500 + with_items: "{{ newhosts.devices }}" # Other states of devices @@ -249,38 +245,38 @@ EXAMPLES = ''' - name: Remove 3 devices by uuid hosts: localhost tasks: - - community.general.packet_device: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - state: absent - device_ids: - - 1fb4faf8-a638-4ac7-8f47-86fe514c30d8 - - 2eb4faf8-a638-4ac7-8f47-86fe514c3043 - - 6bb4faf8-a638-4ac7-8f47-86fe514c301f -''' + - community.general.packet_device: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + state: absent + device_ids: + - 1fb4faf8-a638-4ac7-8f47-86fe514c30d8 + - 2eb4faf8-a638-4ac7-8f47-86fe514c3043 + - 6bb4faf8-a638-4ac7-8f47-86fe514c301f +""" -RETURN = ''' +RETURN = r""" changed: - description: True if a device was altered in any way (created, modified or removed) - type: bool - sample: true - returned: success + description: True if a device was altered in any way (created, modified or removed). + type: bool + sample: true + returned: success devices: - description: Information about each device that was processed - type: list - sample: - - { - "hostname": "my-server.com", - "id": "2a5122b9-c323-4d5c-b53c-9ad3f54273e7", - "public_ipv4": "147.229.15.12", - "private-ipv4": "10.0.15.12", - "tags": [], - "locked": false, - "state": "provisioning", - "public_ipv6": "2604:1380:2:5200::3" - } - returned: success -''' # NOQA + description: Information about each device that was processed + type: list + sample: + - { + "hostname": "my-server.com", + "id": "2a5122b9-c323-4d5c-b53c-9ad3f54273e7", + "public_ipv4": "147.229.15.12", + "private-ipv4": "10.0.15.12", + "tags": [], + "locked": false, + "state": "provisioning", + "public_ipv6": "2604:1380:2:5200::3" + } + returned: success +""" import os diff --git a/plugins/modules/packet_ip_subnet.py b/plugins/modules/packet_ip_subnet.py index 530cfe3a79..c2c9fcead4 100644 --- a/plugins/modules/packet_ip_subnet.py +++ b/plugins/modules/packet_ip_subnet.py @@ -10,26 +10,24 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: packet_ip_subnet short_description: Assign IP subnet to a bare metal server description: - - Assign or unassign IPv4 or IPv6 subnets to or from a device in the Packet host. - - IPv4 subnets must come from already reserved block. - - IPv6 subnets must come from publicly routable /56 block from your project. - - See U(https://support.packet.com/kb/articles/elastic-ips) for more info on IP block reservation. - + - Assign or unassign IPv4 or IPv6 subnets to or from a device in the Packet host. + - IPv4 subnets must come from already reserved block. + - IPv6 subnets must come from publicly routable /56 block from your project. + - See U(https://support.packet.com/kb/articles/elastic-ips) for more info on IP block reservation. version_added: '0.2.0' author: - - Tomas Karasek (@t0mk) - - Nurfet Becirevic (@nurfet-becirevic) + - Tomas Karasek (@t0mk) + - Nurfet Becirevic (@nurfet-becirevic) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: @@ -77,7 +75,8 @@ options: state: description: - Desired state of the IP subnet on the specified device. - - With O(state=present), you must specify either O(hostname) or O(device_id). Subnet with given CIDR will then be assigned to the specified device. + - With O(state=present), you must specify either O(hostname) or O(device_id). Subnet with given CIDR will then be assigned to the specified + device. - With O(state=absent), you can specify either O(hostname) or O(device_id). The subnet will be removed from specified devices. - If you leave both O(hostname) and O(device_id) empty, the subnet will be removed from any device it's assigned to. choices: ['present', 'absent'] @@ -85,10 +84,10 @@ options: type: str requirements: - - "packet-python >= 1.35" -''' + - "packet-python >= 1.35" +""" -EXAMPLES = ''' +EXAMPLES = r""" # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN. # You can also pass it to the auth_token parameter of the module instead. @@ -96,33 +95,33 @@ EXAMPLES = ''' hosts: localhost tasks: - - packet_device: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - hostnames: myserver - operating_system: ubuntu_16_04 - plan: baremetal_0 - facility: sjc1 - state: active + - packet_device: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + hostnames: myserver + operating_system: ubuntu_16_04 + plan: baremetal_0 + facility: sjc1 + state: active # Pick an IPv4 address from a block allocated to your project. - - community.general.packet_ip_subnet: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - hostname: myserver - cidr: "147.75.201.78/32" + - community.general.packet_ip_subnet: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + hostname: myserver + cidr: "147.75.201.78/32" # Release IP address 147.75.201.78 - name: Unassign IP address from any device in your project hosts: localhost tasks: - - community.general.packet_ip_subnet: - project_id: 89b497ee-5afc-420a-8fb5-56984898f4df - cidr: "147.75.201.78/32" - state: absent -''' + - community.general.packet_ip_subnet: + project_id: 89b497ee-5afc-420a-8fb5-56984898f4df + cidr: "147.75.201.78/32" + state: absent +""" -RETURN = ''' +RETURN = r""" changed: description: True if an IP address assignments were altered in any way (created or removed). type: bool @@ -140,7 +139,7 @@ subnet: sample: address: 147.75.90.241 address_family: 4 - assigned_to: { href : /devices/61f9aa5e-0530-47f5-97c2-113828e61ed0 } + assigned_to: {href: /devices/61f9aa5e-0530-47f5-97c2-113828e61ed0} cidr: 31 created_at: '2017-08-07T15:15:30Z' enabled: true @@ -153,7 +152,7 @@ subnet: network: 147.75.90.240 public: true returned: success -''' +""" import uuid diff --git a/plugins/modules/packet_project.py b/plugins/modules/packet_project.py index d8c991dba2..f6acdec152 100644 --- a/plugins/modules/packet_project.py +++ b/plugins/modules/packet_project.py @@ -10,24 +10,22 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: packet_project short_description: Create/delete a project in Packet host description: - - Create/delete a project in Packet host. - - API is documented at U(https://www.packet.com/developers/api/#projects). - + - Create/delete a project in Packet host. + - API is documented at U(https://www.packet.com/developers/api/#projects). version_added: '0.2.0' author: - - Tomas Karasek (@t0mk) - - Nurfet Becirevic (@nurfet-becirevic) + - Tomas Karasek (@t0mk) + - Nurfet Becirevic (@nurfet-becirevic) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: @@ -55,9 +53,9 @@ options: type: str name: - description: - - Name for/of the project. - type: str + description: + - Name for/of the project. + type: str org_id: description: @@ -76,11 +74,10 @@ options: type: str requirements: - - "packet-python >= 1.40" + - "packet-python >= 1.40" +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN. # You can also pass the api token in module param auth_token. @@ -110,9 +107,9 @@ EXAMPLES = ''' community.general.packet_project: name: "newer project" payment_method: "the other visa" -''' +""" -RETURN = ''' +RETURN = r""" changed: description: True if a project was created or removed. type: bool @@ -128,7 +125,7 @@ id: description: UUID of addressed project. type: str returned: success -''' +""" from ansible.module_utils.basic import AnsibleModule, env_fallback from ansible.module_utils.common.text.converters import to_native diff --git a/plugins/modules/packet_sshkey.py b/plugins/modules/packet_sshkey.py index 6519735dcc..8172482108 100644 --- a/plugins/modules/packet_sshkey.py +++ b/plugins/modules/packet_sshkey.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: packet_sshkey short_description: Create/delete an SSH key in Packet host description: - - Create/delete an SSH key in Packet host. - - API is documented at U(https://www.packet.net/help/api/#page:ssh-keys,header:ssh-keys-ssh-keys-post). + - Create/delete an SSH key in Packet host. + - API is documented at U(https://www.packet.net/help/api/#page:ssh-keys,header:ssh-keys-ssh-keys-post). author: "Tomas Karasek (@t0mk) " extends_documentation_fragment: - community.general.attributes @@ -26,42 +25,41 @@ attributes: options: state: description: - - Indicate desired state of the target. + - Indicate desired state of the target. default: present choices: ['present', 'absent'] type: str auth_token: description: - - Packet API token. You can also supply it in environment variable E(PACKET_API_TOKEN). + - Packet API token. You can also supply it in environment variable E(PACKET_API_TOKEN). type: str label: description: - - Label for the key. If you keep it empty, it will be read from key string. + - Label for the key. If you keep it empty, it will be read from key string. type: str aliases: [name] id: description: - - UUID of the key which you want to remove. + - UUID of the key which you want to remove. type: str fingerprint: description: - - Fingerprint of the key which you want to remove. + - Fingerprint of the key which you want to remove. type: str key: description: - - Public Key string ({type} {base64 encoded key} {description}). + - Public Key string (V({type} {base64 encoded key} {description})). type: str key_file: description: - - File with the public key. + - File with the public key. type: path requirements: - packet-python +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN. # You can also pass the api token in module param auth_token. @@ -84,27 +82,27 @@ EXAMPLES = ''' community.general.packet_sshkey: state: absent id: eef49903-7a09-4ca1-af67-4087c29ab5b6 -''' +""" -RETURN = ''' +RETURN = r""" changed: - description: True if a sshkey was created or removed. - type: bool - sample: true - returned: always + description: True if a sshkey was created or removed. + type: bool + sample: true + returned: always sshkeys: description: Information about sshkeys that were created/removed. type: list sample: [ - { - "fingerprint": "5c:93:74:7c:ed:07:17:62:28:75:79:23:d6:08:93:46", - "id": "41d61bd8-3342-428b-a09c-e67bdd18a9b7", - "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAIfNT5S0ncP4BBJBYNhNPxFF9lqVhfPeu6SM1LoCocxqDc1AT3zFRi8hjIf6TLZ2AA4FYbcAWxLMhiBxZRVldT9GdBXile78kAK5z3bKTwq152DCqpxwwbaTIggLFhsU8wrfBsPWnDuAxZ0h7mmrCjoLIE3CNLDA/NmV3iB8xMThAAAAFQCStcesSgR1adPORzBxTr7hug92LwAAAIBOProm3Gk+HWedLyE8IfofLaOeRnbBRHAOL4z0SexKkVOnQ/LGN/uDIIPGGBDYTvXgKZT+jbHeulRJ2jKgfSpGKN4JxFQ8uzVH492jEiiUJtT72Ss1dCV4PmyERVIw+f54itihV3z/t25dWgowhb0int8iC/OY3cGodlmYb3wdcQAAAIBuLbB45djZXzUkOTzzcRDIRfhaxo5WipbtEM2B1fuBt2gyrvksPpH/LK6xTjdIIb0CxPu4OCxwJG0aOz5kJoRnOWIXQGhH7VowrJhsqhIc8gN9ErbO5ea8b1L76MNcAotmBDeTUiPw01IJ8MdDxfmcsCslJKgoRKSmQpCwXQtN2g== tomk@hp2", - "label": "mynewkey33" - } + { + "fingerprint": "5c:93:74:7c:ed:07:17:62:28:75:79:23:d6:08:93:46", + "id": "41d61bd8-3342-428b-a09c-e67bdd18a9b7", + "key": "ssh-dss AAAAB3NzaC1kc3MAAACBA ... MdDxfmcsCslJKgoRKSmQpCwXQtN2g== user@server", + "label": "mynewkey33" + } ] returned: always -''' # NOQA +""" import os import uuid diff --git a/plugins/modules/packet_volume.py b/plugins/modules/packet_volume.py index 659e8d8aa3..229d63a756 100644 --- a/plugins/modules/packet_volume.py +++ b/plugins/modules/packet_volume.py @@ -9,24 +9,22 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: packet_volume short_description: Create/delete a volume in Packet host description: - - Create/delete a volume in Packet host. - - API is documented at U(https://www.packet.com/developers/api/#volumes). - + - Create/delete a volume in Packet host. + - API is documented at U(https://www.packet.com/developers/api/#volumes). version_added: '0.2.0' author: - - Tomas Karasek (@t0mk) - - Nurfet Becirevic (@nurfet-becirevic) + - Tomas Karasek (@t0mk) + - Nurfet Becirevic (@nurfet-becirevic) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: @@ -55,14 +53,13 @@ options: name: description: - - Selector for API-generated name of the volume + - Selector for API-generated name of the volume. type: str description: description: - User-defined description attribute for Packet volume. - - "It is used used as idempotent identifier - if volume with given - description exists, new one is not created." + - It is used used as idempotent identifier - if volume with given description exists, new one is not created. type: str id: @@ -72,7 +69,7 @@ options: plan: description: - - storage_1 for standard tier, storage_2 for premium (performance) tier. + - V(storage_1) for standard tier, V(storage_2) for premium (performance) tier. - Tiers are described at U(https://www.packet.com/cloud/storage/). choices: ['storage_1', 'storage_2'] default: 'storage_1' @@ -91,7 +88,7 @@ options: locked: description: - - Create new volume locked. + - Create new volume locked. type: bool default: false @@ -123,10 +120,9 @@ options: requirements: - "packet-python >= 1.35" +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN. # You can also pass the api token in module param auth_token. @@ -154,25 +150,25 @@ EXAMPLES = ''' id: "{{ result_create.id }}" project_id: "{{ project_id }}" state: absent -''' +""" -RETURN = ''' +RETURN = r""" id: - description: UUID of specified volume - type: str - returned: success - sample: 53000fb2-ee46-4673-93a8-de2c2bdba33c + description: UUID of specified volume. + type: str + returned: success + sample: 53000fb2-ee46-4673-93a8-de2c2bdba33c name: - description: The API-generated name of the volume resource. - type: str - returned: if volume is attached/detached to/from some device - sample: "volume-a91dc506" + description: The API-generated name of the volume resource. + type: str + returned: if volume is attached/detached to/from some device + sample: "volume-a91dc506" description: - description: The user-defined description of the volume resource. - type: str - returned: success - sample: "Just another volume" -''' + description: The user-defined description of the volume resource. + type: str + returned: success + sample: "Just another volume" +""" import uuid diff --git a/plugins/modules/packet_volume_attachment.py b/plugins/modules/packet_volume_attachment.py index a46fef55cb..0423cc879d 100644 --- a/plugins/modules/packet_volume_attachment.py +++ b/plugins/modules/packet_volume_attachment.py @@ -10,27 +10,24 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: packet_volume_attachment short_description: Attach/detach a volume to a device in the Packet host description: - - Attach/detach a volume to a device in the Packet host. - - API is documented at U(https://www.packet.com/developers/api/volumes/). - - "This module creates the attachment route in the Packet API. In order to discover - the block devices on the server, you have to run the Attach Scripts, - as documented at U(https://help.packet.net/technical/storage/packet-block-storage-linux)." - + - Attach/detach a volume to a device in the Packet host. + - API is documented at U(https://www.packet.com/developers/api/volumes/). + - This module creates the attachment route in the Packet API. In order to discover the block devices on the server, you have to run the Attach + Scripts, as documented at U(https://help.packet.net/technical/storage/packet-block-storage-linux). version_added: '0.2.0' author: - - Tomas Karasek (@t0mk) - - Nurfet Becirevic (@nurfet-becirevic) + - Tomas Karasek (@t0mk) + - Nurfet Becirevic (@nurfet-becirevic) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: @@ -61,7 +58,7 @@ options: description: - Selector for the volume. - It can be a UUID, an API-generated volume name, or user-defined description string. - - 'Example values: 4a347482-b546-4f67-8300-fb5018ef0c5, volume-4a347482, "my volume"' + - 'Example values: V(4a347482-b546-4f67-8300-fb5018ef0c5), V(volume-4a347482), V(my volume).' type: str required: true @@ -69,15 +66,14 @@ options: description: - Selector for the device. - It can be a UUID of the device, or a hostname. - - 'Example values: 98a14f7a-3d27-4478-b7cf-35b5670523f3, "my device"' + - 'Example values: 98a14f7a-3d27-4478-b7cf-35b5670523f3, "my device".' type: str requirements: - "packet-python >= 1.35" +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN. # You can also pass the api token in module param auth_token. @@ -122,19 +118,19 @@ EXAMPLES = ''' volume: "{{ volname }}" device: "{{ devname }}" state: absent -''' +""" -RETURN = ''' +RETURN = r""" volume_id: - description: UUID of volume addressed by the module call. - type: str - returned: success + description: UUID of volume addressed by the module call. + type: str + returned: success device_id: - description: UUID of device addressed by the module call. - type: str - returned: success -''' + description: UUID of device addressed by the module call. + type: str + returned: success +""" import uuid diff --git a/plugins/modules/pacman.py b/plugins/modules/pacman.py index f13bde317c..a4a9370ae0 100644 --- a/plugins/modules/pacman.py +++ b/plugins/modules/pacman.py @@ -12,172 +12,161 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pacman short_description: Manage packages with I(pacman) description: - - Manage packages with the I(pacman) package manager, which is used by Arch Linux and its variants. + - Manage packages with the I(pacman) package manager, which is used by Arch Linux and its variants. author: - - Indrajit Raychaudhuri (@indrajitr) - - Aaron Bull Schaefer (@elasticdog) - - Maxime de Roucy (@tchernomax) - - Jean Raby (@jraby) + - Indrajit Raychaudhuri (@indrajitr) + - Aaron Bull Schaefer (@elasticdog) + - Maxime de Roucy (@tchernomax) + - Jean Raby (@jraby) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: full + check_mode: + support: full + diff_mode: + support: full options: - name: - description: - - Name or list of names of the package(s) or file(s) to install, upgrade, or remove. - Cannot be used in combination with O(upgrade). - aliases: [ package, pkg ] - type: list - elements: str - - state: - description: - - Whether to install (V(present) or V(installed), V(latest)), or remove (V(absent) or V(removed)) a package. - - V(present) and V(installed) will simply ensure that a desired package is installed. - - V(latest) will update the specified package if it is not of the latest available version. - - V(absent) and V(removed) will remove the specified package. - default: present - choices: [ absent, installed, latest, present, removed ] - type: str - - force: - description: - - When removing packages, forcefully remove them, without any checks. - Same as O(extra_args="--nodeps --nodeps"). - - When combined with O(update_cache), force a refresh of all package databases. - Same as O(update_cache_extra_args="--refresh --refresh"). - default: false - type: bool - - remove_nosave: - description: - - When removing packages, do not save modified configuration files as C(.pacsave) files. - (passes C(--nosave) to pacman) - version_added: 4.6.0 - default: false - type: bool - - executable: - description: - - Path of the binary to use. This can either be C(pacman) or a pacman compatible AUR helper. - - Pacman compatibility is unfortunately ill defined, in particular, this modules makes - extensive use of the C(--print-format) directive which is known not to be implemented by - some AUR helpers (notably, C(yay)). - - Beware that AUR helpers might behave unexpectedly and are therefore not recommended. - default: pacman - type: str - version_added: 3.1.0 - - extra_args: - description: - - Additional option to pass to pacman when enforcing O(state). - default: '' - type: str - - update_cache: - description: - - Whether or not to refresh the master package lists. - - This can be run as part of a package installation or as a separate step. - - If not specified, it defaults to V(false). - - Please note that this option only had an influence on the module's C(changed) state - if O(name) and O(upgrade) are not specified before community.general 5.0.0. - See the examples for how to keep the old behavior. - type: bool - - update_cache_extra_args: - description: - - Additional option to pass to pacman when enforcing O(update_cache). - default: '' - type: str - - upgrade: - description: - - Whether or not to upgrade the whole system. - Cannot be used in combination with O(name). - - If not specified, it defaults to V(false). - type: bool - - upgrade_extra_args: - description: - - Additional option to pass to pacman when enforcing O(upgrade). - default: '' - type: str - - reason: - description: - - The install reason to set for the packages. - choices: [ dependency, explicit ] - type: str - version_added: 5.4.0 - - reason_for: - description: - - Set the install reason for V(all) packages or only for V(new) packages. - - In case of O(state=latest) already installed packages which will be updated to a newer version are not counted as V(new). - default: new - choices: [ all, new ] - type: str - version_added: 5.4.0 - -notes: - - When used with a C(loop:) each package will be processed individually, - it is much more efficient to pass the list directly to the O(name) option. - - To use an AUR helper (O(executable) option), a few extra setup steps might be required beforehand. - For example, a dedicated build user with permissions to install packages could be necessary. - - > - In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages - with the error: C(error: target not found: ). -""" - -RETURN = """ -packages: + name: description: - - A list of packages that have been changed. - - Before community.general 4.5.0 this was only returned when O(upgrade=true). - In community.general 4.5.0, it was sometimes omitted when the package list is empty, - but since community.general 4.6.0 it is always returned when O(name) is specified or - O(upgrade=true). - returned: success and O(name) is specified or O(upgrade=true) + - Name or list of names of the package(s) or file(s) to install, upgrade, or remove. Cannot be used in combination with O(upgrade). + aliases: [package, pkg] type: list elements: str - sample: [ package, other-package ] -cache_updated: + state: description: - - The changed status of C(pacman -Sy). - - Useful when O(name) or O(upgrade=true) are specified next to O(update_cache=true). - returned: success, when O(update_cache=true) + - Whether to install (V(present) or V(installed), V(latest)), or remove (V(absent) or V(removed)) a package. + - V(present) and V(installed) will simply ensure that a desired package is installed. + - V(latest) will update the specified package if it is not of the latest available version. + - V(absent) and V(removed) will remove the specified package. + default: present + choices: [absent, installed, latest, present, removed] + type: str + + force: + description: + - When removing packages, forcefully remove them, without any checks. Same as O(extra_args="--nodeps --nodeps"). + - When combined with O(update_cache), force a refresh of all package databases. Same as O(update_cache_extra_args="--refresh --refresh"). + default: false type: bool - sample: false + + remove_nosave: + description: + - When removing packages, do not save modified configuration files as C(.pacsave) files. (passes C(--nosave) to pacman). version_added: 4.6.0 + default: false + type: bool -stdout: + executable: description: - - Output from pacman. - returned: success, when needed + - Path of the binary to use. This can either be C(pacman) or a pacman compatible AUR helper. + - Pacman compatibility is unfortunately ill defined, in particular, this modules makes extensive use of the C(--print-format) directive + which is known not to be implemented by some AUR helpers (notably, C(yay)). + - Beware that AUR helpers might behave unexpectedly and are therefore not recommended. + default: pacman type: str - sample: ":: Synchronizing package databases... core is up to date :: Starting full system upgrade..." - version_added: 4.1.0 + version_added: 3.1.0 -stderr: + extra_args: description: - - Error output from pacman. - returned: success, when needed + - Additional option to pass to pacman when enforcing O(state). + default: '' type: str - sample: "warning: libtool: local (2.4.6+44+gb9b44533-14) is newer than core (2.4.6+42+gb88cebd5-15)\nwarning ..." - version_added: 4.1.0 + + update_cache: + description: + - Whether or not to refresh the master package lists. + - This can be run as part of a package installation or as a separate step. + - If not specified, it defaults to V(false). + - Please note that this option only had an influence on the module's C(changed) state if O(name) and O(upgrade) are not specified before + community.general 5.0.0. See the examples for how to keep the old behavior. + type: bool + + update_cache_extra_args: + description: + - Additional option to pass to pacman when enforcing O(update_cache). + default: '' + type: str + + upgrade: + description: + - Whether or not to upgrade the whole system. Cannot be used in combination with O(name). + - If not specified, it defaults to V(false). + type: bool + + upgrade_extra_args: + description: + - Additional option to pass to pacman when enforcing O(upgrade). + default: '' + type: str + + reason: + description: + - The install reason to set for the packages. + choices: [dependency, explicit] + type: str + version_added: 5.4.0 + + reason_for: + description: + - Set the install reason for V(all) packages or only for V(new) packages. + - In case of O(state=latest) already installed packages which will be updated to a newer version are not counted as V(new). + default: new + choices: [all, new] + type: str + version_added: 5.4.0 + +notes: + - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) + option. + - To use an AUR helper (O(executable) option), a few extra setup steps might be required beforehand. For example, a dedicated build user with + permissions to install packages could be necessary. + - 'In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages with the error: C(error: target not + found: ).' """ -EXAMPLES = """ +RETURN = r""" +packages: + description: + - A list of packages that have been changed. + - Before community.general 4.5.0 this was only returned when O(upgrade=true). In community.general 4.5.0, it was sometimes omitted when the + package list is empty, but since community.general 4.6.0 it is always returned when O(name) is specified or O(upgrade=true). + returned: success and O(name) is specified or O(upgrade=true) + type: list + elements: str + sample: [package, other-package] + +cache_updated: + description: + - The changed status of C(pacman -Sy). + - Useful when O(name) or O(upgrade=true) are specified next to O(update_cache=true). + returned: success, when O(update_cache=true) + type: bool + sample: false + version_added: 4.6.0 + +stdout: + description: + - Output from pacman. + returned: success, when needed + type: str + sample: ":: Synchronizing package databases... core is up to date :: Starting full system upgrade..." + version_added: 4.1.0 + +stderr: + description: + - Error output from pacman. + returned: success, when needed + type: str + sample: "warning: libtool: local (2.4.6+44+gb9b44533-14) is newer than core (2.4.6+42+gb88cebd5-15)\nwarning ..." + version_added: 4.1.0 +""" + +EXAMPLES = r""" - name: Install package foo from repo community.general.pacman: name: foo diff --git a/plugins/modules/pacman_key.py b/plugins/modules/pacman_key.py index 4b7b2639ec..f98fb6f8a3 100644 --- a/plugins/modules/pacman_key.py +++ b/plugins/modules/pacman_key.py @@ -8,84 +8,83 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pacman_key author: - - George Rawlinson (@grawlinson) + - George Rawlinson (@grawlinson) version_added: "3.2.0" short_description: Manage pacman's list of trusted keys description: - - Add or remove gpg keys from the pacman keyring. + - Add or remove gpg keys from the pacman keyring. notes: - - Use full-length key ID (40 characters). - - Keys will be verified when using O(data), O(file), or O(url) unless O(verify) is overridden. - - Keys will be locally signed after being imported into the keyring. - - If the key ID exists in the keyring, the key will not be added unless O(force_update) is specified. - - O(data), O(file), O(url), and O(keyserver) are mutually exclusive. + - Use full-length key ID (40 characters). + - Keys will be verified when using O(data), O(file), or O(url) unless O(verify) is overridden. + - Keys will be locally signed after being imported into the keyring. + - If the key ID exists in the keyring, the key will not be added unless O(force_update) is specified. + - O(data), O(file), O(url), and O(keyserver) are mutually exclusive. requirements: - - gpg - - pacman-key + - gpg + - pacman-key extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - id: - description: - - The 40 character identifier of the key. - - Including this allows check mode to correctly report the changed state. - - Do not specify a subkey ID, instead specify the primary key ID. - required: true - type: str - data: - description: - - The keyfile contents to add to the keyring. - - Must be of C(PGP PUBLIC KEY BLOCK) type. - type: str - file: - description: - - The path to a keyfile on the remote server to add to the keyring. - - Remote file must be of C(PGP PUBLIC KEY BLOCK) type. - type: path - url: - description: - - The URL to retrieve keyfile from. - - Remote file must be of C(PGP PUBLIC KEY BLOCK) type. - type: str - keyserver: - description: - - The keyserver used to retrieve key from. - type: str - verify: - description: - - Whether or not to verify the keyfile's key ID against specified key ID. - type: bool - default: true - force_update: - description: - - This forces the key to be updated if it already exists in the keyring. - type: bool - default: false - keyring: - description: - - The full path to the keyring folder on the remote server. - - If not specified, module will use pacman's default (V(/etc/pacman.d/gnupg)). - - Useful if the remote system requires an alternative gnupg directory. - type: path - default: /etc/pacman.d/gnupg - state: - description: - - Ensures that the key is present (added) or absent (revoked). - default: present - choices: [ absent, present ] - type: str -''' + id: + description: + - The 40 character identifier of the key. + - Including this allows check mode to correctly report the changed state. + - Do not specify a subkey ID, instead specify the primary key ID. + required: true + type: str + data: + description: + - The keyfile contents to add to the keyring. + - Must be of C(PGP PUBLIC KEY BLOCK) type. + type: str + file: + description: + - The path to a keyfile on the remote server to add to the keyring. + - Remote file must be of C(PGP PUBLIC KEY BLOCK) type. + type: path + url: + description: + - The URL to retrieve keyfile from. + - Remote file must be of C(PGP PUBLIC KEY BLOCK) type. + type: str + keyserver: + description: + - The keyserver used to retrieve key from. + type: str + verify: + description: + - Whether or not to verify the keyfile's key ID against specified key ID. + type: bool + default: true + force_update: + description: + - This forces the key to be updated if it already exists in the keyring. + type: bool + default: false + keyring: + description: + - The full path to the keyring folder on the remote server. + - If not specified, module will use pacman's default (V(/etc/pacman.d/gnupg)). + - Useful if the remote system requires an alternative gnupg directory. + type: path + default: /etc/pacman.d/gnupg + state: + description: + - Ensures that the key is present (added) or absent (revoked). + default: present + choices: [absent, present] + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Import a key via local file community.general.pacman_key: id: 01234567890ABCDE01234567890ABCDE12345678 @@ -119,9 +118,9 @@ EXAMPLES = ''' community.general.pacman_key: id: 01234567890ABCDE01234567890ABCDE12345678 state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ import os.path import tempfile diff --git a/plugins/modules/pagerduty.py b/plugins/modules/pagerduty.py index 853bd6d797..8d83374c34 100644 --- a/plugins/modules/pagerduty.py +++ b/plugins/modules/pagerduty.py @@ -9,84 +9,82 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: pagerduty short_description: Create PagerDuty maintenance windows description: - - This module will let you create PagerDuty maintenance windows + - This module will let you create PagerDuty maintenance windows. author: - - "Andrew Newdigate (@suprememoocow)" - - "Dylan Silva (@thaumos)" - - "Justin Johns (!UNKNOWN)" - - "Bruce Pennypacker (@bpennypacker)" + - "Andrew Newdigate (@suprememoocow)" + - "Dylan Silva (@thaumos)" + - "Justin Johns (!UNKNOWN)" + - "Bruce Pennypacker (@bpennypacker)" requirements: - - PagerDuty API access + - PagerDuty API access extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - state: - type: str - description: - - Create a maintenance window or get a list of ongoing windows. - required: true - choices: [ "running", "started", "ongoing", "absent" ] - name: - type: str - description: - - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API. - user: - type: str - description: - - PagerDuty user ID. Obsolete. Please, use O(token) for authorization. - token: - type: str - description: - - A pagerduty token, generated on the pagerduty site. It is used for authorization. - required: true - requester_id: - type: str - description: - - ID of user making the request. Only needed when creating a maintenance_window. - service: - type: list - elements: str - description: - - A comma separated list of PagerDuty service IDs. - aliases: [ services ] - window_id: - type: str - description: - - ID of maintenance window. Only needed when absent a maintenance_window. - hours: - type: str - description: - - Length of maintenance window in hours. - default: '1' - minutes: - type: str - description: - - Maintenance window in minutes (this is added to the hours). - default: '0' - desc: - type: str - description: - - Short description of maintenance window. - default: Created by Ansible - validate_certs: - description: - - If V(false), SSL certificates will not be validated. This should only be used - on personally controlled sites using self-signed certificates. - type: bool - default: true -''' + state: + type: str + description: + - Create a maintenance window or get a list of ongoing windows. + required: true + choices: ["running", "started", "ongoing", "absent"] + name: + type: str + description: + - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API. + user: + type: str + description: + - PagerDuty user ID. Obsolete. Please, use O(token) for authorization. + token: + type: str + description: + - A pagerduty token, generated on the pagerduty site. It is used for authorization. + required: true + requester_id: + type: str + description: + - ID of user making the request. Only needed when creating a maintenance_window. + service: + type: list + elements: str + description: + - A comma separated list of PagerDuty service IDs. + aliases: [services] + window_id: + type: str + description: + - ID of maintenance window. Only needed when absent a maintenance_window. + hours: + type: str + description: + - Length of maintenance window in hours. + default: '1' + minutes: + type: str + description: + - Maintenance window in minutes (this is added to the hours). + default: '0' + desc: + type: str + description: + - Short description of maintenance window. + default: Created by Ansible + validate_certs: + description: + - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. + type: bool + default: true +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List ongoing maintenance windows using a token community.general.pagerduty: name: companyabc @@ -143,7 +141,7 @@ EXAMPLES = ''' token: yourtoken state: absent window_id: "{{ pd_window.result.maintenance_windows[0].id }}" -''' +""" import datetime import json diff --git a/plugins/modules/pagerduty_alert.py b/plugins/modules/pagerduty_alert.py index 3c0327e5ab..050dcd17e9 100644 --- a/plugins/modules/pagerduty_alert.py +++ b/plugins/modules/pagerduty_alert.py @@ -8,150 +8,149 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: pagerduty_alert short_description: Trigger, acknowledge or resolve PagerDuty incidents description: - - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events + - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events. author: - - "Amanpreet Singh (@ApsOps)" - - "Xiao Shen (@xshen1)" + - "Amanpreet Singh (@ApsOps)" + - "Xiao Shen (@xshen1)" requirements: - - PagerDuty API access + - PagerDuty API access extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - type: str - description: - - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API. - api_key: - type: str - description: - - The pagerduty API key (readonly access), generated on the pagerduty site. - - Required if O(api_version=v1). - integration_key: - type: str - description: - - The GUID of one of your 'Generic API' services. - - This is the 'integration key' listed on a 'Integrations' tab of PagerDuty service. - service_id: - type: str - description: - - ID of PagerDuty service when incidents will be triggered, acknowledged or resolved. - - Required if O(api_version=v1). - service_key: - type: str - description: - - The GUID of one of your 'Generic API' services. Obsolete. Please use O(integration_key). - state: - type: str - description: - - Type of event to be sent. - required: true - choices: - - 'triggered' - - 'acknowledged' - - 'resolved' - api_version: - type: str - description: - - The API version we want to use to run the module. - - V1 is more limited with option we can provide to trigger incident. - - V2 has more variables for example, O(severity), O(source), O(custom_details), etc. - default: 'v1' - choices: - - 'v1' - - 'v2' - version_added: 7.4.0 - client: - type: str - description: - - The name of the monitoring client that is triggering this event. - required: false - client_url: - type: str - description: - - The URL of the monitoring client that is triggering this event. - required: false - component: - type: str - description: - - Component of the source machine that is responsible for the event, for example C(mysql) or C(eth0). - required: false - version_added: 7.4.0 - custom_details: - type: dict - description: - - Additional details about the event and affected system. - - A dictionary with custom keys and values. - required: false - version_added: 7.4.0 - desc: - type: str - description: - - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version) - will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. - The maximum length is 1024 characters. - - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this event. - required: false - default: Created via Ansible - incident_class: - type: str - description: - - The class/type of the event, for example C(ping failure) or C(cpu load). - required: false - version_added: 7.4.0 - incident_key: - type: str - description: - - Identifies the incident to which this O(state) should be applied. - - For O(state=triggered) - If there's no open (i.e. unresolved) incident with this key, a new one will be created. If there's already an - open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to 'de-dup' - problem reports. If no O(incident_key) is provided, then it will be generated by PagerDuty. - - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened by a - trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded. - required: false - link_url: - type: str - description: - - Relevant link url to the alert. For example, the website or the job link. - required: false - version_added: 7.4.0 - link_text: - type: str - description: - - A short description of the link_url. - required: false - version_added: 7.4.0 - source: - type: str - description: - - The unique location of the affected system, preferably a hostname or FQDN. - - Required in case of O(state=trigger) and O(api_version=v2). - required: false - version_added: 7.4.0 - severity: - type: str - description: - - The perceived severity of the status the event is describing with respect to the affected system. - - Required in case of O(state=trigger) and O(api_version=v2). - default: 'critical' - choices: - - 'critical' - - 'warning' - - 'error' - - 'info' - version_added: 7.4.0 -''' + name: + type: str + description: + - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API. + api_key: + type: str + description: + - The pagerduty API key (readonly access), generated on the pagerduty site. + - Required if O(api_version=v1). + integration_key: + type: str + description: + - The GUID of one of your 'Generic API' services. + - This is the 'integration key' listed on a 'Integrations' tab of PagerDuty service. + service_id: + type: str + description: + - ID of PagerDuty service when incidents will be triggered, acknowledged or resolved. + - Required if O(api_version=v1). + service_key: + type: str + description: + - The GUID of one of your 'Generic API' services. Obsolete. Please use O(integration_key). + state: + type: str + description: + - Type of event to be sent. + required: true + choices: + - 'triggered' + - 'acknowledged' + - 'resolved' + api_version: + type: str + description: + - The API version we want to use to run the module. + - V1 is more limited with option we can provide to trigger incident. + - V2 has more variables for example, O(severity), O(source), O(custom_details) and so on. + default: 'v1' + choices: + - 'v1' + - 'v2' + version_added: 7.4.0 + client: + type: str + description: + - The name of the monitoring client that is triggering this event. + required: false + client_url: + type: str + description: + - The URL of the monitoring client that is triggering this event. + required: false + component: + type: str + description: + - Component of the source machine that is responsible for the event, for example C(mysql) or C(eth0). + required: false + version_added: 7.4.0 + custom_details: + type: dict + description: + - Additional details about the event and affected system. + - A dictionary with custom keys and values. + required: false + version_added: 7.4.0 + desc: + type: str + description: + - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version) will + be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. The + maximum length is 1024 characters. + - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this event. + required: false + default: Created via Ansible + incident_class: + type: str + description: + - The class/type of the event, for example C(ping failure) or C(cpu load). + required: false + version_added: 7.4.0 + incident_key: + type: str + description: + - Identifies the incident to which this O(state) should be applied. + - For O(state=triggered) - If there is no open (in other words unresolved) incident with this key, a new one will be created. If there is already an + open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to 'de-dup' + problem reports. If no O(incident_key) is provided, then it will be generated by PagerDuty. + - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened + by a trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded. + required: false + link_url: + type: str + description: + - Relevant link URL to the alert. For example, the website or the job link. + required: false + version_added: 7.4.0 + link_text: + type: str + description: + - A short description of the O(link_url). + required: false + version_added: 7.4.0 + source: + type: str + description: + - The unique location of the affected system, preferably a hostname or FQDN. + - Required in case of O(state=trigger) and O(api_version=v2). + required: false + version_added: 7.4.0 + severity: + type: str + description: + - The perceived severity of the status the event is describing with respect to the affected system. + - Required in case of O(state=trigger) and O(api_version=v2). + default: 'critical' + choices: + - 'critical' + - 'warning' + - 'error' + - 'info' + version_added: 7.4.0 +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Trigger an incident with just the basic options community.general.pagerduty_alert: name: companyabc @@ -226,7 +225,7 @@ EXAMPLES = ''' integration_key: xxx incident_key: somekey state: resolved -''' +""" import json from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pagerduty_change.py b/plugins/modules/pagerduty_change.py index acd31fb447..39353f7575 100644 --- a/plugins/modules/pagerduty_change.py +++ b/plugins/modules/pagerduty_change.py @@ -8,7 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: pagerduty_change short_description: Track a code or infrastructure change as a PagerDuty change event version_added: 1.3.0 @@ -31,8 +31,7 @@ attributes: options: integration_key: description: - - The integration key that identifies the service the change was made to. - This can be found by adding an integration to a service in PagerDuty. + - The integration key that identifies the service the change was made to. This can be found by adding an integration to a service in PagerDuty. required: true type: str summary: @@ -82,14 +81,14 @@ options: type: str validate_certs: description: - - If V(false), SSL certificates for the target URL will not be validated. - This should only be used on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled sites using + self-signed certificates. required: false default: true type: bool -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Track the deployment as a PagerDuty change event community.general.pagerduty_change: integration_key: abc123abc123abc123abc123abc123ab @@ -106,7 +105,7 @@ EXAMPLES = ''' environment: production link_url: https://github.com/ansible-collections/community.general/pull/1269 link_text: View changes on GitHub -''' +""" from ansible.module_utils.urls import fetch_url from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pagerduty_user.py b/plugins/modules/pagerduty_user.py index eb8a309562..e03342c792 100644 --- a/plugins/modules/pagerduty_user.py +++ b/plugins/modules/pagerduty_user.py @@ -8,64 +8,63 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: pagerduty_user short_description: Manage a user account on PagerDuty description: - - This module manages the creation/removal of a user account on PagerDuty. + - This module manages the creation/removal of a user account on PagerDuty. version_added: '1.3.0' author: Zainab Alsaffar (@zanssa) requirements: - - pdpyras python module = 4.1.1 - - PagerDuty API Access + - pdpyras python module = 4.1.1 + - PagerDuty API Access extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - access_token: - description: - - An API access token to authenticate with the PagerDuty REST API. - required: true - type: str - pd_user: - description: - - Name of the user in PagerDuty. - required: true - type: str - pd_email: - description: - - The user's email address. - - O(pd_email) is the unique identifier used and cannot be updated using this module. - required: true - type: str - pd_role: - description: - - The user's role. - choices: ['global_admin', 'manager', 'responder', 'observer', 'stakeholder', 'limited_stakeholder', 'restricted_access'] - default: 'responder' - type: str - state: - description: - - State of the user. - - On V(present), it creates a user if the user doesn't exist. - - On V(absent), it removes a user if the account exists. - choices: ['present', 'absent'] - default: 'present' - type: str - pd_teams: - description: - - The teams to which the user belongs. - - Required if O(state=present). - type: list - elements: str -''' + access_token: + description: + - An API access token to authenticate with the PagerDuty REST API. + required: true + type: str + pd_user: + description: + - Name of the user in PagerDuty. + required: true + type: str + pd_email: + description: + - The user's email address. + - O(pd_email) is the unique identifier used and cannot be updated using this module. + required: true + type: str + pd_role: + description: + - The user's role. + choices: ['global_admin', 'manager', 'responder', 'observer', 'stakeholder', 'limited_stakeholder', 'restricted_access'] + default: 'responder' + type: str + state: + description: + - State of the user. + - On V(present), it creates a user if the user does not exist. + - On V(absent), it removes a user if the account exists. + choices: ['present', 'absent'] + default: 'present' + type: str + pd_teams: + description: + - The teams to which the user belongs. + - Required if O(state=present). + type: list + elements: str +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a user account on PagerDuty community.general.pagerduty_user: access_token: 'Your_Access_token' @@ -81,9 +80,9 @@ EXAMPLES = r''' pd_user: user_full_name pd_email: user_email state: "absent" -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from os import path from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pam_limits.py b/plugins/modules/pam_limits.py index 4ed037a6ff..516b61fec1 100644 --- a/plugins/modules/pam_limits.py +++ b/plugins/modules/pam_limits.py @@ -8,11 +8,10 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: pam_limits author: -- "Sebastien Rohaut (@usawa)" + - "Sebastien Rohaut (@usawa)" short_description: Modify Linux PAM limits description: - The M(community.general.pam_limits) module modifies PAM limits. @@ -38,32 +37,32 @@ options: description: - Limit type, see C(man 5 limits.conf) for an explanation. required: true - choices: [ "hard", "soft", "-" ] + choices: ["hard", "soft", "-"] limit_item: type: str description: - The limit to be set. required: true choices: - - "core" - - "data" - - "fsize" - - "memlock" - - "nofile" - - "rss" - - "stack" - - "cpu" - - "nproc" - - "as" - - "maxlogins" - - "maxsyslogins" - - "priority" - - "locks" - - "sigpending" - - "msgqueue" - - "nice" - - "rtprio" - - "chroot" + - "core" + - "data" + - "fsize" + - "memlock" + - "nofile" + - "rss" + - "stack" + - "cpu" + - "nproc" + - "as" + - "maxlogins" + - "maxsyslogins" + - "priority" + - "locks" + - "sigpending" + - "msgqueue" + - "nice" + - "rtprio" + - "chroot" value: type: str description: @@ -74,24 +73,21 @@ options: required: true backup: description: - - Create a backup file including the timestamp information so you can get - the original file back if you somehow clobbered it incorrectly. + - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. required: false type: bool default: false use_min: description: - If set to V(true), the minimal value will be used or conserved. - - If the specified value is inferior to the value in the file, - file content is replaced with the new value, else content is not modified. + - If the specified value is inferior to the value in the file, file content is replaced with the new value, else content is not modified. required: false type: bool default: false use_max: description: - If set to V(true), the maximal value will be used or conserved. - - If the specified value is superior to the value in the file, - file content is replaced with the new value, else content is not modified. + - If the specified value is superior to the value in the file, file content is replaced with the new value, else content is not modified. required: false type: bool default: false @@ -109,9 +105,9 @@ options: default: '' notes: - If O(dest) file does not exist, it is created. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Add or modify nofile soft limit for the user joe community.general.pam_limits: domain: joe @@ -141,7 +137,7 @@ EXAMPLES = r''' limit_type: hard limit_item: nofile value: 39693561 -''' +""" import os import re diff --git a/plugins/modules/pamd.py b/plugins/modules/pamd.py index 0ad4c8787e..6502922bc1 100644 --- a/plugins/modules/pamd.py +++ b/plugins/modules/pamd.py @@ -9,15 +9,14 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: pamd author: - - Kenneth D. Evensen (@kevensen) + - Kenneth D. Evensen (@kevensen) short_description: Manage PAM Modules description: - Edit PAM service's type, control, module path and module arguments. - - In order for a PAM rule to be modified, the type, control and - module_path must match an existing rule. See man(5) pam.d for details. + - In order for a PAM rule to be modified, the type, control and module_path must match an existing rule. See man(5) pam.d for details. notes: - This module does not handle authselect profiles. extends_documentation_fragment: @@ -30,8 +29,7 @@ attributes: options: name: description: - - The name generally refers to the PAM service file to - change, for example system-auth. + - The name generally refers to the PAM service file to change, for example system-auth. type: str required: true type: @@ -40,12 +38,11 @@ options: - The O(type), O(control), and O(module_path) options all must match a rule to be modified. type: str required: true - choices: [ account, -account, auth, -auth, password, -password, session, -session ] + choices: [account, -account, auth, -auth, password, -password, session, -session] control: description: - The control of the PAM rule being modified. - - This may be a complicated control with brackets. If this is the case, be - sure to put "[bracketed controls]" in quotes. + - This may be a complicated control with brackets. If this is the case, be sure to put "[bracketed controls]" in quotes. - The O(type), O(control), and O(module_path) options all must match a rule to be modified. type: str required: true @@ -57,55 +54,49 @@ options: required: true new_type: description: - - The new type to assign to the new rule. + - The new type to assign to the new rule. type: str - choices: [ account, -account, auth, -auth, password, -password, session, -session ] + choices: [account, -account, auth, -auth, password, -password, session, -session] new_control: description: - - The new control to assign to the new rule. + - The new control to assign to the new rule. type: str new_module_path: description: - - The new module path to be assigned to the new rule. + - The new module path to be assigned to the new rule. type: str module_arguments: description: - - When O(state=updated), the O(module_arguments) will replace existing module_arguments. - - When O(state=args_absent) args matching those listed in O(module_arguments) will be removed. - - When O(state=args_present) any args listed in O(module_arguments) are added if - missing from the existing rule. - - Furthermore, if the module argument takes a value denoted by C(=), - the value will be changed to that specified in module_arguments. + - When O(state=updated), the O(module_arguments) will replace existing module_arguments. + - When O(state=args_absent) args matching those listed in O(module_arguments) will be removed. + - When O(state=args_present) any args listed in O(module_arguments) are added if missing from the existing rule. + - Furthermore, if the module argument takes a value denoted by C(=), the value will be changed to that specified in module_arguments. type: list elements: str state: description: - - The default of V(updated) will modify an existing rule if type, - control and module_path all match an existing rule. - - With V(before), the new rule will be inserted before a rule matching type, - control and module_path. - - Similarly, with V(after), the new rule will be inserted after an existing rulematching type, - control and module_path. - - With either V(before) or V(after) O(new_type), O(new_control), and O(new_module_path) must all be specified. - - If state is V(args_absent) or V(args_present), O(new_type), O(new_control), and O(new_module_path) will be ignored. - - State V(absent) will remove the rule. + - The default of V(updated) will modify an existing rule if type, control and module_path all match an existing rule. + - With V(before), the new rule will be inserted before a rule matching type, control and module_path. + - Similarly, with V(after), the new rule will be inserted after an existing rulematching type, control and module_path. + - With either V(before) or V(after) O(new_type), O(new_control), and O(new_module_path) must all be specified. + - If state is V(args_absent) or V(args_present), O(new_type), O(new_control), and O(new_module_path) will be ignored. + - State V(absent) will remove the rule. type: str - choices: [ absent, before, after, args_absent, args_present, updated ] + choices: [absent, before, after, args_absent, args_present, updated] default: updated path: description: - - This is the path to the PAM service files. + - This is the path to the PAM service files. type: path default: /etc/pam.d backup: - description: - - Create a backup file including the timestamp information so you can - get the original file back if you somehow clobbered it incorrectly. - type: bool - default: false -''' + description: + - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. + type: bool + default: false +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Update pamd rule's control in /etc/pam.d/system-auth community.general.pamd: name: system-auth @@ -133,8 +124,7 @@ EXAMPLES = r''' new_module_path: pam_faillock.so state: before -- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an \ - existing rule pam_rootok.so +- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an existing rule pam_rootok.so community.general.pamd: name: su type: auth @@ -193,8 +183,8 @@ EXAMPLES = r''' control: '[success=1 default=ignore]' module_path: pam_succeed_if.so module_arguments: - - crond - - quiet + - crond + - quiet state: args_present - name: Module arguments requiring commas must be listed as a Yaml list @@ -204,7 +194,7 @@ EXAMPLES = r''' control: required module_path: pam_access.so module_arguments: - - listsep=, + - listsep=, state: args_present - name: Update specific argument value in a rule @@ -226,21 +216,20 @@ EXAMPLES = r''' type: auth module_path: pam_sss.so control: 'requisite' -''' +""" -RETURN = r''' +RETURN = r""" change_count: - description: How many rules were changed. - type: int - sample: 1 - returned: success + description: How many rules were changed. + type: int + sample: 1 + returned: success backupdest: - description: - - "The file name of the backup file, if created." - returned: success - type: str -... -''' + description: + - The file name of the backup file, if created. + returned: success + type: str +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/parted.py b/plugins/modules/parted.py index b3616a8ecd..43c34ff9e5 100644 --- a/plugins/modules/parted.py +++ b/plugins/modules/parted.py @@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - - Fabrizio Colonna (@ColOfAbRiX) + - Fabrizio Colonna (@ColOfAbRiX) module: parted short_description: Configure block device partitions description: - - This module allows configuring block device partition using the C(parted) - command line tool. For a full description of the fields and the options - check the GNU parted manual. + - This module allows configuring block device partition using the C(parted) command line tool. For a full description of the fields and the + options check the GNU parted manual. requirements: - This module requires C(parted) version 1.8.3 and above. - Option O(align) (except V(undefined)) requires C(parted) 2.1 or above. - - If the version of C(parted) is below 3.1, it requires a Linux version running - the C(sysfs) file system C(/sys/). + - If the version of C(parted) is below 3.1, it requires a Linux version running the C(sysfs) file system C(/sys/). - Requires the C(resizepart) command when using the O(resize) parameter. extends_documentation_fragment: - community.general.attributes @@ -36,15 +33,14 @@ options: device: description: - The block device (disk) where to operate. - - Regular files can also be partitioned, but it is recommended to create a - loopback device using C(losetup) to easily access its partitions. + - Regular files can also be partitioned, but it is recommended to create a loopback device using C(losetup) to easily access its partitions. type: str required: true align: description: - Set alignment for newly created partitions. Use V(undefined) for parted default alignment. type: str - choices: [ cylinder, minimal, none, optimal, undefined ] + choices: [cylinder, minimal, none, optimal, undefined] default: optimal number: description: @@ -53,46 +49,40 @@ options: type: int unit: description: - - Selects the current default unit that Parted will use to display - locations and capacities on the disk and to interpret those given by the - user if they are not suffixed by an unit. + - Selects the current default unit that Parted will use to display locations and capacities on the disk and to interpret those given by + the user if they are not suffixed by an unit. - When fetching information about a disk, it is recommended to always specify a unit. type: str - choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ] + choices: [s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact] default: KiB label: description: - Disk label type or partition table to use. - - If O(device) already contains a different label, it will be changed to O(label) - and any previous partitions will be lost. + - If O(device) already contains a different label, it will be changed to O(label) and any previous partitions will be lost. - A O(name) must be specified for a V(gpt) partition table. type: str - choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ] + choices: [aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun] default: msdos part_type: description: - May be specified only with O(label=msdos) or O(label=dvh). - Neither O(part_type) nor O(name) may be used with O(label=sun). type: str - choices: [ extended, logical, primary ] + choices: [extended, logical, primary] default: primary part_start: description: - - Where the partition will start as offset from the beginning of the disk, - that is, the "distance" from the start of the disk. Negative numbers - specify distance from the end of the disk. - - The distance can be specified with all the units supported by parted - (except compat) and it is case sensitive, for example V(10GiB), V(15%). + - Where the partition will start as offset from the beginning of the disk, that is, the "distance" from the start of the disk. Negative + numbers specify distance from the end of the disk. + - The distance can be specified with all the units supported by parted (except compat) and it is case sensitive, for example V(10GiB), V(15%). - Using negative values may require setting of O(fs_type) (see notes). type: str default: 0% part_end: description: - - Where the partition will end as offset from the beginning of the disk, - that is, the "distance" from the start of the disk. Negative numbers + - Where the partition will end as offset from the beginning of the disk, that is, the "distance" from the start of the disk. Negative numbers specify distance from the end of the disk. - - The distance can be specified with all the units supported by parted - (except compat) and it is case sensitive, for example V(10GiB), V(15%). + - The distance can be specified with all the units supported by parted (except compat) and it is case sensitive, for example V(10GiB), V(15%). type: str default: 100% name: @@ -108,7 +98,7 @@ options: - Whether to create or delete a partition. - If set to V(info) the module will only return the device information. type: str - choices: [ absent, present, info ] + choices: [absent, present, info] default: info fs_type: description: @@ -124,18 +114,15 @@ options: version_added: '1.3.0' notes: - - When fetching information about a new disk and when the version of parted - installed on the system is before version 3.1, the module queries the kernel - through C(/sys/) to obtain disk information. In this case the units CHS and - CYL are not supported. - - Negative O(part_start) start values were rejected if O(fs_type) was not given. - This bug was fixed in parted 3.2.153. If you want to use negative O(part_start), - specify O(fs_type) as well or make sure your system contains newer parted. -''' + - When fetching information about a new disk and when the version of parted installed on the system is before version 3.1, the module queries + the kernel through C(/sys/) to obtain disk information. In this case the units CHS and CYL are not supported. + - Negative O(part_start) start values were rejected if O(fs_type) was not given. This bug was fixed in parted 3.2.153. If you want to use negative + O(part_start), specify O(fs_type) as well or make sure your system contains newer parted. +""" -RETURN = r''' +RETURN = r""" partition_info: - description: Current partition information + description: Current partition information. returned: success type: complex contains: @@ -146,7 +133,7 @@ partition_info: description: List of device partitions. type: list script: - description: parted script executed by module + description: Parted script executed by module. type: str sample: { "disk": { @@ -177,9 +164,9 @@ partition_info: }], "script": "unit KiB print " } -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a new ext4 primary partition community.general.parted: device: /dev/sdb @@ -204,7 +191,7 @@ EXAMPLES = r''' community.general.parted: device: /dev/sdb number: 2 - flags: [ lvm ] + flags: [lvm] state: present part_start: 1GiB @@ -235,7 +222,7 @@ EXAMPLES = r''' part_end: "100%" resize: true state: present -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pear.py b/plugins/modules/pear.py index 36770de6c5..ba8f5f9ca2 100644 --- a/plugins/modules/pear.py +++ b/plugins/modules/pear.py @@ -12,54 +12,53 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pear short_description: Manage pear/pecl packages description: - - Manage PHP packages with the pear package manager. + - Manage PHP packages with the pear package manager. author: - - Jonathan Lestrelin (@jle64) + - Jonathan Lestrelin (@jle64) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - type: str - description: - - Name of the package to install, upgrade, or remove. - required: true - aliases: [pkg] - state: - type: str - description: - - Desired state of the package. - default: "present" - choices: ["present", "installed", "latest", "absent", "removed"] - executable: - type: path - description: - - Path to the pear executable. - prompts: - description: - - List of regular expressions that can be used to detect prompts during pear package installation to answer the expected question. - - Prompts will be processed in the same order as the packages list. - - You can optionally specify an answer to any question in the list. - - If no answer is provided, the list item will only contain the regular expression. - - "To specify an answer, the item will be a dict with the regular expression as key and the answer as value C(my_regular_expression: 'an_answer')." - - You can provide a list containing items with or without answer. - - A prompt list can be shorter or longer than the packages list but will issue a warning. - - If you want to specify that a package will not need prompts in the middle of a list, V(null). - type: list - elements: raw - version_added: 0.2.0 -''' + name: + type: str + description: + - Name of the package to install, upgrade, or remove. + required: true + aliases: [pkg] + state: + type: str + description: + - Desired state of the package. + default: "present" + choices: ["present", "installed", "latest", "absent", "removed"] + executable: + type: path + description: + - Path to the pear executable. + prompts: + description: + - List of regular expressions that can be used to detect prompts during pear package installation to answer the expected question. + - Prompts will be processed in the same order as the packages list. + - You can optionally specify an answer to any question in the list. + - If no answer is provided, the list item will only contain the regular expression. + - "To specify an answer, the item will be a dict with the regular expression as key and the answer as value C(my_regular_expression: 'an_answer')." + - You can provide a list containing items with or without answer. + - A prompt list can be shorter or longer than the packages list but will issue a warning. + - If you want to specify that a package will not need prompts in the middle of a list, V(null). + type: list + elements: raw + version_added: 0.2.0 +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Install pear package community.general.pear: name: Net_URL2 @@ -75,19 +74,18 @@ EXAMPLES = r''' name: pecl/apcu state: present prompts: - - (.*)Enable internal debugging in APCu \[no\] + - (.*)Enable internal debugging in APCu \[no\] - name: Install pecl package with expected prompt and an answer community.general.pear: name: pecl/apcu state: present prompts: - - (.*)Enable internal debugging in APCu \[no\]: "yes" + - (.*)Enable internal debugging in APCu \[no\]: "yes" -- name: Install multiple pear/pecl packages at once with prompts. - Prompts will be processed on the same order as the packages order. - If there is more prompts than packages, packages without prompts will be installed without any prompt expected. - If there is more packages than prompts, additional prompts will be ignored. +- name: Install multiple pear/pecl packages at once with prompts. Prompts will be processed on the same order as the packages order. If there + is more prompts than packages, packages without prompts will be installed without any prompt expected. If there is more packages than prompts, + additional prompts will be ignored. community.general.pear: name: pecl/gnupg, pecl/apcu state: present @@ -95,10 +93,9 @@ EXAMPLES = r''' - I am a test prompt because gnupg doesnt asks anything - (.*)Enable internal debugging in APCu \[no\]: "yes" -- name: Install multiple pear/pecl packages at once skipping the first prompt. - Prompts will be processed on the same order as the packages order. - If there is more prompts than packages, packages without prompts will be installed without any prompt expected. - If there is more packages than prompts, additional prompts will be ignored. +- name: Install multiple pear/pecl packages at once skipping the first prompt. Prompts will be processed on the same order as the packages order. + If there is more prompts than packages, packages without prompts will be installed without any prompt expected. If there is more packages + than prompts, additional prompts will be ignored. community.general.pear: name: pecl/gnupg, pecl/apcu state: present @@ -115,7 +112,7 @@ EXAMPLES = r''' community.general.pear: name: Net_URL2,pecl/json_post state: absent -''' +""" import os