For the glossary: distribution In some operating systems, the kernel of the OS is produced by one organization but this is combined with other necessary tools by a second organization. This second organization is called a distribution. native string Python2 and Python3 have different types for unadorned string literals and many strings operations. In Python2, these are byte strings. In Python3, these are text strings. .. py:data:: BOOLEANS_TRUE All the values that parameter parsing converts to True. This is a mixture of boolean, integer, and native string types. .. py:data:: BOOLEANS_FALSE All the values that parameter parsing converts to False. This is a mixture of boolean, integer, and native string types. .. py:data:: BOOLEANS All the values that parameter parsing consider to be valid booleans. This is the superset of :py:data:`BOOLEANS_TRUE` and :py:data:`BOOLEANS_FALSE`. .. note:: In very old code, modules would specify that a parameter was a boolean by listing something like this in the :ref:`argument_spec`:: module = AnsibleModule( argument_spec=dict( return_status=dict(choices=BOOLEANS), ), ) This pattern is not very flexible and should no longer be used. Switch to using the type field instead:: module = AnsibleModule( argument_spec=dict( return_status=dict(type='bool'), ), ) .. py:data:: AVAILABLE_HASH_ALGORITHMS Mapping of hash algorithms supported by this version of python to a constructor for the hash algorithm. These hash algorithms all follow the API that is available for the stdlib :py:mod:`stdib:hashlib` hash algorithms. .. py:data:: FILE_COMMON_ARGUMENTS This is the argument_spec for anything that implements similar functionality to the file module. Note that currently, using this means that the module will accept all of these parameters but may not actually utilize them. For this reason, this may be deprecated in the future in favor of an argument_spec and supporting utility functions that make sure that both are valid. .. py:function:: get_platform() => NativeString Returns a native string that labels the platform ("Linux", "Solaris", etc). Currently, this is the result of calling :py:func:`stdlib:platform.system`. .. py:function:: get_distribution() => Union[NativeString, None] function attempts to determine what the distribution is and return a string representing that value. If it cannot determine a distribution, it returns None. .. py:function:: get_distribution_version() => Union[NativeString, None] This returns the Internals --------- These globals are not for use by other code. Documenting here for people who need to modify basic,py. .. py:data:: _ANSIBLE_ARGS This is an internal global variable that holds the parameters to the module once AnsibleModule has read them in. It is a native string type. Deprecated ========== All Python2 and Python3 compat ------------------------------ Analogs to these are either in six or one of the ansible.module_utils.pycompatXY modules:: Deprecated New Way to Achieve this ---------- ----------------------- imap ansible.module_utils.six.moves.map basestring ansible.module_utils.six.string_types or (ansible.module_utils.six.text_type, ansible.module_utils.six.binary_type) [*]_ unicode ansible.module_utils.six.text_type bytes ansible.module_utils.six.binary_type iteritems ansible.module_utils.six.iteritems reduce ansible.module_utils.six.moves import reduce NUMBERTYPES ansible.module_utils.six.integer_types + (float,) [+]_ NoneType ansible.module_utils.pycompat27.NoneType Sequence ansible.module_utils.pycompat24.Sequence Mapping ansible.module_utils.pycompat24.Mapping SEQUENCETYPE ansible.module_utils.pycompat27.SEQUENCETYPE json ansible.module_utils.pycompat24.json[****]_ literal_eval ansible.module_utils.pycompat24.literal_eval get_exception ansible.module_utils.pycompat24.get_exception .. _[****]: Ansible Core Team -- do we want to make an ansible.module_utils.json with this and other json-related functions? .. _[*]: What to replace basestring with depends on the usage. Most code that uses basestring looks like this:: if not isinstance(variable, basestring): # Get the string representation of the object variable = str(variable) # Then make sure it's unicode if not isinstance(variable, unicode): variable = unicode(variable, 'utf-'8') This should be replaced with this:: if not isinstance(variable, (six.binary_type, six.text_type)): variable = str(variable) if not isinstance(variable, six.text_type): variable = six.text_type(variable, 'utf-8') .. _[+]: NUMBERTYPES includes floating point numbers while six's equivalent is just for integers. Here's a sample of how to change your code:: # Old code: from ansible.module_utils.basic import NUMBERTYPES if isinstance(obj, NUMBERTYPES): return str(obj) from ansible.module_utils.six import integer_types # New code: if isinstance(obj, integer_types + (float,)): return str(obj) .. todo:: Move the deprecated values that belong in pycompatXY into those files. Private Globals --------------- .. py:data:: PASSWD_ARG_RE Defines what a password looks like. We use this to scan output for things that we should obfuscate. .. py:data:: PERM_BITS Bitmask of all the stat.mode bits pertaining to UNIX permissions .. py:data:: EXEC_PERM_BITS Bitmask of all the stat.mode bits pertaining to UNIX execute permissions .. py:data:: DEFAULT_PERM Bitmask for all file permissions. This is combined with umask in the actual code to come out with the default permissions. .. todo:: Rename these to have a leading underscore to mark them as private RST Notes ========= If we switch to inline documentation, attributes are documented like this:: #: All the values that parameter parsing converts to True BOOLEANS_TRUE = ['yes', 'on', '1', 'true', 'True', 1, True] #: All the values that parameter parsing converts to False BOOLEANS_FALSE = ['no', 'off', '0', 'false', 'False', 0, False]