collection 교체

collection/community/general/plugins/modules/xml.py

@@ -1,11 +1,12 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2014, Red Hat, Inc.
-# Copyright: (c) 2014, Tim Bielawa <tbielawa@redhat.com>
-# Copyright: (c) 2014, Magnus Hedemark <mhedemar@redhat.com>
-# Copyright: (c) 2017, Dag Wieers <dag@wieers.com>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2014, Red Hat, Inc.
+# Copyright (c) 2014, Tim Bielawa <tbielawa@redhat.com>
+# Copyright (c) 2014, Magnus Hedemark <mhedemar@redhat.com>
+# Copyright (c) 2017, Dag Wieers <dag@wieers.com>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
@@ -15,30 +16,38 @@ DOCUMENTATION = r'''
 module: xml
 short_description: Manage bits and pieces of XML files or strings
 description:
-- A CRUD-like interface to managing bits of XML files.
+  - A CRUD-like interface to managing bits of XML files.
+extends_documentation_fragment:
+  - community.general.attributes
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: full
 options:
   path:
     description:
     - Path to the file to operate on.
     - This file must exist ahead of time.
-    - This parameter is required, unless C(xmlstring) is given.
+    - This parameter is required, unless O(xmlstring) is given.
     type: path
     aliases: [ dest, file ]
   xmlstring:
     description:
     - A string containing XML on which to operate.
-    - This parameter is required, unless C(path) is given.
+    - This parameter is required, unless O(path) is given.
     type: str
   xpath:
     description:
     - A valid XPath expression describing the item(s) you want to manipulate.
-    - Operates on the document root, C(/), by default.
+    - Operates on the document root, V(/), by default.
     type: str
   namespaces:
     description:
     - The namespace C(prefix:uri) mapping for the XPath expression.
     - Needs to be a C(dict), not a C(list) of items.
     type: dict
+    default: {}
   state:
     description:
     - Set or remove an xpath selection (node(s), attribute(s)).
@@ -48,59 +57,59 @@ options:
     aliases: [ ensure ]
   attribute:
     description:
-    - The attribute to select when using parameter C(value).
-    - This is a string, not prepended with C(@).
+    - The attribute to select when using parameter O(value).
+    - This is a string, not prepended with V(@).
     type: raw
   value:
     description:
     - Desired state of the selected attribute.
-    - Either a string, or to unset a value, the Python C(None) keyword (YAML Equivalent, C(null)).
+    - Either a string, or to unset a value, the Python V(None) keyword (YAML Equivalent, V(null)).
     - Elements default to no value (but present).
     - Attributes default to an empty string.
     type: raw
   add_children:
     description:
-    - Add additional child-element(s) to a selected element for a given C(xpath).
+    - Add additional child-element(s) to a selected element for a given O(xpath).
     - Child elements must be given in a list and each item may be either a string
-      (eg. C(children=ansible) to add an empty C(<ansible/>) child element),
+      (for example C(children=ansible) to add an empty C(<ansible/>) child element),
       or a hash where the key is an element name and the value is the element value.
-    - This parameter requires C(xpath) to be set.
+    - This parameter requires O(xpath) to be set.
     type: list
     elements: raw
   set_children:
     description:
-    - Set the child-element(s) of a selected element for a given C(xpath).
+    - Set the child-element(s) of a selected element for a given O(xpath).
     - Removes any existing children.
-    - Child elements must be specified as in C(add_children).
-    - This parameter requires C(xpath) to be set.
+    - Child elements must be specified as in O(add_children).
+    - This parameter requires O(xpath) to be set.
     type: list
     elements: raw
   count:
     description:
-    - Search for a given C(xpath) and provide the count of any matches.
-    - This parameter requires C(xpath) to be set.
+    - Search for a given O(xpath) and provide the count of any matches.
+    - This parameter requires O(xpath) to be set.
     type: bool
-    default: no
+    default: false
   print_match:
     description:
-    - Search for a given C(xpath) and print out any matches.
-    - This parameter requires C(xpath) to be set.
+    - Search for a given O(xpath) and print out any matches.
+    - This parameter requires O(xpath) to be set.
     type: bool
-    default: no
+    default: false
   pretty_print:
     description:
     - Pretty print XML output.
     type: bool
-    default: no
+    default: false
   content:
     description:
-    - Search for a given C(xpath) and get content.
-    - This parameter requires C(xpath) to be set.
+    - Search for a given O(xpath) and get content.
+    - This parameter requires O(xpath) to be set.
     type: str
     choices: [ attribute, text ]
   input_type:
     description:
-    - Type of input for C(add_children) and C(set_children).
+    - Type of input for O(add_children) and O(set_children).
     type: str
     choices: [ xml, yaml ]
     default: yaml
@@ -109,38 +118,38 @@ options:
       - Create a backup file including the timestamp information so you can get
         the original file back if you somehow clobbered it incorrectly.
     type: bool
-    default: no
+    default: false
   strip_cdata_tags:
     description:
       - Remove CDATA tags surrounding text values.
       - Note that this might break your XML file if text values contain characters that could be interpreted as XML.
     type: bool
-    default: no
+    default: false
   insertbefore:
     description:
-      - Add additional child-element(s) before the first selected element for a given C(xpath).
+      - Add additional child-element(s) before the first selected element for a given O(xpath).
       - Child elements must be given in a list and each item may be either a string
-        (eg. C(children=ansible) to add an empty C(<ansible/>) child element),
+        (for example C(children=ansible) to add an empty C(<ansible/>) child element),
         or a hash where the key is an element name and the value is the element value.
-      - This parameter requires C(xpath) to be set.
+      - This parameter requires O(xpath) to be set.
     type: bool
-    default: no
+    default: false
   insertafter:
     description:
-      - Add additional child-element(s) after the last selected element for a given C(xpath).
+      - Add additional child-element(s) after the last selected element for a given O(xpath).
       - Child elements must be given in a list and each item may be either a string
-        (eg. C(children=ansible) to add an empty C(<ansible/>) child element),
+        (for example C(children=ansible) to add an empty C(<ansible/>) child element),
         or a hash where the key is an element name and the value is the element value.
-      - This parameter requires C(xpath) to be set.
+      - This parameter requires O(xpath) to be set.
     type: bool
-    default: no
+    default: false
 requirements:
 - lxml >= 2.3.0
 notes:
 - Use the C(--check) and C(--diff) options when testing your expressions.
 - The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure.
 - This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions.
-- Beware that in case your XML elements are namespaced, you need to use the C(namespaces) parameter, see the examples.
+- Beware that in case your XML elements are namespaced, you need to use the O(namespaces) parameter, see the examples.
 - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
 seealso:
 - name: Xml module development community wiki
@@ -192,7 +201,7 @@ EXAMPLES = r'''
   community.general.xml:
     path: /foo/bar.xml
     xpath: /business/beers/beer
-    count: yes
+    count: true
   register: hits
 
 - ansible.builtin.debug:
@@ -218,7 +227,7 @@ EXAMPLES = r'''
   community.general.xml:
     path: /foo/bar.xml
     xpath: '/business/beers/beer[text()="Rochefort 10"]'
-    insertbefore: yes
+    insertbefore: true
     add_children:
     - beer: Old Rasputin
     - beer: Old Motor Oil
@@ -264,7 +273,7 @@ EXAMPLES = r'''
   community.general.xml:
     path: /foo/bar.xml
     xpath: /business/website
-    children: []
+    set_children: []
 
 # In case of namespaces, like in below XML, they have to be explicitly stated.
 #
@@ -329,7 +338,7 @@ actions:
 backup_file:
     description: The name of the backup file that was created
     type: str
-    returned: when backup=yes
+    returned: when O(backup=true)
     sample: /path/to/file.xml.1942.2017-08-24@14:16:01~
 count:
     description: The count of xpath matches.
@@ -959,7 +968,7 @@ def main():
     # add_children && set_children both set?: should have already aborted by now
 
     # set_children set?
-    if set_children:
+    if set_children is not None:
         set_target_children(module, doc, xpath, namespaces, set_children, input_type)
 
     # add_children set?