1.. _developing_module_utilities:
2
3*************************************
4Using and developing module utilities
5*************************************
6
7Ansible provides a number of module utilities, or snippets of shared code, that
8provide helper functions you can use when developing your own modules. The
9``basic.py`` module utility provides the main entry point for accessing the
10Ansible library, and all Python Ansible modules must import something from
11``ansible.module_utils``. A common option is to import ``AnsibleModule``::
12
13  from ansible.module_utils.basic import AnsibleModule
14
15The ``ansible.module_utils`` namespace is not a plain Python package: it is
16constructed dynamically for each task invocation, by extracting imports and
17resolving those matching the namespace against a :ref:`search path <ansible_search_path>` derived from the
18active configuration.
19
20To reduce the maintenance burden in a collection or in local modules, you can extract
21duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file like this::
22
23  from ansible.module_utils.my_shared_code import MySharedCodeClient
24
25When you run ``ansible-playbook``, Ansible will merge any files in your local ``module_utils`` directories into the ``ansible.module_utils`` namespace in the order defined by the :ref:`Ansible search path <ansible_search_path>`.
26
27Naming and finding module utilities
28===================================
29
30You can generally tell what a module utility does from its name and/or its location. Generic utilities (shared code used by many different kinds of modules) live in the main ansible/ansible codebase, in the ``common`` subdirectory or in the root directory of ``lib/ansible/module_utils``. Utilities used by a particular set of modules generally live in the same collection as those modules. For example:
31
32* ``lib/ansible/module_utils/urls.py`` contains shared code for parsing URLs
33* ``openstack.cloud.plugins.module_utils.openstack.py`` contains utilities for modules that work with OpenStack instances
34* ``ansible.netcommon.plugins.module_utils.network.common.config.py`` contains utility functions for use by networking modules
35
36Following this pattern with your own module utilities makes everything easy to find and use.
37
38.. _standard_mod_utils:
39
40Standard module utilities
41=========================
42
43Ansible ships with an extensive library of ``module_utils`` files. You can find the module utility source code in the ``lib/ansible/module_utils`` directory under your main Ansible path. We describe the most widely used utilities below. For more details on any specific module utility, please see the `source code for module_utils <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils>`_.
44
45.. include:: shared_snippets/licensing.txt
46
47- ``api.py`` - Supports generic API modules
48- ``basic.py`` - General definitions and helper utilities for Ansible modules
49- ``common/dict_transformations.py`` - Helper functions for dictionary transformations
50- ``common/file.py`` - Helper functions for working with files
51- ``common/text/`` - Helper functions for converting and formatting text
52- ``common/parameters.py`` - Helper functions for dealing with module parameters
53- ``common/sys_info.py`` - Functions for getting distribution and platform information
54- ``common/validation.py`` - Helper functions for validating module parameters against a module argument spec
55- ``facts/`` - Directory of utilities for modules that return facts. See `PR 23012 <https://github.com/ansible/ansible/pull/23012>`_ for more information
56- ``json_utils.py`` - Utilities for filtering unrelated output around module JSON output, like leading and trailing lines
57- ``powershell/`` - Directory of definitions and helper functions for Windows PowerShell modules
58- ``pycompat24.py`` - Exception workaround for Python 2.4
59- ``service.py`` - Utilities to enable modules to work with Linux services (placeholder, not in use)
60- ``six/__init__.py`` - Bundled copy of the `Six Python library <https://pypi.org/project/six/>`_ to aid in writing code compatible with both Python 2 and Python 3
61- ``splitter.py`` - String splitting and manipulation utilities for working with Jinja2 templates
62- ``urls.py`` - Utilities for working with http and https requests
63
64Several commonly-used utilities migrated to collections in Ansible 2.10, including:
65
66- ``ismount.py`` migrated to ``ansible.posix.plugins.module_utils.mount.py`` - Single helper function that fixes os.path.ismount
67- ``known_hosts.py`` migrated to ``community.general.plugins.module_utils.known_hosts.py`` - utilities for working with known_hosts file
68
69For a list of migrated content with destination collections, see https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml.
70