Using and Developing Module Utilities

    The ansible.module_utils namespace is not a plain Python package: it isconstructed dynamically for each task invocation, by extracting imports andresolving those matching the namespace against a search path derived from theactive configuration.

    To reduce the maintenance burden on your own local modules, you can extractduplicated 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:

    1. from ansible.module_utils.my_shared_code import MySharedCodeClient

    You can generally tell what a module utility does from its name and/or its location. For example, openstack.py contains utilities for modules that work with OpenStack instances.Generic utilities (shared code used by many different kinds of modules) live in the common subdirectory or in the root directory. Utilitiesused by a particular set of modules generally live in a sub-directory that mirrorsthe directory for those modules. For example:

    • lib/ansible/module_utils/urls.py contains shared code for parsing URLs
    • lib/ansible/module_utils/storage/emc/ contains shared code related to EMC
    • lib/ansible/modules/storage/emc/ contains modules related to EMC

    Following this pattern with your own module utilities makes everything easy to find and use.

    Standard module utilities

    Note

    LICENSING REQUIREMENTS Ansible enforces the following licensing requirements:

      • Utilities (files in lib/ansible/module_utils/) may have one of two licenses:
        • A file in module_utils used only for a specific vendor’s hardware, provider, or service may be licensed under GPLv3+.Adding a new file under module_utils with GPLv3+ needs to be approved by the core team.
        • All other module_utils must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.
    • All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).
    • api.py - Supports generic API modules
    • basic.py - General definitions and helper utilities for Ansible modules
    • common/dict_transformations.py - Helper functions for dictionary transformations
    • common/file.py - Helper functions for working with files
    • common/text/ - Helper functions for converting and formatting text.
    • common/parameters.py - Helper functions for dealing with module parameters
    • common/sys_info.py - Functions for getting distribution and platform information
    • common/validation.py - Helper functions for validating module parameters against a module argument spec
    • facts/ - Directory of utilities for modules that return facts. See PR 23012 for more information
    • - Single helper function that fixes os.path.ismount
    • known_hosts.py - utilities for working with known_hosts file
    • network/common/config.py - Configuration utility functions for use by networking modules
    • network/common/netconf.py - Definitions and helper functions for modules that use Netconf transport
    • network/common/parsing.py - Definitions and helper functions for Network modules
    • network/common/network.py - Functions for running commands on networking devices
    • network/common/utils.py - Defines commands and comparison operators and other utilises for use in networking modules
    • powershell/ - Directory of definitions and helper functions for Windows PowerShell modules
    • pycompat24.py - Exception workaround for Python 2.4
    • service.py - Utilities to enable modules to work with Linux services (placeholder, not in use)
    • shell.py - Functions to allow modules to create shells and work with shell commands
    • six/init.py - Bundled copy of the to aid in writing code compatible with both Python 2 and Python 3
    • urls.py - Utilities for working with http and https requests