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