diff --git a/plugins/modules/datadog_downtime.py b/plugins/modules/datadog_downtime.py index a3a6a660f0..f693ba3c2d 100644 --- a/plugins/modules/datadog_downtime.py +++ b/plugins/modules/datadog_downtime.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: datadog_downtime short_description: Manages Datadog downtimes version_added: 2.0.0 @@ -25,105 +24,105 @@ requirements: extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - api_key: - description: - - Your Datadog API key. - required: true - type: str - api_host: - description: - - The URL to the Datadog API. - - This value can also be set with the E(DATADOG_HOST) environment variable. - required: false - default: https://api.datadoghq.com - type: str - app_key: - description: - - Your Datadog app key. - required: true - type: str - state: - description: - - The designated state of the downtime. - required: false - choices: ["present", "absent"] - default: present - type: str - id: - description: - - The identifier of the downtime. - - If empty, a new downtime gets created, otherwise it is either updated or deleted depending of the O(state). - - To keep your playbook idempotent, you should save the identifier in a file and read it in a lookup. - type: int + api_key: + description: + - Your Datadog API key. + required: true + type: str + api_host: + description: + - The URL to the Datadog API. + - This value can also be set with the E(DATADOG_HOST) environment variable. + required: false + default: https://api.datadoghq.com + type: str + app_key: + description: + - Your Datadog app key. + required: true + type: str + state: + description: + - The designated state of the downtime. + required: false + choices: ["present", "absent"] + default: present + type: str + id: + description: + - The identifier of the downtime. + - If empty, a new downtime gets created, otherwise it is either updated or deleted depending of the O(state). + - To keep your playbook idempotent, you should save the identifier in a file and read it in a lookup. + type: int + monitor_tags: + description: + - A list of monitor tags to which the downtime applies. + - The resulting downtime applies to monitors that match ALL provided monitor tags. + type: list + elements: str + scope: + description: + - A list of scopes to which the downtime applies. + - The resulting downtime applies to sources that matches ALL provided scopes. + type: list + elements: str + monitor_id: + description: + - The ID of the monitor to mute. If not provided, the downtime applies to all monitors. + type: int + downtime_message: + description: + - A message to include with notifications for this downtime. + - Email notifications can be sent to specific users by using the same "@username" notation as events. + type: str + start: + type: int + description: + - POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created. + end: + type: int + description: + - POSIX timestamp to end the downtime. If not provided, the downtime is in effect until you cancel it. + timezone: + description: + - The timezone for the downtime. + type: str + rrule: + description: + - The C(RRULE) standard for defining recurring events. + - For example, to have a recurring event on the first day of each month, select a type of rrule and set the C(FREQ) + to C(MONTHLY) and C(BYMONTHDAY) to C(1). + - Most common rrule options from the iCalendar Spec are supported. + - Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)). + type: str +""" + +EXAMPLES = r""" +- name: Create a downtime + register: downtime_var + community.general.datadog_downtime: + state: present monitor_tags: - description: - - A list of monitor tags to which the downtime applies. - - The resulting downtime applies to monitors that match ALL provided monitor tags. - type: list - elements: str - scope: - description: - - A list of scopes to which the downtime applies. - - The resulting downtime applies to sources that matches ALL provided scopes. - type: list - elements: str - monitor_id: - description: - - The ID of the monitor to mute. If not provided, the downtime applies to all monitors. - type: int - downtime_message: - description: - - A message to include with notifications for this downtime. - - Email notifications can be sent to specific users by using the same "@username" notation as events. - type: str - start: - type: int - description: - - POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created. - end: - type: int - description: - - POSIX timestamp to end the downtime. If not provided, the downtime is in effect until you cancel it. - timezone: - description: - - The timezone for the downtime. - type: str - rrule: - description: - - The C(RRULE) standard for defining recurring events. - - For example, to have a recurring event on the first day of each month, - select a type of rrule and set the C(FREQ) to C(MONTHLY) and C(BYMONTHDAY) to C(1). - - Most common rrule options from the iCalendar Spec are supported. - - Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)). - type: str + - "foo:bar" + downtime_message: "Downtime for foo:bar" + scope: "test" + api_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + # Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created + id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}" +- name: Save downtime id to file for later updates and idempotence + delegate_to: localhost + copy: + content: "{{ downtime.downtime.id }}" + dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}" """ -EXAMPLES = """ - - name: Create a downtime - register: downtime_var - community.general.datadog_downtime: - state: present - monitor_tags: - - "foo:bar" - downtime_message: "Downtime for foo:bar" - scope: "test" - api_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" - app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" - # Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created - id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}" - - name: Save downtime id to file for later updates and idempotence - delegate_to: localhost - copy: - content: "{{ downtime.downtime.id }}" - dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}" -""" - -RETURN = """ +RETURN = r""" # Returns the downtime JSON dictionary from the API response under the C(downtime) key. # See https://docs.datadoghq.com/api/v1/downtimes/#schedule-a-downtime for more details. downtime: diff --git a/plugins/modules/datadog_event.py b/plugins/modules/datadog_event.py index 6008b565b3..97be0c9b16 100644 --- a/plugins/modules/datadog_event.py +++ b/plugins/modules/datadog_event.py @@ -14,81 +14,88 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: datadog_event short_description: Posts events to Datadog service description: - - "Allows to post events to Datadog (www.datadoghq.com) service." - - "Uses http://docs.datadoghq.com/api/#events API." + - Allows to post events to Datadog (www.datadoghq.com) service. + - Uses http://docs.datadoghq.com/api/#events API. author: - "Artūras 'arturaz' Šlajus (@arturaz)" - "Naoya Nakazawa (@n0ts)" extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - api_key: - type: str - description: ["Your DataDog API key."] - required: true - app_key: - type: str - description: ["Your DataDog app key."] - required: true - title: - type: str - description: ["The event title."] - required: true - text: - type: str - description: ["The body of the event."] - required: true - date_happened: - type: int - description: - - POSIX timestamp of the event. - - Default value is now. - priority: - type: str - description: ["The priority of the event."] - default: normal - choices: [normal, low] - host: - type: str - description: - - Host name to associate with the event. - - If not specified, it defaults to the remote system's hostname. - api_host: - type: str - description: - - DataDog API endpoint URL. - version_added: '3.3.0' - tags: - type: list - elements: str - description: ["Comma separated list of tags to apply to the event."] - alert_type: - type: str - description: ["Type of alert."] - default: info - choices: ['error', 'warning', 'info', 'success'] - aggregation_key: - type: str - description: ["An arbitrary string to use for aggregation."] - 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 -''' + api_key: + type: str + description: + - Your DataDog API key. + required: true + app_key: + type: str + description: + - Your DataDog app key. + required: true + title: + type: str + description: + - The event title. + required: true + text: + type: str + description: + - The body of the event. + required: true + date_happened: + type: int + description: + - POSIX timestamp of the event. + - Default value is now. + priority: + type: str + description: + - The priority of the event. + default: normal + choices: [normal, low] + host: + type: str + description: + - Host name to associate with the event. + - If not specified, it defaults to the remote system's hostname. + api_host: + type: str + description: + - DataDog API endpoint URL. + version_added: '3.3.0' + tags: + type: list + elements: str + description: + - Comma separated list of tags to apply to the event. + alert_type: + type: str + description: + - Type of alert. + default: info + choices: ['error', 'warning', 'info', 'success'] + aggregation_key: + type: str + description: + - An arbitrary string to use for aggregation. + 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: Post an event with low priority community.general.datadog_event: title: Testing from ansible @@ -116,8 +123,7 @@ EXAMPLES = ''' - aa - b - '#host:{{ inventory_hostname }}' - -''' +""" import platform import traceback diff --git a/plugins/modules/datadog_monitor.py b/plugins/modules/datadog_monitor.py index 75ae8c2332..eec0db0d32 100644 --- a/plugins/modules/datadog_monitor.py +++ b/plugins/modules/datadog_monitor.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: datadog_monitor short_description: Manages Datadog monitors description: @@ -21,181 +20,181 @@ requirements: [datadog] extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - api_key: - description: - - Your Datadog API key. - required: true - type: str - api_host: - description: - - The URL to the Datadog API. Default value is V(https://api.datadoghq.com). - - This value can also be set with the E(DATADOG_HOST) environment variable. - required: false - type: str - version_added: '0.2.0' - app_key: - description: - - Your Datadog app key. - required: true - type: str - state: - description: - - The designated state of the monitor. - required: true - choices: ['present', 'absent', 'mute', 'unmute'] - type: str - tags: - description: - - A list of tags to associate with your monitor when creating or updating. - - This can help you categorize and filter monitors. - type: list - elements: str - type: - description: - - The type of the monitor. - - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0. - - The type V(composite) was added in community.general 3.4.0. - - The type V(event-v2 alert) was added in community.general 4.8.0. - choices: - - metric alert - - service check - - event alert - - event-v2 alert - - process alert - - log alert - - query alert - - trace-analytics alert - - rum alert - - composite - type: str - query: - description: - - The monitor query to notify on. - - Syntax varies depending on what type of monitor you are creating. - type: str - name: - description: - - The name of the alert. - required: true - type: str - notification_message: - description: - - A message to include with notifications for this monitor. - - Email notifications can be sent to specific users by using the same '@username' notation as events. - - Monitor message template variables can be accessed by using double square brackets, i.e '[[' and ']]'. - type: str - silenced: - type: dict - description: - - Dictionary of scopes to silence, with timestamps or None. - - Each scope will be muted until the given POSIX timestamp or forever if the value is None. - notify_no_data: - description: - - Whether this monitor will notify when data stops reporting. - type: bool - default: false - no_data_timeframe: - description: - - The number of minutes before a monitor will notify when data stops reporting. - - Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks. - - If not specified, it defaults to 2x timeframe for metric, 2 minutes for service. - type: str - timeout_h: - description: - - The number of hours of the monitor not reporting data before it will automatically resolve from a triggered state. - type: str - renotify_interval: - description: - - The number of minutes after the last notification before a monitor will re-notify on the current status. - - It will only re-notify if it is not resolved. - type: str - escalation_message: - description: - - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere. - - Not applicable if O(renotify_interval=none). - type: str - notify_audit: - description: - - Whether tagged users will be notified on changes to this monitor. - type: bool - default: false - thresholds: - type: dict - description: - - A dictionary of thresholds by status. - - Only available for service checks and metric alerts. - - Because each of them can have multiple thresholds, we do not define them directly in the query. - - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})." - locked: - description: - - Whether changes to this monitor should be restricted to the creator or admins. - type: bool - default: false - require_full_window: - description: - - Whether this monitor needs a full window of data before it gets evaluated. - - We highly recommend you set this to False for sparse metrics, otherwise some evaluations will be skipped. - type: bool - new_host_delay: - description: - - A positive integer representing the number of seconds to wait before evaluating the monitor for new hosts. - - This gives the host time to fully initialize. - type: str - evaluation_delay: - description: - - Time to delay evaluation (in seconds). - - Effective for sparse values. - type: str - id: - description: - - The ID of the alert. - - If set, will be used instead of the name to locate the alert. - type: str - include_tags: - description: - - Whether notifications from this monitor automatically inserts its triggering tags into the title. - type: bool - default: true - version_added: 1.3.0 - priority: - description: - - Integer from 1 (high) to 5 (low) indicating alert severity. - type: int - version_added: 4.6.0 - notification_preset_name: - description: - - Toggles the display of additional content sent in the monitor notification. - choices: - - show_all - - hide_query - - hide_handles - - hide_all - type: str - version_added: 7.1.0 - renotify_occurrences: - description: - - The number of times re-notification messages should be sent on the current status at the provided re-notification interval. - type: int - version_added: 7.1.0 - renotify_statuses: - description: - - The types of monitor statuses for which re-notification messages are sent. - choices: - - alert - - warn - - no data - type: list - elements: str - version_added: 7.1.0 + api_key: + description: + - Your Datadog API key. + required: true + type: str + api_host: + description: + - The URL to the Datadog API. Default value is V(https://api.datadoghq.com). + - This value can also be set with the E(DATADOG_HOST) environment variable. + required: false + type: str + version_added: '0.2.0' + app_key: + description: + - Your Datadog app key. + required: true + type: str + state: + description: + - The designated state of the monitor. + required: true + choices: ['present', 'absent', 'mute', 'unmute'] + type: str + tags: + description: + - A list of tags to associate with your monitor when creating or updating. + - This can help you categorize and filter monitors. + type: list + elements: str + type: + description: + - The type of the monitor. + - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0. + - The type V(composite) was added in community.general 3.4.0. + - The type V(event-v2 alert) was added in community.general 4.8.0. + choices: + - metric alert + - service check + - event alert + - event-v2 alert + - process alert + - log alert + - query alert + - trace-analytics alert + - rum alert + - composite + type: str + query: + description: + - The monitor query to notify on. + - Syntax varies depending on what type of monitor you are creating. + type: str + name: + description: + - The name of the alert. + required: true + type: str + notification_message: + description: + - A message to include with notifications for this monitor. + - Email notifications can be sent to specific users by using the same '@username' notation as events. + - Monitor message template variables can be accessed by using double square brackets, in other words C([[) and C(]]). + type: str + silenced: + type: dict + description: + - Dictionary of scopes to silence, with timestamps or None. + - Each scope will be muted until the given POSIX timestamp or forever if the value is None. + notify_no_data: + description: + - Whether this monitor will notify when data stops reporting. + type: bool + default: false + no_data_timeframe: + description: + - The number of minutes before a monitor will notify when data stops reporting. + - Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks. + - If not specified, it defaults to 2x timeframe for metric, 2 minutes for service. + type: str + timeout_h: + description: + - The number of hours of the monitor not reporting data before it will automatically resolve from a triggered state. + type: str + renotify_interval: + description: + - The number of minutes after the last notification before a monitor will re-notify on the current status. + - It will only re-notify if it is not resolved. + type: str + escalation_message: + description: + - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere. + - Not applicable if O(renotify_interval=none). + type: str + notify_audit: + description: + - Whether tagged users will be notified on changes to this monitor. + type: bool + default: false + thresholds: + type: dict + description: + - A dictionary of thresholds by status. + - Only available for service checks and metric alerts. + - Because each of them can have multiple thresholds, we do not define them directly in the query. + - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})." + locked: + description: + - Whether changes to this monitor should be restricted to the creator or admins. + type: bool + default: false + require_full_window: + description: + - Whether this monitor needs a full window of data before it gets evaluated. + - We highly recommend you set this to False for sparse metrics, otherwise some evaluations will be skipped. + type: bool + new_host_delay: + description: + - A positive integer representing the number of seconds to wait before evaluating the monitor for new hosts. + - This gives the host time to fully initialize. + type: str + evaluation_delay: + description: + - Time to delay evaluation (in seconds). + - Effective for sparse values. + type: str + id: + description: + - The ID of the alert. + - If set, will be used instead of the name to locate the alert. + type: str + include_tags: + description: + - Whether notifications from this monitor automatically inserts its triggering tags into the title. + type: bool + default: true + version_added: 1.3.0 + priority: + description: + - Integer from V(1) (high) to V(5) (low) indicating alert severity. + type: int + version_added: 4.6.0 + notification_preset_name: + description: + - Toggles the display of additional content sent in the monitor notification. + choices: + - show_all + - hide_query + - hide_handles + - hide_all + type: str + version_added: 7.1.0 + renotify_occurrences: + description: + - The number of times re-notification messages should be sent on the current status at the provided re-notification + interval. + type: int + version_added: 7.1.0 + renotify_statuses: + description: + - The types of monitor statuses for which re-notification messages are sent. + choices: + - alert + - warn + - no data + type: list + elements: str + version_added: 7.1.0 +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a metric monitor community.general.datadog_monitor: type: "metric alert" @@ -239,7 +238,8 @@ EXAMPLES = ''' api_host: https://api.datadoghq.eu api_key: "9775a026f1ca7d1c6c5af9d94d9595a4" app_key: "87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" -''' +""" + import traceback # Import Datadog diff --git a/plugins/modules/dconf.py b/plugins/modules/dconf.py index 065cf1a6a7..ccde7191f9 100644 --- a/plugins/modules/dconf.py +++ b/plugins/modules/dconf.py @@ -9,53 +9,39 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: dconf author: - - "Branko Majic (@azaghal)" + - "Branko Majic (@azaghal)" short_description: Modify and read dconf database description: - - This module allows modifications and reading of C(dconf) database. The module - is implemented as a wrapper around C(dconf) tool. Please see the dconf(1) man - page for more details. - - Since C(dconf) requires a running D-Bus session to change values, the module - will try to detect an existing session and reuse it, or run the tool via - C(dbus-run-session). + - This module allows modifications and reading of C(dconf) database. The module is implemented as a wrapper around C(dconf) + tool. Please see the dconf(1) man page for more details. + - Since C(dconf) requires a running D-Bus session to change values, the module will try to detect an existing session and + reuse it, or run the tool using C(dbus-run-session). requirements: - - Optionally the C(gi.repository) Python library (usually included in the OS - on hosts which have C(dconf)); this will become a non-optional requirement - in a future major release of community.general. + - Optionally the C(gi.repository) Python library (usually included in the OS on hosts which have C(dconf)); this will become + a non-optional requirement in a future major release of community.general. notes: - - This module depends on C(psutil) Python library (version 4.0.0 and upwards), - C(dconf), C(dbus-send), and C(dbus-run-session) binaries. Depending on - distribution you are using, you may need to install additional packages to - have these available. - - This module uses the C(gi.repository) Python library when available for - accurate comparison of values in C(dconf) to values specified in Ansible - code. C(gi.repository) is likely to be present on most systems which have - C(dconf) but may not be present everywhere. When it is missing, a simple - string comparison between values is used, and there may be false positives, - that is, Ansible may think that a value is being changed when it is not. - This fallback will be removed in a future version of this module, at which - point the module will stop working on hosts without C(gi.repository). - - Detection of existing, running D-Bus session, required to change settings - via C(dconf), is not 100% reliable due to implementation details of D-Bus - daemon itself. This might lead to running applications not picking-up - changes on the fly if options are changed via Ansible and - C(dbus-run-session). - - Keep in mind that the C(dconf) CLI tool, which this module wraps around, - utilises an unusual syntax for the values (GVariant). For example, if you - wanted to provide a string value, the correct syntax would be - O(value="'myvalue'") - with single quotes as part of the Ansible parameter - value. - - When using loops in combination with a value like - V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible - type conversions. Applying a filter V({{ item.value | string }}) - to the parameter variable can avoid potential conversion problems. - - The easiest way to figure out exact syntax/value you need to provide for a - key is by making the configuration change in application affected by the - key, and then having a look at value set via commands C(dconf dump - /path/to/dir/) or C(dconf read /path/to/key). + - This module depends on C(psutil) Python library (version 4.0.0 and upwards), C(dconf), C(dbus-send), and C(dbus-run-session) + binaries. Depending on distribution you are using, you may need to install additional packages to have these available. + - This module uses the C(gi.repository) Python library when available for accurate comparison of values in C(dconf) to values + specified in Ansible code. C(gi.repository) is likely to be present on most systems which have C(dconf) but may not be + present everywhere. When it is missing, a simple string comparison between values is used, and there may be false positives, + that is, Ansible may think that a value is being changed when it is not. This fallback will be removed in a future version + of this module, at which point the module will stop working on hosts without C(gi.repository). + - Detection of existing, running D-Bus session, required to change settings using C(dconf), is not 100% reliable due to implementation + details of D-Bus daemon itself. This might lead to running applications not picking-up changes on-the-fly if options are + changed using Ansible and C(dbus-run-session). + - Keep in mind that the C(dconf) CLI tool, which this module wraps around, utilises an unusual syntax for the values (GVariant). + For example, if you wanted to provide a string value, the correct syntax would be O(value="'myvalue'") - with single quotes + as part of the Ansible parameter value. + - When using loops in combination with a value like V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible + type conversions. Applying a filter V({{ item.value | string }}) to the parameter variable can avoid potential conversion + problems. + - The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in + application affected by the key, and then having a look at value set using commands C(dconf dump /path/to/dir/) or C(dconf + read /path/to/key). extends_documentation_fragment: - community.general.attributes attributes: @@ -73,30 +59,27 @@ options: type: raw required: false description: - - Value to set for the specified dconf key. Value should be specified in - GVariant format. Due to complexity of this format, it is best to have a - look at existing values in the dconf database. + - Value to set for the specified dconf key. Value should be specified in GVariant format. Due to complexity of this + format, it is best to have a look at existing values in the dconf database. - Required for O(state=present). - - Although the type is specified as "raw", it should typically be - specified as a string. However, boolean values in particular are - handled properly even when specified as booleans rather than strings - (in fact, handling booleans properly is why the type of this parameter - is "raw"). + - Although the type is specified as "raw", it should typically be specified as a string. However, boolean values in + particular are handled properly even when specified as booleans rather than strings (in fact, handling booleans properly + is why the type of this parameter is "raw"). state: type: str required: false default: present - choices: [ 'read', 'present', 'absent' ] + choices: ['read', 'present', 'absent'] description: - The action to take upon the key/value. -''' +""" RETURN = r""" value: - description: value associated with the requested key - returned: success, state was "read" - type: str - sample: "'Default'" + description: Value associated with the requested key. + returned: success, state was "read" + type: str + sample: "'Default'" """ EXAMPLES = r""" diff --git a/plugins/modules/decompress.py b/plugins/modules/decompress.py index 818213fb0d..aa7a14aefb 100644 --- a/plugins/modules/decompress.py +++ b/plugins/modules/decompress.py @@ -9,18 +9,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: decompress short_description: Decompresses compressed files version_added: 10.1.0 description: - - Decompresses compressed files. - - The source (compressed) file and destination (decompressed) files are on the remote host. - - Source file can be deleted after decompression. + - Decompresses compressed files. + - The source (compressed) file and destination (decompressed) files are on the remote host. + - Source file can be deleted after decompression. extends_documentation_fragment: - - ansible.builtin.files - - community.general.attributes + - ansible.builtin.files + - community.general.attributes attributes: check_mode: support: full @@ -36,17 +35,17 @@ options: description: - The file name of the destination file where the compressed file will be decompressed. - If the destination file exists, it will be truncated and overwritten. - - If not specified, the destination filename will be derived from O(src) by removing the compression format - extension. For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be - V(/path/to/file.txt). If the O(src) file does not have an extension for the current O(format), the O(dest) - filename will be made by appending C(_decompressed) to the O(src) filename. For instance, if O(src) is - V(/path/to/file.myextension), the (dest) filename will be V(/path/to/file.myextension_decompressed). + - If not specified, the destination filename will be derived from O(src) by removing the compression format extension. + For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be V(/path/to/file.txt). If + the O(src) file does not have an extension for the current O(format), the O(dest) filename will be made by appending + C(_decompressed) to the O(src) filename. For instance, if O(src) is V(/path/to/file.myextension), the (dest) filename + will be V(/path/to/file.myextension_decompressed). type: path format: description: - The type of compression to use to decompress. type: str - choices: [ gz, bz2, xz ] + choices: [gz, bz2, xz] default: gz remove: description: @@ -54,12 +53,13 @@ options: type: bool default: false requirements: - - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python 2) if using C(xz) format. + - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python + 2) if using C(xz) format. author: - Stanislav Shamilov (@shamilovstas) -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Decompress file /path/to/file.txt.gz into /path/to/file.txt (gz compression is used by default) community.general.decompress: src: /path/to/file.txt.gz @@ -80,15 +80,15 @@ EXAMPLES = r''' src: /path/to/file.txt.gz dest: /path/to/file.txt remove: true -''' +""" -RETURN = r''' +RETURN = r""" dest: - description: Path to decompressed file + description: Path to decompressed file. type: str returned: success sample: /path/to/file.txt -''' +""" import bz2 import filecmp diff --git a/plugins/modules/deploy_helper.py b/plugins/modules/deploy_helper.py index b47ed82540..14a7d4f8c7 100644 --- a/plugins/modules/deploy_helper.py +++ b/plugins/modules/deploy_helper.py @@ -11,27 +11,19 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: deploy_helper author: "Ramon de la Fuente (@ramondelafuente)" short_description: Manages some of the steps common in deploying projects description: - - The Deploy Helper manages some of the steps common in deploying software. - It creates a folder structure, manages a symlink for the current release - and cleans up old releases. - # TODO: convert below to RETURN documentation! - - "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. - C(project_path), whatever you set in the O(path) parameter, - C(current_path), the path to the symlink that points to the active release, - C(releases_path), the path to the folder to keep releases in, - C(shared_path), the path to the folder to keep shared resources in, - C(unfinished_filename), the file to check for to recognize unfinished builds, - C(previous_release), the release the 'current' symlink is pointing to, - C(previous_release_path), the full path to the 'current' symlink target, - C(new_release), either the 'release' parameter or a generated timestamp, - C(new_release_path), the path to the new release folder (not created by the module)." - + - The Deploy Helper manages some of the steps common in deploying software. It creates a folder structure, manages a symlink + for the current release and cleans up old releases. + - Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. C(project_path), whatever + you set in the O(path) parameter, C(current_path), the path to the symlink that points to the active release, C(releases_path), + the path to the folder to keep releases in, C(shared_path), the path to the folder to keep shared resources in, C(unfinished_filename), + the file to check for to recognize unfinished builds, C(previous_release), the release the 'current' symlink is pointing + to, C(previous_release_path), the full path to the 'current' symlink target, C(new_release), either the O(release) parameter + or a generated timestamp, C(new_release_path), the path to the new release folder (not created by the module). attributes: check_mode: support: full @@ -44,42 +36,38 @@ options: required: true aliases: ['dest'] description: - - The root path of the project. - Returned in the C(deploy_helper.project_path) fact. - + - The root path of the project. Returned in the C(deploy_helper.project_path) fact. state: type: str description: - The state of the project. - V(query) will only gather facts. - V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders. - - V(finalize) will remove the unfinished_filename file, create a symlink to the newly - deployed release and optionally clean old releases. + - V(finalize) will remove the unfinished_filename file, create a symlink to the newly deployed release and optionally + clean old releases. - V(clean) will remove failed & old releases. - V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)). - choices: [ present, finalize, absent, clean, query ] + choices: [present, finalize, absent, clean, query] default: present release: type: str description: - The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)). - This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). - You can use the generated fact C(release={{ deploy_helper.new_release }}). - + This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). You can + use the generated fact C(release={{ deploy_helper.new_release }}). releases_path: type: str description: - - The name of the folder that will hold the releases. This can be relative to O(path) or absolute. - Returned in the C(deploy_helper.releases_path) fact. + - The name of the folder that will hold the releases. This can be relative to O(path) or absolute. Returned in the C(deploy_helper.releases_path) + fact. default: releases shared_path: type: path description: - - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. - If this is set to an empty string, no shared folder will be created. - Returned in the C(deploy_helper.shared_path) fact. + - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. If this is + set to an empty string, no shared folder will be created. Returned in the C(deploy_helper.shared_path) fact. default: shared current_path: @@ -92,9 +80,9 @@ options: unfinished_filename: type: str description: - - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that - contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is - automatically deleted from the C(new_release_path) during O(state=finalize). + - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that contain this + file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is automatically deleted + from the C(new_release_path) during O(state=finalize). default: DEPLOY_UNFINISHED clean: @@ -111,20 +99,18 @@ options: default: 5 notes: - - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden - parameters to both calls, otherwise the second call will overwrite the facts of the first one. - - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a - new naming strategy without problems. - - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent - unless you pass your own release name with O(release). Due to the nature of deploying software, this should not - be much of a problem. + - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden parameters + to both calls, otherwise the second call will overwrite the facts of the first one. + - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a new naming + strategy without problems. + - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent unless you + pass your own release name with O(release). Due to the nature of deploying software, this should not be much of a problem. extends_documentation_fragment: - ansible.builtin.files - community.general.attributes -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" # General explanation, starting with an example folder structure for a project: # root: @@ -192,10 +178,10 @@ EXAMPLES = ''' src: '{{ deploy_helper.shared_path }}/{{ item.src }}' state: link with_items: - - path: app/sessions - src: sessions - - path: web/uploads - src: uploads + - path: app/sessions + src: sessions + - path: web/uploads + src: uploads - name: Finalize the deploy, removing the unfinished file and switching the symlink community.general.deploy_helper: path: /path/to/root @@ -277,7 +263,8 @@ EXAMPLES = ''' path: /path/to/root - ansible.builtin.debug: var: deploy_helper -''' +""" + import os import shutil import time diff --git a/plugins/modules/dimensiondata_network.py b/plugins/modules/dimensiondata_network.py index cfb7d61cd9..6617d6aef1 100644 --- a/plugins/modules/dimensiondata_network.py +++ b/plugins/modules/dimensiondata_network.py @@ -14,8 +14,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: dimensiondata_network short_description: Create, update, and delete MCP 1.0 & 2.0 networks extends_documentation_fragment: @@ -24,7 +23,7 @@ extends_documentation_fragment: - community.general.attributes description: - - Create, update, and delete MCP 1.0 & 2.0 networks + - Create, update, and delete MCP 1.0 & 2.0 networks. author: 'Aimon Bustardo (@aimonb)' attributes: check_mode: @@ -55,9 +54,9 @@ options: choices: [present, absent] default: present type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create an MCP 1.0 network community.general.dimensiondata_network: region: na @@ -79,43 +78,43 @@ EXAMPLES = ''' location: NA1 name: mynet state: absent -''' +""" -RETURN = ''' +RETURN = r""" network: - description: Dictionary describing the network. - returned: On success when O(state=present). - type: complex - contains: - id: - description: Network ID. - type: str - sample: "8c787000-a000-4050-a215-280893411a7d" - name: - description: Network name. - type: str - sample: "My network" - description: - description: Network description. - type: str - sample: "My network description" - location: - description: Datacenter location. - type: str - sample: NA3 - status: - description: Network status. (MCP 2.0 only) - type: str - sample: NORMAL - private_net: - description: Private network subnet. (MCP 1.0 only) - type: str - sample: "10.2.3.0" - multicast: - description: Multicast enabled? (MCP 1.0 only) - type: bool - sample: false -''' + description: Dictionary describing the network. + returned: On success when O(state=present). + type: complex + contains: + id: + description: Network ID. + type: str + sample: "8c787000-a000-4050-a215-280893411a7d" + name: + description: Network name. + type: str + sample: "My network" + description: + description: Network description. + type: str + sample: "My network description" + location: + description: Datacenter location. + type: str + sample: NA3 + status: + description: Network status. (MCP 2.0 only). + type: str + sample: NORMAL + private_net: + description: Private network subnet. (MCP 1.0 only). + type: str + sample: "10.2.3.0" + multicast: + description: Multicast enabled? (MCP 1.0 only). + type: bool + sample: false +""" import traceback from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/dimensiondata_vlan.py b/plugins/modules/dimensiondata_vlan.py index 9d129f3dea..d7aa72fcf2 100644 --- a/plugins/modules/dimensiondata_vlan.py +++ b/plugins/modules/dimensiondata_vlan.py @@ -10,8 +10,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: dimensiondata_vlan short_description: Manage a VLAN in a Cloud Control network domain extends_documentation_fragment: @@ -45,32 +44,34 @@ options: type: str private_ipv4_base_address: description: - - The base address for the VLAN's IPv4 network (e.g. 192.168.1.0). + - The base address for the VLAN's IPv4 network (for example V(192.168.1.0)). type: str default: '' private_ipv4_prefix_size: description: - - The size of the IPv4 address space, e.g 24. - - Required, if O(private_ipv4_base_address) is specified. + - The size of the IPv4 address space, for example V(24). + - Required, if O(private_ipv4_base_address) is specified. type: int default: 0 state: description: - The desired state for the target VLAN. - - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist). + - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not + exist). choices: [present, absent, readonly] default: present type: str allow_expand: description: - - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses. + - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently + possesses. - If V(false), the module will fail under these conditions. - This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible). type: bool default: false -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Add or update VLAN community.general.dimensiondata_vlan: region: na @@ -100,59 +101,59 @@ EXAMPLES = ''' name: my_vlan_1 state: absent wait: true -''' +""" -RETURN = ''' +RETURN = r""" vlan: - description: Dictionary describing the VLAN. - returned: On success when O(state=present) - type: complex - contains: - id: - description: VLAN ID. - type: str - sample: "aaaaa000-a000-4050-a215-2808934ccccc" - name: - description: VLAN name. - type: str - sample: "My VLAN" - description: - description: VLAN description. - type: str - sample: "My VLAN description" - location: - description: Datacenter location. - type: str - sample: NA3 - private_ipv4_base_address: - description: The base address for the VLAN's private IPV4 network. - type: str - sample: 192.168.23.0 - private_ipv4_prefix_size: - description: The prefix size for the VLAN's private IPV4 network. - type: int - sample: 24 - private_ipv4_gateway_address: - description: The gateway address for the VLAN's private IPV4 network. - type: str - sample: 192.168.23.1 - private_ipv6_base_address: - description: The base address for the VLAN's IPV6 network. - type: str - sample: 2402:9900:111:1195:0:0:0:0 - private_ipv6_prefix_size: - description: The prefix size for the VLAN's IPV6 network. - type: int - sample: 64 - private_ipv6_gateway_address: - description: The gateway address for the VLAN's IPV6 network. - type: str - sample: 2402:9900:111:1195:0:0:0:1 - status: - description: VLAN status. - type: str - sample: NORMAL -''' + description: Dictionary describing the VLAN. + returned: On success when O(state=present) + type: complex + contains: + id: + description: VLAN ID. + type: str + sample: "aaaaa000-a000-4050-a215-2808934ccccc" + name: + description: VLAN name. + type: str + sample: "My VLAN" + description: + description: VLAN description. + type: str + sample: "My VLAN description" + location: + description: Datacenter location. + type: str + sample: NA3 + private_ipv4_base_address: + description: The base address for the VLAN's private IPV4 network. + type: str + sample: 192.168.23.0 + private_ipv4_prefix_size: + description: The prefix size for the VLAN's private IPV4 network. + type: int + sample: 24 + private_ipv4_gateway_address: + description: The gateway address for the VLAN's private IPV4 network. + type: str + sample: 192.168.23.1 + private_ipv6_base_address: + description: The base address for the VLAN's IPV6 network. + type: str + sample: 2402:9900:111:1195:0:0:0:0 + private_ipv6_prefix_size: + description: The prefix size for the VLAN's IPV6 network. + type: int + sample: 64 + private_ipv6_gateway_address: + description: The gateway address for the VLAN's IPV6 network. + type: str + sample: 2402:9900:111:1195:0:0:0:1 + status: + description: VLAN status. + type: str + sample: NORMAL +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.dimensiondata import DimensionDataModule, UnknownNetworkError diff --git a/plugins/modules/discord.py b/plugins/modules/discord.py index 130649f076..7cf05da0c1 100644 --- a/plugins/modules/discord.py +++ b/plugins/modules/discord.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: discord short_description: Send Discord messages version_added: 3.1.0 @@ -18,7 +17,7 @@ description: author: Christian Wollinger (@cwollinger) seealso: - name: API documentation - description: Documentation for Discord API + description: Documentation for Discord API. link: https://discord.com/developers/docs/resources/webhook#execute-webhook extends_documentation_fragment: - community.general.attributes @@ -31,13 +30,13 @@ options: webhook_id: description: - The webhook ID. - - "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})." + - 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).' required: true type: str webhook_token: description: - The webhook token. - - "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})." + - 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).' required: true type: str content: @@ -62,13 +61,13 @@ options: description: - Send messages as Embeds to the Discord channel. - Embeds can have a colored border, embedded images, text fields and more. - - "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)" + - 'Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object).' - At least one of O(content) and O(embeds) must be specified. type: list elements: dict -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Send a message to the Discord channel community.general.discord: webhook_id: "00000" @@ -119,7 +118,7 @@ EXAMPLES = """ timestamp: "{{ ansible_date_time.iso8601 }}" """ -RETURN = """ +RETURN = r""" http_code: description: - Response Code returned by Discord API. diff --git a/plugins/modules/django_check.py b/plugins/modules/django_check.py index 7a12ec94e2..9699428b9c 100644 --- a/plugins/modules/django_check.py +++ b/plugins/modules/django_check.py @@ -7,50 +7,49 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: django_check author: -- Alexei Znamensky (@russoz) + - Alexei Znamensky (@russoz) short_description: Wrapper for C(django-admin check) version_added: 9.1.0 description: -- This module is a wrapper for the execution of C(django-admin check). + - This module is a wrapper for the execution of C(django-admin check). extends_documentation_fragment: -- community.general.attributes -- community.general.django + - community.general.attributes + - community.general.django options: database: description: - - Specify databases to run checks against. - - If not specified, Django will not run database tests. + - Specify databases to run checks against. + - If not specified, Django will not run database tests. type: list elements: str deploy: description: - - Include additional checks relevant in a deployment setting. + - Include additional checks relevant in a deployment setting. type: bool default: false fail_level: description: - - Message level that will trigger failure. - - Default is the Django default value. Check the documentation for the version being used. + - Message level that will trigger failure. + - Default is the Django default value. Check the documentation for the version being used. type: str choices: [CRITICAL, ERROR, WARNING, INFO, DEBUG] tags: description: - - Restrict checks to specific tags. + - Restrict checks to specific tags. type: list elements: str apps: description: - - Restrict checks to specific applications. - - Default is to check all applications. + - Restrict checks to specific applications. + - Default is to check all applications. type: list elements: str notes: -- The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc). -- The module will fail if RV(ignore:rc) is not zero. + - The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc). + - The module will fail if RV(ignore:rc) is not zero. attributes: check_mode: support: full @@ -58,8 +57,7 @@ attributes: support: none """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Check the entire project community.general.django_check: settings: myproject.settings @@ -67,15 +65,14 @@ EXAMPLES = """ - name: Create the project using specific databases community.general.django_check: database: - - somedb - - myotherdb + - somedb + - myotherdb settings: fancysite.settings pythonpath: /home/joedoe/project/fancysite venv: /home/joedoe/project/fancysite/venv """ -RETURN = """ ---- +RETURN = r""" run_info: description: Command-line execution information. type: dict diff --git a/plugins/modules/django_command.py b/plugins/modules/django_command.py index 2d6d36ad74..72cffb5c9c 100644 --- a/plugins/modules/django_command.py +++ b/plugins/modules/django_command.py @@ -7,18 +7,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: django_command author: -- Alexei Znamensky (@russoz) + - Alexei Znamensky (@russoz) short_description: Run Django admin commands version_added: 9.0.0 description: -- This module allows the execution of arbitrary Django admin commands. + - This module allows the execution of arbitrary Django admin commands. extends_documentation_fragment: -- community.general.attributes -- community.general.django + - community.general.attributes + - community.general.django attributes: check_mode: support: none @@ -27,18 +26,17 @@ attributes: options: command: description: - - Django admin command. It must be a valid command accepted by C(python -m django) at the target system. + - Django admin command. It must be a valid command accepted by C(python -m django) at the target system. type: str required: true extra_args: type: list elements: str description: - - List of extra arguments passed to the django admin command. + - List of extra arguments passed to the django admin command. """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Check the project community.general.django_command: command: check @@ -52,8 +50,7 @@ EXAMPLES = """ venv: /home/joedoe/project/fancysite/venv """ -RETURN = """ ---- +RETURN = r""" run_info: description: Command-line execution information. type: dict diff --git a/plugins/modules/django_createcachetable.py b/plugins/modules/django_createcachetable.py index 85f5774294..4d849624a9 100644 --- a/plugins/modules/django_createcachetable.py +++ b/plugins/modules/django_createcachetable.py @@ -7,19 +7,18 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: django_createcachetable author: -- Alexei Znamensky (@russoz) + - Alexei Znamensky (@russoz) short_description: Wrapper for C(django-admin createcachetable) version_added: 9.1.0 description: -- This module is a wrapper for the execution of C(django-admin createcachetable). + - This module is a wrapper for the execution of C(django-admin createcachetable). extends_documentation_fragment: -- community.general.attributes -- community.general.django -- community.general.django.database + - community.general.attributes + - community.general.django + - community.general.django.database attributes: check_mode: support: full @@ -27,8 +26,7 @@ attributes: support: none """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Create cache table in the default database community.general.django_createcachetable: settings: myproject.settings @@ -41,8 +39,7 @@ EXAMPLES = """ venv: /home/joedoe/project/fancysite/venv """ -RETURN = """ ---- +RETURN = r""" run_info: description: Command-line execution information. type: dict diff --git a/plugins/modules/django_manage.py b/plugins/modules/django_manage.py index 352bfe4b50..dab544a29d 100644 --- a/plugins/modules/django_manage.py +++ b/plugins/modules/django_manage.py @@ -10,13 +10,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: django_manage short_description: Manages a Django application description: - - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the - O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation. + - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the O(virtualenv) parameter, + all management commands will be executed by the given C(virtualenv) installation. extends_documentation_fragment: - community.general.attributes attributes: @@ -27,17 +26,18 @@ attributes: options: command: description: - - The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation. + - The name of the Django management command to run. The commands listed below are built in this module and have some + basic parameter validation. - V(collectstatic) - Collects the static files into C(STATIC_ROOT). - V(createcachetable) - Creates the cache tables for use with the database cache backend. - V(flush) - Removes all data from the database. - V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database. - V(migrate) - Synchronizes the database state with models and migrations. - V(test) - Runs tests for all installed apps. - - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may - prompt for user input should be run with the C(--noinput) flag. - - Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0. - See note about supported versions of Django. + - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may prompt for user + input should be run with the C(--noinput) flag. + - Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0. See note about supported + versions of Django. type: str required: true project_path: @@ -53,8 +53,8 @@ options: required: false pythonpath: description: - - A directory to add to the Python path. Typically used to include the settings module if it is located - external to the application directory. + - A directory to add to the Python path. Typically used to include the settings module if it is located external to + the application directory. - This would be equivalent to adding O(pythonpath)'s value to the E(PYTHONPATH) environment variable. type: path required: false @@ -84,8 +84,7 @@ options: type: bool database: description: - - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), - and V(migrate) commands. + - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), and V(migrate) commands. type: str required: false failfast: @@ -107,14 +106,13 @@ options: type: bool merge: description: - - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this - parameter with V(migrate) command. + - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this parameter with + V(migrate) command. required: false type: bool link: description: - - Will create links to the files instead of copying them, you can only use this parameter with - V(collectstatic) command. + - Will create links to the files instead of copying them, you can only use this parameter with V(collectstatic) command. required: false type: bool testrunner: @@ -132,20 +130,17 @@ options: version_added: 5.8.0 notes: - - > - B(ATTENTION): Support for Django releases older than 4.1 has been removed in - community.general version 9.0.0. While the module allows for free-form commands - does not verify the version of Django being used, it is B(strongly recommended) - to use a more recent version of Django. + - 'B(ATTENTION): Support for Django releases older than 4.1 has been removed in community.general version 9.0.0. While the + module allows for free-form commands, not verifying the version of Django being used, it is B(strongly recommended) to + use a more recent version of the framework.' - Please notice that Django 4.1 requires Python 3.8 or greater. - - This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment - does not already exist at the given location. This behavior changed in community.general version 9.0.0. + - This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not + already exist at the given location. This behavior changed in community.general version 9.0.0. - The recommended way to create a virtual environment in Ansible is by using M(ansible.builtin.pip). - - This module assumes English error messages for the V(createcachetable) command to detect table existence, - unfortunately. + - This module assumes English error messages for the V(createcachetable) command to detect table existence, unfortunately. - To be able to use the V(collectstatic) command, you must have enabled C(staticfiles) in your settings. - - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, - for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. + - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, for example C(#!/usr/bin/env + python), for invoking the appropriate Python interpreter. seealso: - name: django-admin and manage.py Reference description: Reference for C(django-admin) or C(manage.py) commands. @@ -156,13 +151,13 @@ seealso: - name: What Python version can I use with Django? description: From the Django FAQ, the response to Python requirements for the framework. link: https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django -requirements: [ "django >= 4.1" ] +requirements: ["django >= 4.1"] author: - Alexei Znamensky (@russoz) - Scott Anderson (@tastychutney) -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Run cleanup on the application installed in django_dir community.general.django_manage: command: clearsessions diff --git a/plugins/modules/dnf_config_manager.py b/plugins/modules/dnf_config_manager.py index aa2571d9f0..2d896f3742 100644 --- a/plugins/modules/dnf_config_manager.py +++ b/plugins/modules/dnf_config_manager.py @@ -7,8 +7,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: dnf_config_manager short_description: Enable or disable dnf repositories using config-manager version_added: 8.2.0 @@ -43,9 +42,9 @@ options: seealso: - module: ansible.builtin.dnf - module: ansible.builtin.yum_repository -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure the crb repository is enabled community.general.dnf_config_manager: name: crb @@ -57,9 +56,9 @@ EXAMPLES = r''' - appstream - zfs state: disabled -''' +""" -RETURN = r''' +RETURN = r""" repo_states_pre: description: Repo IDs before action taken. returned: success @@ -115,12 +114,12 @@ repo_states_post: - crb-debug - crb-source changed_repos: - description: Repositories changed. - returned: success - type: list - elements: str - sample: [ 'crb' ] -''' + description: Repositories changed. + returned: success + type: list + elements: str + sample: ['crb'] +""" from ansible.module_utils.basic import AnsibleModule import os diff --git a/plugins/modules/dnf_versionlock.py b/plugins/modules/dnf_versionlock.py index 3fcf132eaf..07a85c11c2 100644 --- a/plugins/modules/dnf_versionlock.py +++ b/plugins/modules/dnf_versionlock.py @@ -7,37 +7,32 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: dnf_versionlock version_added: '4.0.0' short_description: Locks package versions in C(dnf) based systems description: -- Locks package versions using the C(versionlock) plugin in C(dnf) based - systems. This plugin takes a set of name and versions for packages and - excludes all other versions of those packages. This allows you to for example - protect packages from being updated by newer versions. The state of the - plugin that reflects locking of packages is the C(locklist). + - Locks package versions using the C(versionlock) plugin in C(dnf) based systems. This plugin takes a set of name and versions + for packages and excludes all other versions of those packages. This allows you to for example protect packages from being + updated by newer versions. The state of the plugin that reflects locking of packages is the C(locklist). extends_documentation_fragment: - community.general.attributes attributes: check_mode: support: partial details: - - The logics of the C(versionlock) plugin for corner cases could be - confusing, so please take in account that this module will do its best to - give a C(check_mode) prediction on what is going to happen. In case of - doubt, check the documentation of the plugin. - - Sometimes the module could predict changes in C(check_mode) that will not - be such because C(versionlock) concludes that there is already a entry in - C(locklist) that already matches. + - The logics of the C(versionlock) plugin for corner cases could be confusing, so please take in account that this module + will do its best to give a C(check_mode) prediction on what is going to happen. In case of doubt, check the documentation + of the plugin. + - Sometimes the module could predict changes in C(check_mode) that will not be such because C(versionlock) concludes + that there is already a entry in C(locklist) that already matches. diff_mode: support: none options: name: description: - - Package name spec to add or exclude to or delete from the C(locklist) - using the format expected by the C(dnf repoquery) command. + - Package name spec to add or exclude to or delete from the C(locklist) using the format expected by the C(dnf repoquery) + command. - This parameter is mutually exclusive with O(state=clean). type: list required: false @@ -45,43 +40,34 @@ options: default: [] raw: description: - - Do not resolve package name specs to NEVRAs to find specific version - to lock to. Instead the package name specs are used as they are. This - enables locking to not yet available versions of the package. + - Do not resolve package name specs to NEVRAs to find specific version to lock to. Instead the package name specs are + used as they are. This enables locking to not yet available versions of the package. type: bool default: false state: description: - - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or - V(clean)) from the C(locklist). - - V(present) will add a package name spec to the C(locklist). If there is a - installed package that matches, then only that version will be added. - Otherwise, all available package versions will be added. - - V(excluded) will add a package name spec as excluded to the - C(locklist). It means that packages represented by the package name - spec will be excluded from transaction operations. All available - package versions will be added. - - V(absent) will delete entries in the C(locklist) that match the - package name spec. - - V(clean) will delete all entries in the C(locklist). This option is - mutually exclusive with O(name). - choices: [ 'absent', 'clean', 'excluded', 'present' ] + - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or V(clean)) from the C(locklist). + - V(present) will add a package name spec to the C(locklist). If there is a installed package that matches, then only + that version will be added. Otherwise, all available package versions will be added. + - V(excluded) will add a package name spec as excluded to the C(locklist). It means that packages represented by the + package name spec will be excluded from transaction operations. All available package versions will be added. + - V(absent) will delete entries in the C(locklist) that match the package name spec. + - V(clean) will delete all entries in the C(locklist). This option is mutually exclusive with O(name). + choices: ['absent', 'clean', 'excluded', 'present'] type: str default: present notes: - - In an ideal world, the C(versionlock) plugin would have a dry-run option to - know for sure what is going to happen. So far we have to work with a best - guess as close as possible to the behaviour inferred from its code. - - For most of cases where you want to lock and unlock specific versions of a - package, this works fairly well. + - In an ideal world, the C(versionlock) plugin would have a dry-run option to know for sure what is going to happen. So + far we have to work with a best guess as close as possible to the behaviour inferred from its code. + - For most of cases where you want to lock and unlock specific versions of a package, this works fairly well. requirements: - dnf - dnf-plugin-versionlock author: - Roberto Moreda (@moreda) -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Prevent installed nginx from being updated community.general.dnf_versionlock: name: nginx @@ -113,34 +99,34 @@ EXAMPLES = r''' - name: Delete all entries in the locklist of versionlock community.general.dnf_versionlock: state: clean -''' +""" -RETURN = r''' +RETURN = r""" locklist_pre: - description: Locklist before module execution. - returned: success - type: list - elements: str - sample: [ 'bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*' ] + description: Locklist before module execution. + returned: success + type: list + elements: str + sample: ['bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*'] locklist_post: - description: Locklist after module execution. - returned: success and (not check mode or state is clean) - type: list - elements: str - sample: [ 'bash-0:4.4.20-1.el8_4.*' ] + description: Locklist after module execution. + returned: success and (not check mode or state is clean) + type: list + elements: str + sample: ['bash-0:4.4.20-1.el8_4.*'] specs_toadd: - description: Package name specs meant to be added by versionlock. - returned: success - type: list - elements: str - sample: [ 'bash' ] + description: Package name specs meant to be added by versionlock. + returned: success + type: list + elements: str + sample: ['bash'] specs_todelete: - description: Package name specs meant to be deleted by versionlock. - returned: success - type: list - elements: str - sample: [ 'bind' ] -''' + description: Package name specs meant to be deleted by versionlock. + returned: success + type: list + elements: str + sample: ['bind'] +""" from ansible.module_utils.basic import AnsibleModule import fnmatch diff --git a/plugins/modules/dnsimple.py b/plugins/modules/dnsimple.py index c5829e36eb..c72208f5c5 100644 --- a/plugins/modules/dnsimple.py +++ b/plugins/modules/dnsimple.py @@ -10,12 +10,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: dnsimple short_description: Interface with dnsimple.com (a DNS hosting service) description: - - "Manages domains and records via the DNSimple API, see the docs: U(http://developer.dnsimple.com/)." + - 'Manages domains and records using the DNSimple API, see the docs: U(http://developer.dnsimple.com/).' extends_documentation_fragment: - community.general.attributes attributes: @@ -27,8 +26,8 @@ options: account_email: description: - Account email. If omitted, the environment variables E(DNSIMPLE_EMAIL) and E(DNSIMPLE_API_TOKEN) will be looked for. - - "If those aren't found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)." - - "C(.dnsimple) config files are only supported in dnsimple-python<2.0.0" + - "If those variables are not found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)." + - C(.dnsimple) config files are only supported in dnsimple-python<2.0.0. type: str account_api_token: description: @@ -36,9 +35,9 @@ options: type: str domain: description: - - Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNSimple. + - Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNSimple. - If omitted, a list of domains will be returned. - - If domain is present but the domain doesn't exist, it will be created. + - If domain is present but the domain does not exist, it will be created. type: str record: description: @@ -52,7 +51,8 @@ options: type: description: - The type of DNS record to create. - choices: [ 'A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL', 'CAA' ] + choices: ['A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL', + 'CAA'] type: str ttl: description: @@ -70,8 +70,8 @@ options: type: int state: description: - - whether the record should exist or not. - choices: [ 'present', 'absent' ] + - Whether the record should exist or not. + choices: ['present', 'absent'] default: present type: str solo: @@ -91,9 +91,9 @@ options: requirements: - "dnsimple >= 2.0.0" author: "Alex Coomans (@drcapulet)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Authenticate using email and API token and fetch all domains community.general.dnsimple: account_email: test@example.com @@ -149,7 +149,7 @@ EXAMPLES = ''' value: example.com state: absent delegate_to: localhost -''' +""" RETURN = r"""# """ diff --git a/plugins/modules/dnsimple_info.py b/plugins/modules/dnsimple_info.py index 46c2877f73..c508525fac 100644 --- a/plugins/modules/dnsimple_info.py +++ b/plugins/modules/dnsimple_info.py @@ -9,8 +9,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: dnsimple_info short_description: Pull basic info from DNSimple API @@ -20,45 +19,45 @@ version_added: "4.2.0" description: Retrieve existing records and domains from DNSimple API. extends_documentation_fragment: - - community.general.attributes - - community.general.attributes.info_module + - community.general.attributes + - community.general.attributes.info_module options: - name: - description: - - The domain name to retrieve info from. - - Will return all associated records for this domain if specified. - - If not specified, will return all domains associated with the account ID. - type: str + name: + description: + - The domain name to retrieve info from. + - Will return all associated records for this domain if specified. + - If not specified, will return all domains associated with the account ID. + type: str - account_id: - description: The account ID to query. - required: true - type: str + account_id: + description: The account ID to query. + required: true + type: str - api_key: - description: The API key to use. - required: true - type: str + api_key: + description: The API key to use. + required: true + type: str - record: - description: - - The record to find. - - If specified, only this record will be returned instead of all records. - required: false - type: str + record: + description: + - The record to find. + - If specified, only this record will be returned instead of all records. + required: false + type: str - sandbox: - description: Whether or not to use sandbox environment. - required: false - default: false - type: bool + sandbox: + description: Whether or not to use sandbox environment. + required: false + default: false + type: bool author: - - Edward Hilgendorf (@edhilgendorf) -''' + - Edward Hilgendorf (@edhilgendorf) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Get all domains from an account community.general.dnsimple_info: account_id: "1234" @@ -76,15 +75,15 @@ EXAMPLES = r''' record: "subdomain" account_id: "1234" api_key: "1234" -''' +""" -RETURN = r''' +RETURN = r""" dnsimple_domain_info: - description: Returns a list of dictionaries of all domains associated with the supplied account ID. - type: list - elements: dict - returned: success when O(name) is not specified - sample: + description: Returns a list of dictionaries of all domains associated with the supplied account ID. + type: list + elements: dict + returned: success when O(name) is not specified + sample: - account_id: 1234 created_at: '2021-10-16T21:25:42Z' id: 123456 @@ -93,41 +92,41 @@ dnsimple_domain_info: reverse: false secondary: false updated_at: '2021-11-10T20:22:50Z' - contains: - account_id: - description: The account ID. - type: int - created_at: - description: When the domain entry was created. - type: str - id: - description: ID of the entry. - type: int - last_transferred_at: - description: Date the domain was transferred, or empty if not. - type: str - name: - description: Name of the record. - type: str - reverse: - description: Whether or not it is a reverse zone record. - type: bool - updated_at: - description: When the domain entry was updated. - type: str + contains: + account_id: + description: The account ID. + type: int + created_at: + description: When the domain entry was created. + type: str + id: + description: ID of the entry. + type: int + last_transferred_at: + description: Date the domain was transferred, or empty if not. + type: str + name: + description: Name of the record. + type: str + reverse: + description: Whether or not it is a reverse zone record. + type: bool + updated_at: + description: When the domain entry was updated. + type: str dnsimple_records_info: - description: Returns a list of dictionaries with all records for the domain supplied. - type: list - elements: dict - returned: success when O(name) is specified, but O(record) is not - sample: + description: Returns a list of dictionaries with all records for the domain supplied. + type: list + elements: dict + returned: success when O(name) is specified, but O(record) is not + sample: - content: ns1.dnsimple.com admin.dnsimple.com created_at: '2021-10-16T19:07:34Z' id: 12345 name: 'catheadbiscuit' - parent_id: null - priority: null + parent_id: + priority: regions: - global system_record: true @@ -135,55 +134,55 @@ dnsimple_records_info: type: SOA updated_at: '2021-11-15T23:55:51Z' zone_id: example.com - contains: - content: - description: Content of the returned record. - type: str - created_at: - description: When the domain entry was created. - type: str - id: - description: ID of the entry. - type: int - name: - description: Name of the record. - type: str - parent_id: - description: Parent record or null. - type: int - priority: - description: Priority setting of the record. - type: str - regions: - description: List of regions where the record is available. - type: list - system_record: - description: Whether or not it is a system record. - type: bool - ttl: - description: Record TTL. - type: int - type: - description: Record type. - type: str - updated_at: - description: When the domain entry was updated. - type: str - zone_id: - description: ID of the zone that the record is associated with. - type: str + contains: + content: + description: Content of the returned record. + type: str + created_at: + description: When the domain entry was created. + type: str + id: + description: ID of the entry. + type: int + name: + description: Name of the record. + type: str + parent_id: + description: Parent record or null. + type: int + priority: + description: Priority setting of the record. + type: str + regions: + description: List of regions where the record is available. + type: list + system_record: + description: Whether or not it is a system record. + type: bool + ttl: + description: Record TTL. + type: int + type: + description: Record type. + type: str + updated_at: + description: When the domain entry was updated. + type: str + zone_id: + description: ID of the zone that the record is associated with. + type: str dnsimple_record_info: - description: Returns a list of dictionaries that match the record supplied. - returned: success when O(name) and O(record) are specified - type: list - elements: dict - sample: + description: Returns a list of dictionaries that match the record supplied. + returned: success when O(name) and O(record) are specified + type: list + elements: dict + sample: - content: 1.2.3.4 created_at: '2021-11-15T23:55:51Z' id: 123456 name: catheadbiscuit - parent_id: null - priority: null + parent_id: + priority: regions: - global system_record: false @@ -191,44 +190,44 @@ dnsimple_record_info: type: A updated_at: '2021-11-15T23:55:51Z' zone_id: example.com - contains: - content: - description: Content of the returned record. - type: str - created_at: - description: When the domain entry was created. - type: str - id: - description: ID of the entry. - type: int - name: - description: Name of the record. - type: str - parent_id: - description: Parent record or null. - type: int - priority: - description: Priority setting of the record. - type: str - regions: - description: List of regions where the record is available. - type: list - system_record: - description: Whether or not it is a system record. - type: bool - ttl: - description: Record TTL. - type: int - type: - description: Record type. - type: str - updated_at: - description: When the domain entry was updated. - type: str - zone_id: - description: ID of the zone that the record is associated with. - type: str -''' + contains: + content: + description: Content of the returned record. + type: str + created_at: + description: When the domain entry was created. + type: str + id: + description: ID of the entry. + type: int + name: + description: Name of the record. + type: str + parent_id: + description: Parent record or null. + type: int + priority: + description: Priority setting of the record. + type: str + regions: + description: List of regions where the record is available. + type: list + system_record: + description: Whether or not it is a system record. + type: bool + ttl: + description: Record TTL. + type: int + type: + description: Record type. + type: str + updated_at: + description: When the domain entry was updated. + type: str + zone_id: + description: ID of the zone that the record is associated with. + type: str +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils import deps diff --git a/plugins/modules/dnsmadeeasy.py b/plugins/modules/dnsmadeeasy.py index 47d9430e7b..742d50c3f2 100644 --- a/plugins/modules/dnsmadeeasy.py +++ b/plugins/modules/dnsmadeeasy.py @@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: dnsmadeeasy short_description: Interface with dnsmadeeasy.com (a DNS hosting service) description: - - > - Manages DNS records via the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation of domains or - monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/) + - 'Manages DNS records using the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation + of domains or monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/).' extends_documentation_fragment: - community.general.attributes attributes: @@ -39,8 +37,8 @@ options: domain: description: - - Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNS Made Easy (e.g. "839989") for faster - resolution + - Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNS Made Easy + (for example V(839989)) for faster resolution. required: true type: str @@ -52,49 +50,47 @@ options: record_name: description: - - Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned in "result" regardless - of the state argument. + - Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned + in "result" regardless of the state argument. type: str record_type: description: - Record type. - choices: [ 'A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT' ] + choices: ['A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT'] type: str record_value: description: - - > - Record value. HTTPRED: , MX: , NS: , PTR: , - SRV: , TXT: " - - > - If record_value is not specified; no changes will be made and the record will be returned in 'result' - (in other words, this module can be used to fetch a record's current id, type, and ttl) + - 'Record value. HTTPRED: , MX: , NS: , PTR: , SRV: + , TXT: ".' + - If record_value is not specified; no changes will be made and the record will be returned in 'result' (in other words, + this module can be used to fetch a record's current id, type, and ttl). type: str record_ttl: description: - - record's "Time to live". Number of seconds the record remains cached in DNS servers. + - Record's "Time-To-Live". Number of seconds the record remains cached in DNS servers. default: 1800 type: int state: description: - - whether the record should exist or not + - Whether the record should exist or not. required: true - choices: [ 'present', 'absent' ] + choices: ['present', 'absent'] type: str 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. + - 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 monitor: description: - - If V(true), add or change the monitor. This is applicable only for A records. + - If V(true), add or change the monitor. This is applicable only for A records. type: bool default: false @@ -153,7 +149,7 @@ options: failover: description: - - If V(true), add or change the failover. This is applicable only for A records. + - If V(true), add or change the failover. This is applicable only for A records. type: bool default: false @@ -192,20 +188,19 @@ options: type: str notes: - - The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure you are within a few - seconds of actual time by using NTP. - - This module returns record(s) and monitor(s) in the "result" element when 'state' is set to 'present'. - These values can be be registered and used in your playbooks. + - The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure + you are within a few seconds of actual time by using NTP. + - This module returns record(s) and monitor(s) in the "result" element when O(state=present). These values can + be be registered and used in your playbooks. - Only A records can have a monitor or failover. - - To add failover, the 'failover', 'autoFailover', 'port', 'protocol', 'ip1', and 'ip2' options are required. - - To add monitor, the 'monitor', 'port', 'protocol', 'maxEmails', 'systemDescription', and 'ip1' options are required. - - The monitor and the failover will share 'port', 'protocol', and 'ip1' options. - -requirements: [ hashlib, hmac ] + - To add failover, the O(failover), O(autoFailover), O(port), O(protocol), O(ip1), and O(ip2) options are required. + - To add monitor, the O(monitor), O(port), O(protocol), O(maxEmails), O(systemDescription), and O(ip1) options are required. + - The monitor and the failover will share O(port), O(protocol), and O(ip1) options. +requirements: [hashlib, hmac] author: "Brice Burgess (@briceburg)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Fetch my.com domain records community.general.dnsmadeeasy: account_key: key @@ -291,8 +286,8 @@ EXAMPLES = ''' record_value: 127.0.0.1 monitor: true ip1: 127.0.0.2 - protocol: HTTP # default - port: 80 # default + protocol: HTTP # default + port: 80 # default maxEmails: 1 systemDescription: Monitor Test A record contactList: my contact list @@ -308,11 +303,11 @@ EXAMPLES = ''' record_value: 127.0.0.1 monitor: true ip1: 127.0.0.2 - protocol: HTTP # default - port: 80 # default + protocol: HTTP # default + port: 80 # default maxEmails: 1 systemDescription: Monitor Test A record - contactList: 1174 # contact list id + contactList: 1174 # contact list id httpFqdn: http://my.com httpFile: example httpQueryString: some string @@ -357,7 +352,7 @@ EXAMPLES = ''' record_type: A record_value: 127.0.0.1 monitor: false -''' +""" # ============================================ # DNSMadeEasy module specific support methods. diff --git a/plugins/modules/dpkg_divert.py b/plugins/modules/dpkg_divert.py index 5f0d924fe2..d74d8ba039 100644 --- a/plugins/modules/dpkg_divert.py +++ b/plugins/modules/dpkg_divert.py @@ -9,24 +9,20 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: dpkg_divert short_description: Override a debian package's version of a file version_added: '0.2.0' author: - quidame (@quidame) description: - - A diversion is for C(dpkg) the knowledge that only a given package - (or the local administrator) is allowed to install a file at a given - location. Other packages shipping their own version of this file will - be forced to O(divert) it, that is to install it at another location. It - allows one to keep changes in a file provided by a debian package by - preventing its overwrite at package upgrade. - - This module manages diversions of debian packages files using the - C(dpkg-divert) commandline tool. It can either create or remove a - diversion for a given file, but also update an existing diversion - to modify its O(holder) and/or its O(divert) location. + - A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install + a file at a given location. Other packages shipping their own version of this file will be forced to O(divert) it, that + is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing + its overwrite at package upgrade. + - This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create + or remove a diversion for a given file, but also update an existing diversion to modify its O(holder) and/or its O(divert) + location. extends_documentation_fragment: - community.general.attributes attributes: @@ -37,28 +33,23 @@ attributes: options: path: description: - - The original and absolute path of the file to be diverted or - undiverted. This path is unique, i.e. it is not possible to get - two diversions for the same O(path). + - The original and absolute path of the file to be diverted or undiverted. This path is unique, in other words it is not possible + to get two diversions for the same O(path). required: true type: path state: description: - - When O(state=absent), remove the diversion of the specified - O(path); when O(state=present), create the diversion if it does - not exist, or update its package O(holder) or O(divert) location, - if it already exists. + - When O(state=absent), remove the diversion of the specified O(path); when O(state=present), create the diversion if + it does not exist, or update its package O(holder) or O(divert) location, if it already exists. type: str default: present choices: [absent, present] holder: description: - - The name of the package whose copy of file is not diverted, also - known as the diversion holder or the package the diversion belongs - to. - - The actual package does not have to be installed or even to exist - for its name to be valid. If not specified, the diversion is hold - by 'LOCAL', that is reserved by/for dpkg for local diversions. + - The name of the package whose copy of file is not diverted, also known as the diversion holder or the package the + diversion belongs to. + - The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the + diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions. - This parameter is ignored when O(state=absent). type: str divert: @@ -69,28 +60,25 @@ options: type: path rename: description: - - Actually move the file aside (when O(state=present)) or back (when - O(state=absent)), but only when changing the state of the diversion. - This parameter has no effect when attempting to add a diversion that - already exists or when removing an unexisting one. - - Unless O(force=true), renaming fails if the destination file already - exists (this lock being a dpkg-divert feature, and bypassing it being - a module feature). + - Actually move the file aside (when O(state=present)) or back (when O(state=absent)), but only when changing the state + of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing + an unexisting one. + - Unless O(force=true), renaming fails if the destination file already exists (this lock being a dpkg-divert feature, + and bypassing it being a module feature). type: bool default: false force: description: - - When O(rename=true) and O(force=true), renaming is performed even if - the target of the renaming exists, i.e. the existing contents of the - file at this location will be lost. + - When O(rename=true) and O(force=true), renaming is performed even if the target of the renaming exists, in other words the existing + contents of the file at this location will be lost. - This parameter is ignored when O(rename=false). type: bool default: false requirements: - dpkg-divert >= 1.15.0 (Debian family) -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Divert /usr/bin/busybox to /usr/bin/busybox.distrib and keep file in place community.general.dpkg_divert: path: /usr/bin/busybox @@ -112,9 +100,9 @@ EXAMPLES = r''' state: absent rename: true force: true -''' +""" -RETURN = r''' +RETURN = r""" commands: description: The dpkg-divert commands ran internally by the module. type: list @@ -151,7 +139,7 @@ diversion: "path": "/etc/foobarrc", "state": "present" } -''' +""" import re diff --git a/plugins/modules/easy_install.py b/plugins/modules/easy_install.py index 2e8fc2f4f0..734f0dc4df 100644 --- a/plugins/modules/easy_install.py +++ b/plugins/modules/easy_install.py @@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: easy_install short_description: Installs Python libraries description: - - Installs Python libraries, optionally in a C(virtualenv) + - Installs Python libraries, optionally in a C(virtualenv). extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -31,31 +30,25 @@ options: virtualenv: type: str description: - - An optional O(virtualenv) directory path to install into. If the - O(virtualenv) does not exist, it is created automatically. + - An optional O(virtualenv) directory path to install into. If the O(virtualenv) does not exist, it is created automatically. virtualenv_site_packages: description: - - Whether the virtual environment will inherit packages from the - global site-packages directory. Note that if this setting is - changed on an already existing virtual environment it will not - have any effect, the environment must be deleted and newly - created. + - Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting + is changed on an already existing virtual environment it will not have any effect, the environment must be deleted + and newly created. type: bool default: false virtualenv_command: type: str description: - - The command to create the virtual environment with. For example - V(pyvenv), V(virtualenv), V(virtualenv2). + - The command to create the virtual environment with. For example V(pyvenv), V(virtualenv), V(virtualenv2). default: virtualenv executable: type: str description: - - The explicit executable or a pathname to the executable to be used to - run easy_install for a specific version of Python installed in the - system. For example V(easy_install-3.3), if there are both Python 2.7 - and 3.3 installations in the system and you want to run easy_install - for the Python 3.3 installation. + - The explicit executable or a pathname to the executable to be used to run easy_install for a specific version of Python + installed in the system. For example V(easy_install-3.3), if there are both Python 2.7 and 3.3 installations in the + system and you want to run easy_install for the Python 3.3 installation. default: easy_install state: type: str @@ -64,17 +57,14 @@ options: choices: [present, latest] default: present notes: - - Please note that the C(easy_install) module can only install Python - libraries. Thus this module is not able to remove libraries. It is - generally recommended to use the M(ansible.builtin.pip) module which you can first install - using M(community.general.easy_install). - - Also note that C(virtualenv) must be installed on the remote host if the - O(virtualenv) parameter is specified. -requirements: [ "virtualenv" ] + - Please note that the C(easy_install) module can only install Python libraries. Thus this module is not able to remove + libraries. It is generally recommended to use the M(ansible.builtin.pip) module which you can first install using M(community.general.easy_install). + - Also note that C(virtualenv) must be installed on the remote host if the O(virtualenv) parameter is specified. +requirements: ["virtualenv"] author: "Matt Wright (@mattupstate)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install or update pip community.general.easy_install: name: pip @@ -84,7 +74,7 @@ EXAMPLES = ''' community.general.easy_install: name: bottle virtualenv: /webapps/myapp/venv -''' +""" import os import os.path diff --git a/plugins/modules/ejabberd_user.py b/plugins/modules/ejabberd_user.py index b43e078a5d..f93612a516 100644 --- a/plugins/modules/ejabberd_user.py +++ b/plugins/modules/ejabberd_user.py @@ -9,51 +9,50 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ejabberd_user author: "Peter Sprygada (@privateip)" short_description: Manages users for ejabberd servers requirements: - - ejabberd with mod_admin_extra + - ejabberd with mod_admin_extra description: - - This module provides user management for ejabberd servers + - This module provides user management for ejabberd servers. 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: - username: - type: str - description: - - the name of the user to manage - required: true - host: - type: str - description: - - the ejabberd host associated with this username - required: true - password: - type: str - description: - - the password to assign to the username - required: false - state: - type: str - description: - - describe the desired state of the user to be managed - required: false - default: 'present' - choices: [ 'present', 'absent' ] + username: + type: str + description: + - The name of the user to manage. + required: true + host: + type: str + description: + - The ejabberd host associated with this username. + required: true + password: + type: str + description: + - The password to assign to the username. + required: false + state: + type: str + description: + - Describe the desired state of the user to be managed. + required: false + default: 'present' + choices: ['present', 'absent'] notes: - - Password parameter is required for state == present only - - Passwords must be stored in clear text for this release - - The ejabberd configuration file must include mod_admin_extra as a module. -''' -EXAMPLES = ''' + - Password parameter is required for O(state=present) only. + - Passwords must be stored in clear text for this release. + - The ejabberd configuration file must include mod_admin_extra as a module. +""" +EXAMPLES = r""" # Example playbook entries using the ejabberd_user module to manage users state. - name: Create a user if it does not exist @@ -67,7 +66,7 @@ EXAMPLES = ''' username: test host: server state: absent -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt diff --git a/plugins/modules/elasticsearch_plugin.py b/plugins/modules/elasticsearch_plugin.py index 92b628a740..f7b73b8323 100644 --- a/plugins/modules/elasticsearch_plugin.py +++ b/plugins/modules/elasticsearch_plugin.py @@ -9,88 +9,85 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: elasticsearch_plugin short_description: Manage Elasticsearch plugins description: - - Manages Elasticsearch plugins. + - Manages Elasticsearch plugins. author: - - Mathew Davies (@ThePixelDeveloper) - - Sam Doran (@samdoran) + - Mathew Davies (@ThePixelDeveloper) + - Sam Doran (@samdoran) 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: - description: - - Name of the plugin to install. - required: true - type: str - state: - description: - - Desired state of a plugin. - choices: ["present", "absent"] - default: present - type: str - src: - description: - - Optionally set the source location to retrieve the plugin from. This can be a file:// - URL to install from a local file, or a remote URL. If this is not set, the plugin - location is just based on the name. - - The name parameter must match the descriptor in the plugin ZIP specified. - - Is only used if the state would change, which is solely checked based on the name - parameter. If, for example, the plugin is already installed, changing this has no - effect. - - For ES 1.x use url. - required: false - type: str - url: - description: - - Set exact URL to download the plugin from (Only works for ES 1.x). - - For ES 2.x and higher, use src. - required: false - type: str - timeout: - description: - - "Timeout setting: 30s, 1m, 1h..." - - Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0. - default: 1m - type: str - force: - description: - - "Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console detection fails." - default: false - type: bool - plugin_bin: - description: - - Location of the plugin binary. If this file is not found, the default plugin binaries will be used. - type: path - plugin_dir: - description: - - Your configured plugin directory specified in Elasticsearch - default: /usr/share/elasticsearch/plugins/ - type: path - proxy_host: - description: - - Proxy host to use during plugin installation - type: str - proxy_port: - description: - - Proxy port to use during plugin installation - type: str - version: - description: - - Version of the plugin to be installed. - If plugin exists with previous version, it will NOT be updated - type: str -''' + name: + description: + - Name of the plugin to install. + required: true + type: str + state: + description: + - Desired state of a plugin. + choices: ["present", "absent"] + default: present + type: str + src: + description: + - Optionally set the source location to retrieve the plugin from. This can be a C(file://) URL to install from a local + file, or a remote URL. If this is not set, the plugin location is just based on the name. + - The name parameter must match the descriptor in the plugin ZIP specified. + - Is only used if the state would change, which is solely checked based on the name parameter. If, for example, the + plugin is already installed, changing this has no effect. + - For ES 1.x use O(url). + required: false + type: str + url: + description: + - Set exact URL to download the plugin from (Only works for ES 1.x). + - For ES 2.x and higher, use src. + required: false + type: str + timeout: + description: + - 'Timeout setting: V(30s), V(1m), V(1h)...' + - Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0. + default: 1m + type: str + force: + description: + - Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console + detection fails. + default: false + type: bool + plugin_bin: + description: + - Location of the plugin binary. If this file is not found, the default plugin binaries will be used. + type: path + plugin_dir: + description: + - Your configured plugin directory specified in Elasticsearch. + default: /usr/share/elasticsearch/plugins/ + type: path + proxy_host: + description: + - Proxy host to use during plugin installation. + type: str + proxy_port: + description: + - Proxy port to use during plugin installation. + type: str + version: + description: + - Version of the plugin to be installed. If plugin exists with previous version, it will NOT be updated. + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install Elasticsearch Head plugin in Elasticsearch 2.x community.general.elasticsearch_plugin: name: mobz/elasticsearch-head @@ -116,7 +113,7 @@ EXAMPLES = ''' name: ingest-geoip state: present force: true -''' +""" import os diff --git a/plugins/modules/emc_vnx_sg_member.py b/plugins/modules/emc_vnx_sg_member.py index b06cd01de3..cbdb0f4442 100644 --- a/plugins/modules/emc_vnx_sg_member.py +++ b/plugins/modules/emc_vnx_sg_member.py @@ -12,52 +12,50 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: emc_vnx_sg_member short_description: Manage storage group member on EMC VNX description: - - "This module manages the members of an existing storage group." - + - This module manages the members of an existing storage group. extends_documentation_fragment: - - community.general.emc.emc_vnx - - community.general.attributes + - community.general.emc.emc_vnx + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - description: - - Name of the Storage group to manage. - required: true - type: str - lunid: - description: - - Lun id to be added. - required: true - type: int - state: - description: - - Indicates the desired lunid state. - - V(present) ensures specified lunid is present in the Storage Group. - - V(absent) ensures specified lunid is absent from Storage Group. - default: present - choices: [ "present", "absent"] - type: str + name: + description: + - Name of the Storage group to manage. + required: true + type: str + lunid: + description: + - Lun id to be added. + required: true + type: int + state: + description: + - Indicates the desired lunid state. + - V(present) ensures specified O(lunid) is present in the Storage Group. + - V(absent) ensures specified O(lunid) is absent from Storage Group. + default: present + choices: ["present", "absent"] + type: str author: - - Luca 'remix_tj' Lorenzetto (@remixtj) -''' + - Luca 'remix_tj' Lorenzetto (@remixtj) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Add lun to storage group community.general.emc_vnx_sg_member: name: sg01 @@ -75,14 +73,14 @@ EXAMPLES = ''' sp_password: sysadmin lunid: 100 state: absent -''' +""" -RETURN = ''' +RETURN = r""" hluid: - description: LUNID that hosts attached to the storage group will see. - type: int - returned: success -''' + description: LUNID that hosts attached to the storage group will see. + type: int + returned: success +""" import traceback diff --git a/plugins/modules/etcd3.py b/plugins/modules/etcd3.py index b1bb181cf4..66f0cfb85b 100644 --- a/plugins/modules/etcd3.py +++ b/plugins/modules/etcd3.py @@ -9,84 +9,83 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: etcd3 short_description: Set or delete key value pairs from an etcd3 cluster requirements: - etcd3 description: - Sets or deletes values in etcd3 cluster using its v3 api. - - Needs python etcd3 lib to work + - Needs python etcd3 lib to work. extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - key: - type: str - description: - - the key where the information is stored in the cluster - required: true - value: - type: str - description: - - the information stored - required: true - host: - type: str - description: - - the IP address of the cluster - default: 'localhost' - port: - type: int - description: - - the port number used to connect to the cluster - default: 2379 - state: - type: str - description: - - the state of the value for the key. - - can be present or absent - required: true - choices: [ present, absent ] - user: - type: str - description: - - The etcd user to authenticate with. - password: - type: str - description: - - The password to use for authentication. - - Required if O(user) is defined. - ca_cert: - type: path - description: - - The Certificate Authority to use to verify the etcd host. - - Required if O(client_cert) and O(client_key) are defined. - client_cert: - type: path - description: - - PEM formatted certificate chain file to be used for SSL client authentication. - - Required if O(client_key) is defined. - client_key: - type: path - description: - - PEM formatted file that contains your private key to be used for SSL client authentication. - - Required if O(client_cert) is defined. - timeout: - type: int - description: - - The socket level timeout in seconds. + key: + type: str + description: + - The key where the information is stored in the cluster. + required: true + value: + type: str + description: + - The information stored. + required: true + host: + type: str + description: + - The IP address of the cluster. + default: 'localhost' + port: + type: int + description: + - The port number used to connect to the cluster. + default: 2379 + state: + type: str + description: + - The state of the value for the key. + - Can be present or absent. + required: true + choices: [present, absent] + user: + type: str + description: + - The etcd user to authenticate with. + password: + type: str + description: + - The password to use for authentication. + - Required if O(user) is defined. + ca_cert: + type: path + description: + - The Certificate Authority to use to verify the etcd host. + - Required if O(client_cert) and O(client_key) are defined. + client_cert: + type: path + description: + - PEM formatted certificate chain file to be used for SSL client authentication. + - Required if O(client_key) is defined. + client_key: + type: path + description: + - PEM formatted file that contains your private key to be used for SSL client authentication. + - Required if O(client_cert) is defined. + timeout: + type: int + description: + - The socket level timeout in seconds. author: - - Jean-Philippe Evrard (@evrardjp) - - Victor Fauth (@vfauth) -''' + - Jean-Philippe Evrard (@evrardjp) + - Victor Fauth (@vfauth) +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Store a value "bar" under the key "foo" for a cluster located "http://localhost:2379" community.general.etcd3: key: "foo" @@ -114,16 +113,16 @@ EXAMPLES = """ client_key: "/etc/ssl/private/key.pem" """ -RETURN = ''' +RETURN = r""" key: - description: The key that was queried - returned: always - type: str + description: The key that was queried. + returned: always + type: str old_value: - description: The previous value in the cluster - returned: always - type: str -''' + description: The previous value in the cluster. + returned: always + type: str +""" import traceback diff --git a/plugins/modules/facter.py b/plugins/modules/facter.py index 87017246ae..0fa286d5e6 100644 --- a/plugins/modules/facter.py +++ b/plugins/modules/facter.py @@ -8,36 +8,34 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: facter short_description: Runs the discovery program C(facter) on the remote system description: - - Runs the C(facter) discovery program - (U(https://github.com/puppetlabs/facter)) on the remote system, returning - JSON data that can be useful for inventory purposes. + - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning JSON data + that can be useful for inventory purposes. 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: - arguments: - description: - - Specifies arguments for facter. - type: list - elements: str + arguments: + description: + - Specifies arguments for facter. + type: list + elements: str requirements: - - facter - - ruby-json + - facter + - ruby-json author: - - Ansible Core Team - - Michael DeHaan -''' + - Ansible Core Team + - Michael DeHaan +""" -EXAMPLES = ''' +EXAMPLES = r""" # Example command-line invocation # ansible www.example.net -m facter @@ -47,11 +45,11 @@ EXAMPLES = ''' - name: Execute facter with arguments community.general.facter: arguments: - - -p - - system_uptime - - timezone - - is_virtual -''' + - -p + - system_uptime + - timezone + - is_virtual +""" import json from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/facter_facts.py b/plugins/modules/facter_facts.py index abc3f87ebe..8f73b37644 100644 --- a/plugins/modules/facter_facts.py +++ b/plugins/modules/facter_facts.py @@ -9,47 +9,45 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: facter_facts short_description: Runs the discovery program C(facter) on the remote system and return Ansible facts version_added: 8.0.0 description: - - Runs the C(facter) discovery program - (U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible facts from the - JSON data that can be useful for inventory purposes. + - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible + facts from the JSON data that can be useful for inventory purposes. extends_documentation_fragment: - - community.general.attributes - - community.general.attributes.facts - - community.general.attributes.facts_module + - community.general.attributes + - community.general.attributes.facts + - community.general.attributes.facts_module options: - arguments: - description: - - Specifies arguments for facter. - type: list - elements: str + arguments: + description: + - Specifies arguments for facter. + type: list + elements: str requirements: - - facter - - ruby-json + - facter + - ruby-json author: - - Ansible Core Team - - Michael DeHaan -''' + - Ansible Core Team + - Michael DeHaan +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Execute facter no arguments community.general.facter_facts: - name: Execute facter with arguments community.general.facter_facts: arguments: - - -p - - system_uptime - - timezone - - is_virtual -''' + - -p + - system_uptime + - timezone + - is_virtual +""" -RETURN = r''' +RETURN = r""" ansible_facts: description: Dictionary with one key C(facter). returned: always @@ -59,7 +57,7 @@ ansible_facts: description: Dictionary containing facts discovered in the remote system. returned: always type: dict -''' +""" import json diff --git a/plugins/modules/filesize.py b/plugins/modules/filesize.py index 83de682883..777c00711f 100644 --- a/plugins/modules/filesize.py +++ b/plugins/modules/filesize.py @@ -9,17 +9,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: filesize short_description: Create a file with a given size, or resize it if it exists description: - - This module is a simple wrapper around C(dd) to create, extend or truncate - a file, given its size. It can be used to manage swap files (that require - contiguous blocks) or alternatively, huge sparse files. - + - This module is a simple wrapper around C(dd) to create, extend or truncate a file, given its size. It can be used to manage + swap files (that require contiguous blocks) or alternatively, huge sparse files. author: - quidame (@quidame) @@ -40,36 +37,27 @@ options: size: description: - Requested size of the file. - - The value is a number (either C(int) or C(float)) optionally followed - by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or - V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), - and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of - V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB); + - The value is a number (either C(int) or C(float)) optionally followed by a multiplicative suffix, that can be one + of V(B) (bytes), V(KB) or V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), and so on for V(T), + V(P), V(E), V(Z) and V(Y); or alternatively one of V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB); V(G), V(g) or V(GiB) (= 1024MiB); and so on. - - If the multiplicative suffix is not provided, the value is treated as - an integer number of blocks of O(blocksize) bytes each (float values - are rounded to the closest integer). + - If the multiplicative suffix is not provided, the value is treated as an integer number of blocks of O(blocksize) + bytes each (float values are rounded to the closest integer). - When the O(size) value is equal to the current file size, does nothing. - - When the O(size) value is bigger than the current file size, bytes from - O(source) (if O(sparse) is not V(false)) are appended to the file - without truncating it, in other words, without modifying the existing - bytes of the file. - - When the O(size) value is smaller than the current file size, it is - truncated to the requested value without modifying bytes before this - value. - - That means that a file of any arbitrary size can be grown to any other - arbitrary size, and then resized down to its initial size without - modifying its initial content. + - When the O(size) value is bigger than the current file size, bytes from O(source) (if O(sparse) is not V(false)) are + appended to the file without truncating it, in other words, without modifying the existing bytes of the file. + - When the O(size) value is smaller than the current file size, it is truncated to the requested value without modifying + bytes before this value. + - That means that a file of any arbitrary size can be grown to any other arbitrary size, and then resized down to its + initial size without modifying its initial content. type: raw required: true blocksize: description: - Size of blocks, in bytes if not followed by a multiplicative suffix. - - The numeric value (before the unit) B(MUST) be an integer (or a C(float) - if it equals an integer). - - If not set, the size of blocks is guessed from the OS and commonly - results in V(512) or V(4096) bytes, that is used internally by the - module or when O(size) has no unit. + - The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals an integer). + - If not set, the size of blocks is guessed from the OS and commonly results in V(512) or V(4096) bytes, that is used + internally by the module or when O(size) has no unit. type: raw source: description: @@ -79,26 +67,22 @@ options: default: /dev/zero force: description: - - Whether or not to overwrite the file if it exists, in other words, to - truncate it from 0. When V(true), the module is not idempotent, that - means it always reports C(changed=true). + - Whether or not to overwrite the file if it exists, in other words, to truncate it from 0. When V(true), the module + is not idempotent, that means it always reports C(changed=true). - O(force=true) and O(sparse=true) are mutually exclusive. type: bool default: false sparse: description: - Whether or not the file to create should be a sparse file. - - This option is effective only on newly created files, or when growing a - file, only for the bytes to append. + - This option is effective only on newly created files, or when growing a file, only for the bytes to append. - This option is not supported on OSes or filesystems not supporting sparse files. - O(force=true) and O(sparse=true) are mutually exclusive. type: bool default: false unsafe_writes: description: - - This option is silently ignored. This module always modifies file - size in-place. - + - This option is silently ignored. This module always modifies file size in-place. requirements: - dd (Data Duplicator) in PATH @@ -138,9 +122,9 @@ seealso: - name: busybox(1) manpage for Linux description: Manual page of the GNU/Linux's busybox, that provides its own dd implementation. link: https://www.unix.com/man-page/linux/1/busybox -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a file of 1G filled with null bytes community.general.filesize: path: /var/bigfile @@ -183,9 +167,9 @@ EXAMPLES = r''' mode: u=rw,go= owner: root group: root -''' +""" -RETURN = r''' +RETURN = r""" cmd: description: Command executed to create or resize the file. type: str @@ -229,7 +213,7 @@ path: type: str sample: /var/swap0 returned: always -''' +""" import re diff --git a/plugins/modules/filesystem.py b/plugins/modules/filesystem.py index 73e8c79c6a..2edc8be5ab 100644 --- a/plugins/modules/filesystem.py +++ b/plugins/modules/filesystem.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: - Alexander Bulimov (@abulimov) - quidame (@quidame) @@ -29,33 +28,29 @@ attributes: options: state: description: - - If O(state=present), the filesystem is created if it doesn't already - exist, that is the default behaviour if O(state) is omitted. - - If O(state=absent), filesystem signatures on O(dev) are wiped if it - contains a filesystem (as known by C(blkid)). - - When O(state=absent), all other options but O(dev) are ignored, and the - module does not fail if the device O(dev) doesn't actually exist. + - If O(state=present), the filesystem is created if it does not already exist, that is the default behaviour if O(state) + is omitted. + - If O(state=absent), filesystem signatures on O(dev) are wiped if it contains a filesystem (as known by C(blkid)). + - When O(state=absent), all other options but O(dev) are ignored, and the module does not fail if the device O(dev) + does not actually exist. type: str - choices: [ present, absent ] + choices: [present, absent] default: present version_added: 1.3.0 fstype: - choices: [ bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ] + choices: [bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs] description: - - Filesystem type to be created. This option is required with - O(state=present) (or if O(state) is omitted). - - ufs support has been added in community.general 3.4.0. - - bcachefs support has been added in community.general 8.6.0. + - Filesystem type to be created. This option is required with O(state=present) (or if O(state) is omitted). + - Ufs support has been added in community.general 3.4.0. + - Bcachefs support has been added in community.general 8.6.0. type: str aliases: [type] dev: description: - - Target path to block device (Linux) or character device (FreeBSD) or - regular file (both). - - When setting Linux-specific filesystem types on FreeBSD, this module - only works when applying to regular files, aka disk images. - - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support - a regular file as their target O(dev). + - Target path to block device (Linux) or character device (FreeBSD) or regular file (both). + - When setting Linux-specific filesystem types on FreeBSD, this module only works when applying to regular files, aka + disk images. + - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support a regular file as their target O(dev). - Support for character devices on FreeBSD has been added in community.general 3.4.0. type: path required: true @@ -68,12 +63,11 @@ options: resizefs: description: - If V(true), if the block device and filesystem size differ, grow the filesystem into the space. - - Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems. - Attempts to resize other filesystem types will fail. - - XFS Will only grow if mounted. Currently, the module is based on commands - from C(util-linux) package to perform operations, so resizing of XFS is - not supported on FreeBSD systems. - - vFAT will likely fail if C(fatresize < 1.04). + - Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) + filesystems. Attempts to resize other filesystem types will fail. + - XFS Will only grow if mounted. Currently, the module is based on commands from C(util-linux) package to perform operations, + so resizing of XFS is not supported on FreeBSD systems. + - VFAT will likely fail if C(fatresize < 1.04). - Mutually exclusive with O(uuid). type: bool default: false @@ -93,32 +87,28 @@ options: type: str version_added: 7.1.0 requirements: - - Uses specific tools related to the O(fstype) for creating or resizing a - filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on). - - Uses generic tools mostly related to the Operating System (Linux or - FreeBSD) or available on both, as C(blkid). + - Uses specific tools related to the O(fstype) for creating or resizing a filesystem (from packages e2fsprogs, xfsprogs, + dosfstools, and so on). + - Uses generic tools mostly related to the Operating System (Linux or FreeBSD) or available on both, as C(blkid). - On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required. notes: - - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) - is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also - unable to detect a filesystem), this filesystem is overwritten even if - O(force) is V(false). - - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide - a C(blkid) command that is compatible with this module. However, these - packages conflict with each other, and only the C(util-linux) package - provides the command required to not fail when O(state=absent). + - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) is unable to detect a filesystem (and in + case C(fstyp) on FreeBSD is also unable to detect a filesystem), this filesystem is overwritten even if O(force) is V(false). + - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide a C(blkid) command that is compatible with this + module. However, these packages conflict with each other, and only the C(util-linux) package provides the command required + to not fail when O(state=absent). seealso: - module: community.general.filesize - module: ansible.posix.mount - name: xfs_admin(8) manpage for Linux - description: Manual page of the GNU/Linux's xfs_admin implementation + description: Manual page of the GNU/Linux's xfs_admin implementation. link: https://man7.org/linux/man-pages/man8/xfs_admin.8.html - name: tune2fs(8) manpage for Linux - description: Manual page of the GNU/Linux's tune2fs implementation + description: Manual page of the GNU/Linux's tune2fs implementation. link: https://man7.org/linux/man-pages/man8/tune2fs.8.html -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a ext2 filesystem on /dev/sdb1 community.general.filesystem: fstype: ext2 @@ -157,7 +147,7 @@ EXAMPLES = ''' fstype: lvm dev: /dev/sdc uuid: random -''' +""" import os import platform diff --git a/plugins/modules/flatpak.py b/plugins/modules/flatpak.py index 84e4ea8374..13898c3349 100644 --- a/plugins/modules/flatpak.py +++ b/plugins/modules/flatpak.py @@ -10,8 +10,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: flatpak short_description: Manage flatpaks description: @@ -34,66 +33,60 @@ attributes: options: executable: description: - - The path to the C(flatpak) executable to use. - - By default, this module looks for the C(flatpak) executable on the path. + - The path to the C(flatpak) executable to use. + - By default, this module looks for the C(flatpak) executable on the path. type: path default: flatpak method: description: - - The installation method to use. - - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) - or only for the current V(user). + - The installation method to use. + - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user). type: str - choices: [ system, user ] + choices: [system, user] default: system name: description: - - The name of the flatpak to manage. To operate on several packages this - can accept a list of packages. - - When used with O(state=present), O(name) can be specified as a URL to a - C(flatpakref) file or the unique reverse DNS name that identifies a flatpak. - - Both C(https://) and C(http://) URLs are supported. - - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote - to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit). - - When used with O(state=absent) or O(state=latest), it is recommended to specify the name in - the reverse DNS format. - - When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the - installed flatpak based on the name of the flatpakref to remove or update it. However, there - is no guarantee that the names of the flatpakref file and the reverse DNS name of the - installed flatpak do match. + - The name of the flatpak to manage. To operate on several packages this can accept a list of packages. + - When used with O(state=present), O(name) can be specified as a URL to a C(flatpakref) file or the unique reverse DNS + name that identifies a flatpak. + - Both C(https://) and C(http://) URLs are supported. + - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote to look for the flatpak. + An example for a reverse DNS name is C(org.gnome.gedit). + - When used with O(state=absent) or O(state=latest), it is recommended to specify the name in the reverse DNS format. + - When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the installed flatpak based + on the name of the flatpakref to remove or update it. However, there is no guarantee that the names of the flatpakref + file and the reverse DNS name of the installed flatpak do match. type: list elements: str required: true no_dependencies: description: - - If installing runtime dependencies should be omitted or not - - This parameter is primarily implemented for integration testing this module. - There might however be some use cases where you would want to have this, like when you are - packaging your own flatpaks. + - If installing runtime dependencies should be omitted or not. + - This parameter is primarily implemented for integration testing this module. There might however be some use cases + where you would want to have this, like when you are packaging your own flatpaks. type: bool default: false version_added: 3.2.0 remote: description: - - The flatpak remote (repository) to install the flatpak from. - - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before - you can use this. - - See the M(community.general.flatpak_remote) module for managing flatpak remotes. + - The flatpak remote (repository) to install the flatpak from. + - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before you can use this. + - See the M(community.general.flatpak_remote) module for managing flatpak remotes. type: str default: flathub state: description: - - Indicates the desired package state. - - The value V(latest) is supported since community.general 8.6.0. - choices: [ absent, present, latest ] + - Indicates the desired package state. + - The value V(latest) is supported since community.general 8.6.0. + choices: [absent, present, latest] type: str default: present -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Install the spotify flatpak community.general.flatpak: - name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref + name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref state: present - name: Install the gedit flatpak package without dependencies (not recommended) @@ -123,7 +116,7 @@ EXAMPLES = r''' - name: Update the spotify flatpak community.general.flatpak: - name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref + name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref state: latest - name: Update the gedit flatpak package without dependencies (not recommended) @@ -164,35 +157,35 @@ EXAMPLES = r''' - org.inkscape.Inkscape - org.mozilla.firefox state: absent -''' +""" -RETURN = r''' +RETURN = r""" command: - description: The exact flatpak command that was executed + description: The exact flatpak command that was executed. returned: When a flatpak command has been executed type: str sample: "/usr/bin/flatpak install --user --nontinteractive flathub org.gnome.Calculator" msg: - description: Module error message + description: Module error message. returned: failure type: str sample: "Executable '/usr/local/bin/flatpak' was not found on the system." rc: - description: Return code from flatpak binary + description: Return code from flatpak binary. returned: When a flatpak command has been executed type: int sample: 0 stderr: - description: Error output from flatpak binary + description: Error output from flatpak binary. returned: When a flatpak command has been executed type: str sample: "error: Error searching remote flathub: Can't find ref org.gnome.KDE" stdout: - description: Output from flatpak binary + description: Output from flatpak binary. returned: When a flatpak command has been executed type: str sample: "org.gnome.Calendar/x86_64/stable\tcurrent\norg.gnome.gitg/x86_64/stable\tcurrent\n" -''' +""" from ansible.module_utils.six.moves.urllib.parse import urlparse from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/flatpak_remote.py b/plugins/modules/flatpak_remote.py index a4eb3ea27c..ba202d3033 100644 --- a/plugins/modules/flatpak_remote.py +++ b/plugins/modules/flatpak_remote.py @@ -10,15 +10,13 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: flatpak_remote short_description: Manage flatpak repository remotes description: - Allows users to add or remove flatpak remotes. - - The flatpak remotes concept is comparable to what is called repositories in other packaging - formats. - - Currently, remote addition is only supported via C(flatpakrepo) file URLs. + - The flatpak remotes concept is comparable to what is called repositories in other packaging formats. + - Currently, remote addition is only supported using C(flatpakrepo) file URLs. - Existing remotes will not be updated. - See the M(community.general.flatpak) module for managing flatpaks. author: @@ -36,49 +34,47 @@ attributes: options: executable: description: - - The path to the C(flatpak) executable to use. - - By default, this module looks for the C(flatpak) executable on the path. + - The path to the C(flatpak) executable to use. + - By default, this module looks for the C(flatpak) executable on the path. type: str default: flatpak flatpakrepo_url: description: - - The URL to the C(flatpakrepo) file representing the repository remote to add. - - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) - is added using the specified installation O(method). - - When used with O(state=absent), this is not required. - - Required when O(state=present). + - The URL to the C(flatpakrepo) file representing the repository remote to add. + - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) is added using the specified + installation O(method). + - When used with O(state=absent), this is not required. + - Required when O(state=present). type: str method: description: - - The installation method to use. - - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) - or only for the current V(user). + - The installation method to use. + - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user). type: str - choices: [ system, user ] + choices: [system, user] default: system name: description: - - The desired name for the flatpak remote to be registered under on the managed host. - - When used with O(state=present), the remote will be added to the managed host under - the specified O(name). - - When used with O(state=absent) the remote with that name will be removed. + - The desired name for the flatpak remote to be registered under on the managed host. + - When used with O(state=present), the remote will be added to the managed host under the specified O(name). + - When used with O(state=absent) the remote with that name will be removed. type: str required: true state: description: - - Indicates the desired package state. + - Indicates the desired package state. type: str - choices: [ absent, present ] + choices: [absent, present] default: present enabled: description: - - Indicates whether this remote is enabled. + - Indicates whether this remote is enabled. type: bool default: true version_added: 6.4.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Add the Gnome flatpak remote to the system installation community.general.flatpak_remote: name: gnome @@ -108,35 +104,35 @@ EXAMPLES = r''' name: flathub state: present enabled: false -''' +""" -RETURN = r''' +RETURN = r""" command: - description: The exact flatpak command that was executed + description: The exact flatpak command that was executed. returned: When a flatpak command has been executed type: str sample: "/usr/bin/flatpak remote-add --system flatpak-test https://dl.flathub.org/repo/flathub.flatpakrepo" msg: - description: Module error message + description: Module error message. returned: failure type: str sample: "Executable '/usr/local/bin/flatpak' was not found on the system." rc: - description: Return code from flatpak binary + description: Return code from flatpak binary. returned: When a flatpak command has been executed type: int sample: 0 stderr: - description: Error output from flatpak binary + description: Error output from flatpak binary. returned: When a flatpak command has been executed type: str sample: "error: GPG verification enabled, but no summary found (check that the configured URL in remote config is correct)\n" stdout: - description: Output from flatpak binary + description: Output from flatpak binary. returned: When a flatpak command has been executed type: str sample: "flathub\tFlathub\thttps://dl.flathub.org/repo/\t1\t\n" -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.common.text.converters import to_bytes, to_native