mock_modules generates mock modules that fail ansible-lint

[richm]

Summary

I have a problem with Automation Hub gating which (afaict) uses ansible-lint 24.12.2, ansible-core 2.16, and python 3.12 - and using mock_modules in .ansible-lint - ansible-lint generates a mocked python module which fails ansible-lint - steps to reproduce:

# python3.12 -mvenv .venv
# . .venv/bin/activate
# pip install ansible-lint==24.* ansible-core==2.16.*
# ansible-galaxy collection init myns.mycoll
# cd myns/mycoll
# cat .ansible-lint
mock_modules:
  - some_ns.some_coll.some_module
# ansible-lint
load-failure: Failed to load or parse file.
.ansible/collections/ansible_collections/some_ns/some_coll/plugins/modules/some_module.py:14

yaml[new-line-at-end-of-file]: No new line character at the end of file
.ansible/collections/ansible_collections/some_ns/some_coll/plugins/modules/some_module.py:14

afaict, the problem is the generated EXAMPLES = '''mocked''' and RETURN = '''mocked''' - these are being flagged as invalid YAML by rules init.py matchyaml -

        # yaml returned can be an AnsibleUnicode (a string) when the yaml
        # file contains a single string. YAML spec allows this but we consider
        # this an fatal error.

I don't know if the v24 branch is being maintained upstream but this is the version being used by Automation Hub.

Issue Type

• Bug Report

OS / ENVIRONMENT

ansible-lint --version
24.12.2
ansible --version
2.16.2

• ansible installation method: pip
• ansible-lint installation method: pip

STEPS TO REPRODUCE

see above

Desired Behavior

Should be able to use mock_modules and ansible-lint will pass.

Actual Behavior

See above.

[santosh7676]

Hi, I was able to reproduce this issue locally using the steps provided.

From debugging, it looks like the generated mock module (.py file under .ansible/collections/...) is being incorrectly classified as text/yaml, which causes the YAML rule (yamllint) to run on it and fail.

The root cause appears to be in kind_from_path(), where file type detection relies on pattern matching and may classify these generated .py files as YAML.

I initially tested a fix that classified all .py files as Python, but that caused regressions (e.g., Ansible plugin modules under plugins/modules/ were no longer detected correctly).

So I refined the approach to only target generated mock modules:

if path.suffix.lower() == ".py" and ".ansible/collections" in str(path):
    return "text/python" if base else "python"

With this change:

• Mock modules are no longer treated as YAML
• YAML-related errors on generated modules disappear
• Existing behavior for real Ansible plugins remains unchanged

I’ve also added tests to cover both the general case and the mock module path scenario.

Does this approach look acceptable? Happy to adjust based on feedback.

[richm]

ok, but in my testing it appeared that the problem was the generated EXAMPLES = '''mocked''' and RETURN = '''mocked''' blocks in the generated module code. If these were replaced with valid YAML, or in the case of the RETURN, use the special RETURN = r""" # """ which means "this module has no return", then ansible-lint passed.

[santosh7676]

Thanks @richm, you’re right.

I previously suspected file-kind detection (kind_from_path) for generated mock module paths. After retesting, the real issue is in the generated mock module content itself:

EXAMPLES = '''mocked'''
RETURN = '''mocked'''
These values are parsed by ansible-lint’s module-doc checks and can be treated as invalid YAML content in this flow, which leads to the reported failures.

Updated fix
I switched the mocked module template to use:

valid YAML in EXAMPLES
the no-return sentinel for RETURN: RETURN = r""" + # """
This resolves the mock-module failures in my repro without touching kind detection logic.