Creating my first Action plugin and have a few questions

[Kent Larsson]

Hello folks!

I'm creating an Action plugin to query a file for contents.

I aim to publish it at Ansible Galaxy for myself to use, and perhaps it will be useful for someone else as well. It's my first Ansible plugin, and it's been a couple of years since I last touched Python as well, so I am in need of some guidance.

I have this file tree:

ansible_collections/
└── myns
    └── query_file
        ├── galaxy.yml
        ├── LICENSE
        ├── meta
        │   └── runtime.yml
        ├── plugins
        │   ├── action
        │   │   ├── args.json
        │   │   ├── query
        │   │   │   ├── config.py
        │   │   │   ├── parse.py
        │   │   │   ├── parse_target_container.py
        │   │   │   ├── select_columns.py
        │   │   │   ├── target_from.py
        │   │   │   ├── target.py
        │   │   │   ├── test_parse_dict.py
        │   │   │   ├── test_parse_list.py
        │   │   │   ├── test_parse.py
        │   │   │   ├── test_parse_target_container.py
        │   │   │   ├── test_select_columns.py
        │   │   │   ├── test_shared.py
        │   │   │   ├── test_target_from_string.py
        │   │   │   ├── test_target_init.py
        │   │   │   └── test_target_match_in.py
        │   │   └── query_file.py
        │   └── README.md
        ├── README.md
        ├── requirements.txt
        └── tests
            ├── integration
            │   ├── inventory
            │   └── targets
            │       └── action_query_file
            │           └── tasks
            │               └── test_x.yml
            └── unit
                └── plugins
                    └── action
                        └── test_y.py

1. query_file.py contains my class which extends ActionBase. I use some more modern stuff like types, @singledispatch, and @dataclass. I think it will be hard to support Python 2.7 so I thought I'd stick with Python 3 only. Does that decision make sense? I thought so since it's been a while now since Python 2.7 become unsupported.
   
2. If I go for Python 3 only, is there something I should do for ansible-test sanity to pass? It complains about some missing Python versions.
3. Next to as a sibling to query_file.py I have a directory named query. It contains the generic logic which is pure Python and does not require Ansible. I'd like to keep that code split up as it is. Is there a better, more "standard", place for it?
4. The query directory contains tests as well. I like my tests next to the files being tested, but it seems Ansible prefers a tests directory. Should I move my tests there for them to be executed well in a pipeline?

Thank you very much for taking the time to read this far! I hope there are some knowledgable people here who can provide some answers.

/ Kent

[Felix Fontein]

Hi,

> 1. query_file.py contains my class which extends ActionBase. I use

> some more modern stuff like types, @singledispatch, and @dataclass. I
> think it will be hard to support Python 2.7 so I thought I'd stick
> with Python 3 only. Does that decision make sense? I thought so since
> it's been a while now since Python 2.7 become unsupported.

If you want to support older ansible-core versions, you also should
support Python 2.7, but if you stick to ansible-core 2.12+ there's no
need for that. You can find a support matrix here:
https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix

If your collection supports (as declared in meta/runtime.yml)
ansible-core 2.12+ or even requires a later version, you can stick to
Python 3.8+ on the controller side (action plugins always run on the
controller side).

> 2. If I go for Python 3 only, is there something I should do for

> ansible-test sanity to pass? It complains about some missing
> Python versions.

Which ansible-core version are you using?

> 3. Next to as a sibling to query_file.py I have a directory named

> query. It contains the generic logic which is pure Python and does
> not require Ansible. I'd like to keep that code split up as it is. Is
> there a better, more "standard", place for it?

The standard place would be somewhere in plugins/plugin_utils/. Every
file in plugins/action/ (and subdirectories) is supposed to be an
action plugin. The JSON file in plugins/action/ might also cause
problems.

Do document your plugin, you also need a module stub in
plugins/modules/ with DOCUMENTATION, RETURN, and EXAMPLES.

> 4. The query directory contains tests as well. I like my tests

> next to the files being tested, but it seems Ansible prefers a tests
> directory. Should I move my tests there for them to be executed well
> in a pipeline?

ansible-test prefers tests for <path_to_file>/<filebase>.py to be in
tests/unit/<path_to_file>/test_<filebase>.py.

Regarding tests/integration:

> │ └── targets
> │ └── action_query_file
> │ └── tasks
> │ └── test_x.yml

you should have a main.yml in targets/action_query_file/tasks/.
Integration tests are an Ansible role, and `ansible-test integration`
uses the default entrypoint.

Cheers,
Felix