xml: Improve documentation and examples (#50602)

This PR includes:
- Type information for parameters
- Added 'seealso' section to documentation
- Improve examples
This commit is contained in:
Dag Wieers 2019-01-07 21:46:51 +01:00 committed by Alicia Cozine
parent 19d7197d97
commit 100988899a

View file

@ -1,11 +1,10 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# Copyright 2014, Red Hat, Inc. # Copyright: (c) 2014, Red Hat, Inc.
# Tim Bielawa <tbielawa@redhat.com> # Copyright: (c) 2014, Tim Bielawa <tbielawa@redhat.com>
# Magnus Hedemark <mhedemar@redhat.com> # Copyright: (c) 2014, Magnus Hedemark <mhedemar@redhat.com>
# Copyright 2017, Dag Wieers <dag@wieers.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) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
@ -21,45 +20,51 @@ module: xml
short_description: Manage bits and pieces of XML files or strings short_description: Manage bits and pieces of XML files or strings
description: description:
- A CRUD-like interface to managing bits of XML files. - A CRUD-like interface to managing bits of XML files.
- You might also be interested in a brief tutorial from U(https://www.w3schools.com/xml/xpath_intro.asp)
and U(https://developer.mozilla.org/en-US/docs/Web/XPath).
version_added: '2.4' version_added: '2.4'
options: options:
path: path:
description: description:
- Path to the file to operate on. File must exist ahead of time. - 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 C(xmlstring) is given.
type: path
required: yes required: yes
aliases: [ dest, file ] aliases: [ dest, file ]
xmlstring: xmlstring:
description: description:
- A string containing XML on which to operate. - A string containing XML on which to operate.
- This parameter is required, unless C(path) is given. - This parameter is required, unless C(path) is given.
type: str
required: yes required: yes
xpath: xpath:
description: description:
- A valid XPath expression describing the item(s) you want to manipulate. - 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, C(/), by default.
type: str
namespaces: namespaces:
description: description:
- The namespace C(prefix:uri) mapping for the XPath expression. - The namespace C(prefix:uri) mapping for the XPath expression.
- Needs to be a C(dict), not a C(list) of items. - Needs to be a C(dict), not a C(list) of items.
type: dict
state: state:
description: description:
- Set or remove an xpath selection (node(s), attribute(s)). - Set or remove an xpath selection (node(s), attribute(s)).
default: present type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present
aliases: [ ensure ] aliases: [ ensure ]
attribute: attribute:
description: description:
- The attribute to select when using parameter C(value). - The attribute to select when using parameter C(value).
- This is a string, not prepended with C(@). - This is a string, not prepended with C(@).
type: raw
value: value:
description: description:
- Desired state of the selected attribute. - 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 C(None) keyword (YAML Equivalent, C(null)).
- Elements default to no value (but present). - Elements default to no value (but present).
- Attributes default to an empty string. - Attributes default to an empty string.
type: raw
add_children: add_children:
description: 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 C(xpath).
@ -67,37 +72,41 @@ options:
(eg. C(children=ansible) to add an empty C(<ansible/>) child element), (eg. 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. 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 C(xpath) to be set.
type: list
set_children: set_children:
description: 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 C(xpath).
- Removes any existing children. - Removes any existing children.
- Child elements must be specified as in C(add_children). - Child elements must be specified as in C(add_children).
- This parameter requires C(xpath) to be set. - This parameter requires C(xpath) to be set.
type: list
count: count:
description: description:
- Search for a given C(xpath) and provide the count of any matches. - Search for a given C(xpath) and provide the count of any matches.
- This parameter requires C(xpath) to be set. - This parameter requires C(xpath) to be set.
type: bool type: bool
default: 'no' default: no
print_match: print_match:
description: description:
- Search for a given C(xpath) and print out any matches. - Search for a given C(xpath) and print out any matches.
- This parameter requires C(xpath) to be set. - This parameter requires C(xpath) to be set.
type: bool type: bool
default: 'no' default: no
pretty_print: pretty_print:
description: description:
- Pretty print XML output. - Pretty print XML output.
type: bool type: bool
default: 'no' default: no
content: content:
description: description:
- Search for a given C(xpath) and get content. - Search for a given C(xpath) and get content.
- This parameter requires C(xpath) to be set. - This parameter requires C(xpath) to be set.
type: str
choices: [ attribute, text ] choices: [ attribute, text ]
input_type: input_type:
description: description:
- Type of input for C(add_children) and C(set_children). - Type of input for C(add_children) and C(set_children).
type: str
choices: [ xml, yaml ] choices: [ xml, yaml ]
default: yaml default: yaml
backup: backup:
@ -105,13 +114,13 @@ options:
- Create a backup file including the timestamp information so you can get - Create a backup file including the timestamp information so you can get
the original file back if you somehow clobbered it incorrectly. the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: 'no' default: no
strip_cdata_tags: strip_cdata_tags:
description: description:
- Remove CDATA tags surrounding text values. - 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. - Note that this might break your XML file if text values contain characters that could be interpreted as XML.
type: bool type: bool
default: 'no' default: no
version_added: '2.7' version_added: '2.7'
requirements: requirements:
- lxml >= 2.3.0 - lxml >= 2.3.0
@ -119,9 +128,18 @@ notes:
- Use the C(--check) and C(--diff) options when testing your expressions. - 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. - 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. - 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. - Beware that in case your XML elements are namespaced, you need to use the C(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. - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
- More information about this module is available from the community wiki at U(https://github.com/ansible/community/wiki/Module:-xml) seealso:
- name: Xml module development community wiki
description: More information related to the development of this xml module.
link: https://github.com/ansible/community/wiki/Module:-xml
- name: Introduction to XPath
description: A brief tutorial on XPath (w3schools.com).
link: https://www.w3schools.com/xml/xpath_intro.asp
- name: XPath Reference document
description: The reference documentation on XSLT/XPath (developer.mozilla.org).
link: https://developer.mozilla.org/en-US/docs/Web/XPath
author: author:
- Tim Bielawa (@tbielawa) - Tim Bielawa (@tbielawa)
- Magnus Hedemark (@magnus919) - Magnus Hedemark (@magnus919)
@ -129,20 +147,36 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: Remove the subjective attribute of the rating element # Consider the following XML file:
#
# <business type="bar">
# <name>Tasty Beverage Co.</name>
# <beers>
# <beer>Rochefort 10</beer>
# <beer>St. Bernardus Abbot 12</beer>
# <beer>Schlitz</beer>
# </beers>
# <rating subjective="true">10</rating>
# <website>
# <mobilefriendly/>
# <address>http://tastybeverageco.com</address>
# </website>
# </business>
- name: Remove the 'subjective' attribute of the 'rating' element
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/rating/@subjective xpath: /business/rating/@subjective
state: absent state: absent
- name: Set the rating to 11 - name: Set the rating to '11'
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/rating xpath: /business/rating
value: 11 value: 11
# Retrieve and display the number of nodes # Retrieve and display the number of nodes
- name: Get count of beers nodes - name: Get count of 'beers' nodes
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/beers/beer xpath: /business/beers/beer
@ -152,13 +186,14 @@ EXAMPLES = r'''
- debug: - debug:
var: hits.count var: hits.count
- name: Add a phonenumber element to the business element # Example where parent XML nodes are created automatically
- name: Add a 'phonenumber' element to the 'business' element
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/phonenumber xpath: /business/phonenumber
value: 555-555-1234 value: 555-555-1234
- name: Add several more beers to the beers element - name: Add several more beers to the 'beers' element
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/beers xpath: /business/beers
@ -167,12 +202,13 @@ EXAMPLES = r'''
- beer: Old Motor Oil - beer: Old Motor Oil
- beer: Old Curmudgeon - beer: Old Curmudgeon
- name: Add a validxhtml element to the website element # NOTE: The 'state' defaults to 'present' and 'value' defaults to 'null' for elements
- name: Add a 'validxhtml' element to the 'website' element
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/website/validxhtml xpath: /business/website/validxhtml
- name: Add an empty validatedon attribute to the validxhtml element - name: Add an empty 'validatedon' attribute to the 'validxhtml' element
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/website/validxhtml/@validatedon xpath: /business/website/validxhtml/@validatedon
@ -197,27 +233,27 @@ EXAMPLES = r'''
debug: debug:
var: xmlresp.matches[0].validxhtml.validatedon var: xmlresp.matches[0].validxhtml.validatedon
- name: Remove all children from the website element (option 1) - name: Remove all children from the 'website' element (option 1)
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/website/* xpath: /business/website/*
state: absent state: absent
- name: Remove all children from the website element (option 2) - name: Remove all children from the 'website' element (option 2)
xml: xml:
path: /foo/bar.xml path: /foo/bar.xml
xpath: /business/website xpath: /business/website
children: [] children: []
# In case of namespaces, like in below XML, they have to be explicitely stated # In case of namespaces, like in below XML, they have to be explicitely stated.
# NOTE: there's the prefix "x" in front of the "bar", too #
#<?xml version='1.0' encoding='UTF-8'?> # <foo xmlns="http://x.test" xmlns:attr="http://z.test">
#<foo xmlns="http://x.test" xmlns:attr="http://z.test"> # <bar>
# <bar> # <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" />
# <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" /> # </bar>
# </bar> # </foo>
#</foo>
# NOTE: There is the prefix 'x' in front of the 'bar' element, too.
- name: Set namespaced '/x:foo/x:bar/y:baz/@z:my_namespaced_attribute' to 'false' - name: Set namespaced '/x:foo/x:bar/y:baz/@z:my_namespaced_attribute' to 'false'
xml: xml:
path: foo.xml path: foo.xml