Import test: improve docs, add more tests

[felixfontein]

SUMMARY

Follow-up to #72497. Improves documentation of import sanity test,

Also hopefully improves the situation in #73596, CC @rhysmeister.

ISSUE TYPE

• Docs Pull Request
• Test Pull Request

COMPONENT NAME

ansible-test import sanity test

[felixfontein]

ready_for_review

[webknjaz]

For readability, it's probably better to have this in the else: block.

[felixfontein]

Fixed in 4f9e127.

[webknjaz]

I want to add that if the code targets a new enough Python 3 version, the example could preserve more metadata about the exception causes:

    try:
        import another_library
    except ImportError as imp_exc:
        another_library_import_exc = imp_exc
    else:
        another_library_import_exc = None


    # Later in module code:

        if another_library_import_exc is not None:
            # Needs: from ansible.module_utils.basic import missing_required_lib
            module.fail_json(msg=missing_required_lib('another_library'))

    # Later in plugin code:

        if another_library_import_exc is not None:
            raise AnsibleError('another_library must be installed to use this plugin') from another_library_import_exc

For older Pythons the example could use six.raise_from() shim.

[felixfontein]

I split up the example into modules vs. plugins, and used traceback to return the import traceback in module.fail_json(), and six.raise_from() for plugins (e74bec0).

[webknjaz]

How about

Suggested change

	RETURN = ''''''
	RETURN = ''

[felixfontein]

I copied that from existing tests in the same collection. I've changed it to ''' # ''' as recommended here: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#return-block (8d8ecba).

[Andersson007]

and thank you for the clarification! it helps much

[felixfontein]

CC @mattclay @acozine @lmalivert @samccann

[acozine]

Added a couple of suggestions for clarity.

[acozine]

Thanks for adding the reason for using try/except blocks. I'd move things around a bit just so the comparison of unchecked imports and "all other Python libraries" is easier to follow.

[felixfontein]

@evgeni @webknjaz @mattclay @Andersson007 @acozine thanks for all your reviews, suggestions, and for merging this!