ansible/test/units/module_utils
Dag Wieers cd9471ef17 Introduce new 'required_by' argument_spec option (#28662)
* Introduce new "required_by' argument_spec option

This PR introduces a new **required_by** argument_spec option which allows you to say *"if parameter A is set, parameter B and C are required as well"*.

- The difference with **required_if** is that it can only add dependencies if a parameter is set to a specific value, not when it is just defined.
- The difference with **required_together** is that it has a commutative property, so: *"Parameter A and B are required together, if one of them has been defined"*.

As an example, we need this for the complex options that the xml module provides. One of the issues we often see is that users are not using the correct combination of options, and then are surprised that the module does not perform the requested action(s).

This would be solved by adding the correct dependencies, and mutual exclusives. For us this is important to get this shipped together with the new xml module in Ansible v2.4. (This is related to bugfix https://github.com/ansible/ansible/pull/28657)

```python
    module = AnsibleModule(
        argument_spec=dict(
            path=dict(type='path', aliases=['dest', 'file']),
            xmlstring=dict(type='str'),
            xpath=dict(type='str'),
            namespaces=dict(type='dict', default={}),
            state=dict(type='str', default='present', choices=['absent',
'present'], aliases=['ensure']),
            value=dict(type='raw'),
            attribute=dict(type='raw'),
            add_children=dict(type='list'),
            set_children=dict(type='list'),
            count=dict(type='bool', default=False),
            print_match=dict(type='bool', default=False),
            pretty_print=dict(type='bool', default=False),
            content=dict(type='str', choices=['attribute', 'text']),
            input_type=dict(type='str', default='yaml', choices=['xml',
'yaml']),
            backup=dict(type='bool', default=False),
        ),
        supports_check_mode=True,
        required_by=dict(
            add_children=['xpath'],
            attribute=['value', 'xpath'],
            content=['xpath'],
            set_children=['xpath'],
            value=['xpath'],
        ),
        required_if=[
            ['count', True, ['xpath']],
            ['print_match', True, ['xpath']],
        ],
        required_one_of=[
            ['path', 'xmlstring'],
            ['add_children', 'content', 'count', 'pretty_print', 'print_match', 'set_children', 'value'],
        ],
        mutually_exclusive=[
            ['add_children', 'content', 'count', 'print_match','set_children', 'value'],
            ['path', 'xmlstring'],
        ],
    )
```

* Rebase and fix conflict

* Add modules that use required_by functionality

* Update required_by schema

* Fix rebase issue
2019-02-15 10:57:45 +10:00
..
aws Move unit test compat code out of lib/ansible/. (#46996) 2018-10-12 20:01:14 -07:00
basic Introduce new 'required_by' argument_spec option (#28662) 2019-02-15 10:57:45 +10:00
cloud Move unit test compat code out of lib/ansible/. (#46996) 2018-10-12 20:01:14 -07:00
common Add a CLIArgs Singleton class that will hold the parse cli arguments 2019-01-03 18:12:23 -08:00
docker docker modules: various adjustments (#51700) 2019-02-08 08:16:11 +00:00
ec2 Update bare exceptions to specify Exception. 2018-12-16 15:03:19 -08:00
facts parallelize getting mount info (#49398) 2019-01-23 12:33:59 -05:00
gcp Enable additional pylint rules and resolve issues found. (#47221) 2018-10-18 13:38:08 -07:00
json_utils Move unit test compat code out of lib/ansible/. (#46996) 2018-10-12 20:01:14 -07:00
net_tools Move unit test compat code out of lib/ansible/. (#46996) 2018-10-12 20:01:14 -07:00
network Fix unit tests on Python 3.8. 2019-02-13 01:03:06 -08:00
parsing Consolidate boolean/mk_boolean conversion functions into a single location 2017-07-17 11:48:05 -07:00
urls identity: Add GSSAPI suport for FreeIPA authentication (#52031) 2019-02-13 15:38:13 +00:00
xenserver Initial commit for xenserver module_util unit tests (#50850) 2019-02-05 09:41:26 -08:00
__init__.py
conftest.py Python 3.8 collections compatibility fixes. 2018-10-08 11:26:37 -07:00
test_acme.py Code style adjustment. (#49329) 2018-11-29 21:57:32 +01:00
test_database.py Fix unit test parametrize order on Python 3.5. 2018-09-17 22:45:42 -07:00
test_distribution_version.py facts: solaris: introduce distribution_major version detection for Solaris (#43978) 2019-01-23 20:33:32 -05:00
test_distro.py Fix unit tests on Python 3.8. 2019-02-13 01:03:06 -08:00
test_known_hosts.py Fix unit test parametrize order on Python 3.5. 2018-09-17 22:45:42 -07:00
test_postgresql.py Move unit test compat code out of lib/ansible/. (#46996) 2018-10-12 20:01:14 -07:00
test_text.py Porting tests to pytest (#33387) 2017-12-05 12:43:13 -08:00
test_utm_utils.py Add optional headers to utm modules (#49856) 2019-01-17 19:06:50 +05:30
test_vmware.py Final round of moving modules to new import error msg (#51852) 2019-02-08 10:07:01 +10:00