ref: (BREAKING) Rewrite to use classes and objects rather than dicts

[lgarber-akamai]

📝 Description

THIS IS A BREAKING CHANGE

This change overhauls the user-implemented spec structure to use classes rather than raw dictionaries. This allows for improved static analysis and more control over which fields are passed to Ansible.

This change has been tested against ansible_linode.

✔️ How to Test

make test

✔️ Example Usage

spec_filter = dict(
    name=SpecField(type=FieldType.string, required=True,
              description=[
                  'The name of the field to filter on.',
                  'Valid filterable attributes can be found here: '
                  # pylint: disable-next=line-too-long
                  'https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples',
              ]),
    values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True,
                description=[
                    'A list of values to allow for this field.',
                    'Fields will pass this filter if at least one of these values matches.'
                ])
)

spec = dict(
    # Disable the default values
    state=SpecField(type=FieldType.string, required=False, doc_hide=True),
    label=SpecField(type=FieldType.string, required=False, doc_hide=True),

    order=SpecField(
        type=FieldType.string,
        description=['The order to list events in.'],
        default='asc',
        choices=['desc', 'asc']
    ),
    order_by=SpecField(
        type=FieldType.string,
        description=['The attribute to order events by.']
    ),
    filters=SpecField(
        type=FieldType.list, element_type=FieldType.dict,
        suboptions=spec_filter,
        description=['A list of filters to apply to the resulting events.']
    ),
    count=SpecField(
        type=FieldType.integer,
        description=[
            'The number of results to return.',
            'If undefined, all results will be returned.'
        ])
)

SPECDOC_META = SpecDocMeta(
    description=[
        'List and filter on Linode stackscripts.'
    ],
    requirements=global_requirements,
    author=global_authors,
    options=spec,
    examples=docs.specdoc_examples,
    return_values=dict(
        stackscripts=SpecReturnValue(
            description='The returned stackscripts.',
            docs_url='https://www.linode.com/docs/api/stackscripts/'
                     '#stackscripts-list__response-samples',
            type=FieldType.list,
            elements=FieldType.dict,
            sample=docs.result_stackscripts_samples
        )
    )
)


class Module(LinodeModuleBase):
    """Module for getting a list of Linode stackscripts"""

    def __init__(self) -> None:
        self.module_arg_spec = SPECDOC_META.ansible_spec

...

[zliang-akamai]

It seems that we will need some corresponding changes in Ansible repo, right?

[lgarber-akamai]

It seems that we will need some corresponding changes in Ansible repo, right?

@zliang-akamai Yep! This will be a large breaking change so part of bumping the dependency in ansible_linode would be adapting the spec of all modules to use this new class system.

This project is only consumed by us and hasn't yet had a minor release, so we're still free to make breaking changes.

[zliang-akamai]

Looks good to me! Well done!