Migrated User-related list module to new framework (#578)

* Migrated user list module

* Fixed docs

Author: ezilber-akamai

README.md

@@ -109,7 +109,7 @@ Name | Description |
 [linode.cloud.stackscript_list](./docs/modules/stackscript_list.md)|List and filter on StackScripts.|
 [linode.cloud.token_list](./docs/modules/token_list.md)|List and filter on Tokens.|
 [linode.cloud.type_list](./docs/modules/type_list.md)|List and filter on Types.|
-[linode.cloud.user_list](./docs/modules/user_list.md)|List Users.|
+[linode.cloud.user_list](./docs/modules/user_list.md)|List and filter on Users.|
 [linode.cloud.vlan_list](./docs/modules/vlan_list.md)|List and filter on Linode VLANs.|
 [linode.cloud.volume_list](./docs/modules/volume_list.md)|List and filter on Linode Volumes.|
 [linode.cloud.vpc_ip_list](./docs/modules/vpc_ip_list.md)|List and filter on VPC IP Addresses.|

docs/modules/user_list.md

@@ -1,6 +1,6 @@
 # user_list
 
-List Users.
+List and filter on Users.
 
 - [Minimum Required Fields](#minimum-required-fields)
 - [Examples](#examples)
@@ -24,12 +24,21 @@ List Users.
 
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
-| `order` | <center>`str`</center> | <center>Optional</center> | The order to list users in.  **(Choices: `desc`, `asc`; Default: `asc`)** |
-| `count` | <center>`int`</center> | <center>Optional</center> | The number of results to return. If undefined, all results will be returned.   |
+| `order` | <center>`str`</center> | <center>Optional</center> | The order to list Users in.  **(Choices: `desc`, `asc`; Default: `asc`)** |
+| `order_by` | <center>`str`</center> | <center>Optional</center> | The attribute to order Users by.   |
+| [`filters` (sub-options)](#filters) | <center>`list`</center> | <center>Optional</center> | A list of filters to apply to the resulting Users.   |
+| `count` | <center>`int`</center> | <center>Optional</center> | The number of Users to return. If undefined, all results will be returned.   |
+
+### filters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `name` | <center>`str`</center> | <center>**Required**</center> | The name of the field to filter on. Valid filterable fields can be found [here](https://techdocs.akamai.com/linode-api/reference/get-users).   |
+| `values` | <center>`list`</center> | <center>**Required**</center> | A list of values to allow for this field. Fields will pass this filter if at least one of these values matches.   |
 
 ## Return Values
 
-- `users` - The returned users.
+- `users` - The returned Users.
 
     - Sample Response:
         ```json
@@ -47,6 +56,6 @@ List Users.
           }
         ]
         ```
-    - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-account) for a list of returned fields
+    - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-users) for a list of returned fields
 
 

plugins/modules/user_list.py

@@ -4,97 +4,28 @@
 """This module allows users to list Users."""
 from __future__ import absolute_import, division, print_function
 
-from typing import Any, Dict, Optional
-
 import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.user_list as docs
-from ansible_collections.linode.cloud.plugins.module_utils.linode_common import (
-    LinodeModuleBase,
-)
-from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
-    global_authors,
-    global_requirements,
-)
-from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import (
-    get_all_paginated,
-)
-from ansible_specdoc.objects import (
-    FieldType,
-    SpecDocMeta,
-    SpecField,
-    SpecReturnValue,
+from ansible_collections.linode.cloud.plugins.module_utils.linode_common_list import (
+    ListModule,
 )
 
-spec = {
-    # 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 users in."],
-        default="asc",
-        choices=["desc", "asc"],
-    ),
-    "count": SpecField(
-        type=FieldType.integer,
-        description=[
-            "The number of results to return.",
-            "If undefined, all results will be returned.",
-        ],
-    ),
-}
-
-SPECDOC_META = SpecDocMeta(
-    description=["List Users."],
-    requirements=global_requirements,
-    author=global_authors,
-    options=spec,
+module = ListModule(
+    result_display_name="Users",
+    result_field_name="users",
+    endpoint_template="/account/users",
+    result_docs_url="https://techdocs.akamai.com/linode-api/reference/get-users",
     examples=docs.specdoc_examples,
-    return_values={
-        "users": SpecReturnValue(
-            description="The returned users.",
-            docs_url=(
-                "https://techdocs.akamai.com/linode-api/reference/get-account"
-            ),
-            type=FieldType.list,
-            elements=FieldType.dict,
-            sample=docs.result_users_samples,
-        )
-    },
+    result_samples=docs.result_users_samples,
 )
 
+SPECDOC_META = module.spec
+
 DOCUMENTATION = r"""
 """
 EXAMPLES = r"""
 """
 RETURN = r"""
 """
 
-
-class Module(LinodeModuleBase):
-    """Module for getting a list of Users"""
-
-    def __init__(self) -> None:
-        self.module_arg_spec = SPECDOC_META.ansible_spec
-        self.results: Dict[str, Any] = {"users": []}
-
-        super().__init__(module_arg_spec=self.module_arg_spec)
-
-    def exec_module(self, **kwargs: Any) -> Optional[dict]:
-        """Entrypoint for user module"""
-
-        self.results["users"] = get_all_paginated(
-            self.client,
-            "/account/users",
-            None,
-            num_results=self.module.params["count"],
-        )
-        return self.results
-
-
-def main() -> None:
-    """Constructs and calls the module"""
-    Module()
-
-
 if __name__ == "__main__":
-    main()
+    module.run()