Add return type to json_loads

[epenet]

Proposed change

I have read this thread around "Define a JSON type" python/typing#182 and I think that now that mypy supports recursive type, it might make sense to introduce this type to the Home Assistant code base.

Linked to #85603

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Black (black --fast homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.
• Untested files have been added to .coveragerc.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[epenet]

Note: it might not fit every situation.
It might force the user to add instance checks assert isinstance(json_data["value"], dict) before calling json_data["value"]["sub_value"]

This comment python/typing#182 (comment) has a nice example of when using it will be awkward.

If it returns JSONType then the first thing any code needs to do is to run an isinstance check for the returned value, as due to being a union, most operations won't be valid on it. However, in some cases it's arguably okay to assume that the returned value is a dict, for example. If this an internal data file, we can be reasonably sure that the format is what we expect. I didn't think about object_hook but that might be another thing to consider.

If a user wants to do the type check they can add an annotation if the return type is Any:

data = json.load(...)  # type: JSONType
if isinstance(data, dict): 
    ...

This, for example, would be rejected if the return type is a union, but would be fine if the return type is Any:

data = json.load(...)  # type: Dict[str, Any]   # error if load() return type is union
...

[epenet]

Rebased over #86419

[jbouwh]

Looks good to me,
Thnx @epenet !

Stale following json_loads_object

[jbouwh]

Looks good to me,
Thnx @epenet !

[emontnemery]

Looks good 👍

[epenet]

Thanks @emontnemery , thanks @jbouwh 👍