ansible/docs/docsite/rst/reference_appendices/module_utils.rst
Sam Doran 2cbfd1e350
Add porting guide and documentation for changes to argument spec validation ()
* Add ArgumentSpecValidator to docs
* Improve docs for ArgumentSpecValidator
* Document removal of private methods

* Update module_utils documentation
    - Add docs for argument spec classes as well as validation and parameters files.
    - preserve the order in the source for errors.py
    - document DEFAULT_TYPE_VALIDATORS so it can be referenced elsewhere
    - fix automodule directive for validation.py

* Update docs in arg_spec and paremeters
    - This improves the generated documentation.

* Document breaking changes in porting guide.
* Update formatting in porting guide and add a Deprecated section
* Fine tune module_utils documentation


* Move instance docstring to the __init__ method
  Remove optional description since it fails the sanity test and I am not 100% it is valid anyway.

* Remoe incorrect parameter from docstring
  This was changed a while ago but wasn't removed from the docstring.

* Use attr rather than attribute
  The py:attribute: domain only exists in newer Sphinx >= 3.1.

* Improve documentation on exceptions
* Final pass
    - use args/kwargs instead of param
    - fix formatting errors that didn't display examples correctly
    - format TypeErrors so they are referenced as classes
    - specify complex types
2021-04-20 15:40:53 -04:00

74 lines
1.7 KiB
ReStructuredText

.. _ansible.module_utils:
.. _module_utils:
***************************************************************
Ansible Reference: Module Utilities
***************************************************************
This page documents utilities intended to be helpful when writing
Ansible modules in Python.
AnsibleModule
--------------
To use this functionality, include ``from ansible.module_utils.basic import AnsibleModule`` in your module.
.. autoclass:: ansible.module_utils.basic.AnsibleModule
:members:
:noindex:
Basic
------
To use this functionality, include ``import ansible.module_utils.basic`` in your module.
.. automodule:: ansible.module_utils.basic
:members:
Argument Spec
---------------------
Classes and functions for validating parameters against an argument spec.
ArgumentSpecValidator
=====================
.. autoclass:: ansible.module_utils.common.arg_spec.ArgumentSpecValidator
:members:
ValidationResult
================
.. autoclass:: ansible.module_utils.common.arg_spec.ValidationResult
:members:
:member-order: bysource
:private-members: _no_log_values # This only works in sphinx >= 3.2. Otherwise it shows all private members with doc strings.
Parameters
==========
.. automodule:: ansible.module_utils.common.parameters
:members:
.. py:data:: DEFAULT_TYPE_VALIDATORS
:class:`dict` of type names, such as ``'str'``, and the default function
used to check that type, :func:`~ansible.module_utils.common.validation.check_type_str` in this case.
Validation
==========
Standalone functions for validating various parameter types.
.. automodule:: ansible.module_utils.common.validation
:members:
Errors
------
.. automodule:: ansible.module_utils.errors
:members:
:member-order: bysource