Skip to content

Ansible Compatibility Guide

This guide outlines compatibility considerations for the cdot65.scm Ansible collection, particularly focusing on Ansible test compatibility requirements.

Python Version Compatibility

While the core functionality of this collection targets Python 3.12+ (as specified in pyproject.toml), the Ansible Galaxy ecosystem requires compatibility with older Python versions for testing purposes.

Key Compatibility Requirements

  1. Ansible Test Python Versions:

  2. Ansible tests against multiple Python versions including 3.12

  3. Our code needs to be syntax-compatible with these versions even if we don't officially support them

  4. Common Python Compatibility Issues:

  5. F-strings (use "text {0}".format(var) instead)

  6. Type hints (wrap in try/except blocks)
  7. Keyword-only arguments

  8. Unpacking generalizations

  9. Required Boilerplate:

  10. Add from __future__ import (absolute_import, division, print_function) to all Python files

  11. Add __metaclass__ = type to all Python files
  12. Use GPL v3 license headers for all modules

Import Considerations

  1. Import Order:

  2. Documentation variables (DOCUMENTATION, EXAMPLES, RETURN) must appear before imports in modules

  3. Use conditional imports for external dependencies like scm

  4. External Dependencies:

  5. Add checks for required external dependencies:

try:
    import scm
    HAS_SCM = True
except ImportError:
    HAS_SCM = False

# Later in the code:
if not HAS_SCM:
    module.fail_json(msg="The python pan-scm-sdk module is required for this module")

Ansible Compatibility

The collection supports Ansible 2.17.0 and higher as specified in meta/runtime.yml. For module validation testing purposes, the collection should include proper module redirects in this file.

Manual Fixes

Some issues may require manual intervention:

  1. Import Order: If a module has imports before documentation variables, you'll need to reorganize the file manually:

  2. Move all imports after the DOCUMENTATION, EXAMPLES, and RETURN variables

  3. Ensure imports are properly organized

  4. Documentation Validation: If validation errors occur in module documentation:

  5. Check for invalid keys in no_log parameters

  6. Verify all parameter types and choices match the expected values

Testing

After applying fixes, verify them with:

ansible-test sanity

For targeted tests:

ansible-test sanity --test import
ansible-test sanity --test pylint
ansible-test sanity --test validate-modules

Ongoing Compatibility

When developing new modules or making changes:

  1. Avoid Python 3.6+ specific features like:

  2. F-strings

  3. Dataclasses
  4. Type annotations without fallbacks

  5. Walrus operator (:=)

  6. Maintain proper import structure:

  7. Documentation before imports

  8. Proper boilerplate

  9. Check dependencies:

  10. Always include conditional imports for external packages

  11. Add appropriate error messages when dependencies are missing