Proposal to used TypedDict to improve type hints

[burck1]

ref: #747

Checklist

• I have looked into the Readme and Examples, and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Describe the problem you'd like to have solved

Currently the management client library provides some type information as type hints for method parameters and return values, but many of the methods use dict[str, Any] as the type hint meaning callers do not know the expected keys of the dict nor the expected type of the values. This means IDEs, linters, LSPs, etc. are not able to provide warnings when callers of the methods are attempting to access a key that shouldn't exist or a value of a different type than expected.

Describe the ideal solution

I'd like my IDE / linter to be able to correct me if I misspell a key or use a value improperly.

There are many way to solve this problem in Python, but one option that could be interesting for this library is using Python's TypedDict type. TypedDicts are essentially just Python dictionary objects with extra type information, so using TypedDict to document types for the management clients' methods could be a backwards-compatible way to improve the types for the management clients without changing the runtime behavior of the library.

For example:

Before:

import json
from typing import Any

def get_client() -> dict[str, Any]:
    return json.loads('{"client_id":"abc123","name":"Example Client","is_first_party":true}')

client = get_client()
print('client_id:', client['client_id'])
print('name:', client['name'])
print('is_first_party:', client['is_first_party'])
print('foo_bar:', client['foo_bar']) # throws KeyError at runtime

After:

import json
from typing import TypedDict

class Client(TypedDict):
    client_id: str
    name: str
    is_first_party: bool

# update to the return type of the function
def get_client() -> Client:
    return json.loads('{"client_id":"abc123","name":"Example Client","is_first_party":true}')

# caller has the exact same code, but now they see type hints for the `client` variable's keys and values
client = get_client()
print('client_id:', client['client_id'])
print('name:', client['name'])
print('is_first_party:', client['is_first_party'])
print('foo_bar:', client['foo_bar']) # still would throw a KeyError at runtime,
#   but now we see a lint / LSP warning
#   "foo_bar" is not a defined key in "Client" Pylance(reportGeneralTypeIssues)

Additionally, since Auth0 has recently released an OpenAPI Specification for the Management API, TypedDict types could be auto-generated using a library like datamodel-code-generator. Then the only code change that would be required in the library would be to update the dict[str, Any] type hints in the management client classes.

Alternatives and current workarounds

Current workaround: Manual type cohersion, validation, or parsing by users of the library.

Additional context

[burck1]

@adamjmcgrath, @kishore7snehil, @tusharpandey13

Questions, comments, thoughts on this? Good idea or bad idea? Or if you have another plan on your backlog for supporting types for requests / responses, I'd be interested in learning about it.