[DEV-11572] add: backwards compat static typing

[thearchitector]

Summary

type stubs and mypy compliance. also ran our standard set of pre-commit linters against everything

enables using the client in typed contexts (all of Insights) with in-editor sanity checks without doing nasty type casts or ignores:

client: IndicoClient = IndicoClient(IndicoConfig(...))

# this is valid
subs: list[Submission] = client.call(ListSubmission(...))
# this is also valid
subs: Iterator[list[Submission]] = client.paginate(ListSubmission(...))

# this is not, and will throw a typing error 
subs: list[str] = client.call(ListSubmission(...))

also works for the async client, example in examples/typed_calls.py

---

enabled by turning http request classes into a generic that exposes its anticipated return type. for ex:

class GetIPAVersion(GraphQLRequest[str]):
    query = """
        "query getIPAVersion {
            ipaVersion
        }
    """

    def __init__(self) -> None:
        super().__init__(self.query)

    def process_response(self, response: "Payload") -> str:
        version: str = super().parse_payload(response)["ipaVersion"]
        return version

---

All typing should be compatible with the versions we say we test against (3.8+), and should not cause any breaking changes for people who are not using static typing.

verifications of that claim -- i made no material changes to any of the existing tests, only the linting:

tox:

  py38: OK (33.86=setup[31.30]+cmd[2.04,0.52] seconds)
  py39: OK (41.70=setup[38.93]+cmd[2.22,0.56] seconds)
  py310: OK (42.14=setup[39.36]+cmd[2.30,0.49] seconds)
  py311: OK (41.73=setup[39.30]+cmd[1.91,0.53] seconds)
  py312: OK (41.80=setup[38.82]+cmd[2.47,0.51] seconds)
  congratulations :) (42.20 seconds)

mypy:

(venv) indico@indico-XPS-13-9310:~/repos/indico-client-python$ mypy --config-file=pyproject.toml
Success: no issues found in 54 source files

integration tests:

these tests were already failing

FAILED tests/integration/queries/test_custom_blueprint.py::test_register_blueprint - indico.errors.IndicoRequestError: Status: 400, Error: A ComponentType.CUSTOM_OUTPUT blueprint called Meowtput with footer version 2 already exists.
FAILED tests/integration/queries/test_model_group.py::test_model_group_progress - indico.errors.IndicoRequestError: Status: 400, Error: 'NoneType' object is not subscriptable
FAILED tests/integration/queries/test_questionnaire.py::test_get_examples - assert 0 == 3
FAILED tests/integration/queries/test_questionnaire.py::test_add_labels - TypeError: AddLabels.__init__() got an unexpected keyword argument 'dataset_id'
FAILED tests/integration/queries/test_workflow.py::test_workflow_submission[_input0] - AttributeError: 'Submission' object has no attribute 'deleted'
FAILED tests/integration/queries/test_workflow.py::test_workflow_submission[_input1] - AttributeError: 'Submission' object has no attribute 'deleted'

vs. the run with my changes:

FAILED tests/integration/queries/test_custom_blueprint.py::test_register_blueprint - indico.errors.IndicoRequestError: Status: 400, Error: A ComponentType.CUSTOM_OUTPUT blueprint called Meowtput with footer version 2 already exists.
FAILED tests/integration/queries/test_model_group.py::test_model_group_progress - indico.errors.IndicoRequestError: Status: 400, Error: 'NoneType' object is not subscriptable
FAILED tests/integration/queries/test_questionnaire.py::test_get_examples - assert 0 == 3
FAILED tests/integration/queries/test_questionnaire.py::test_add_labels - TypeError: AddLabels.__init__() got an unexpected keyword argument 'dataset_id'
FAILED tests/integration/queries/test_workflow.py::test_workflow_submission[_input0] - AttributeError: 'Submission' object has no attribute 'deleted'
FAILED tests/integration/queries/test_workflow.py::test_workflow_submission[_input1] - AttributeError: 'Submission' object has no attribute 'deleted'
================================================================= 6 failed, 109 passed, 1 skipped in 3946.57s (1:05:46) =================================================================

[thearchitector]

typed python does not permit overriding the typing of the signature in subclasses. we were doing that implicitly before by having this fn return Dict and subclasses return their BaseType, etc.

a Union[Dict, ResponseType] does not solve the problem here either, as subclasses would have had to cast or type: ignore to deal with the Dict part in their overrides (ugly, not nice)

the smallest code change soln I could come up with is to split the function into a parse_payload fn typed to return Any, and replaced all super().process_response calls in every query with super().parse_payload. this impl calls parse_payload to maintain backwards compat

practically, that means we're deprecating the use of super().process_response in any custom GraphQLRequest subclasses; i tried, but sadly could not figure out a nice way to raise a deprecation error

[goatrocks]

We've used https://deprecation.readthedocs.io/en/latest/ in the past for raising deprecation errors

[thearchitector]

yea, i just couldn't figure out a way to only raise the error when invoking it via super().process_response

[goatrocks]

my kingdom for working deprecation in python

[goatrocks]

I wonder if we can do away with this class at some point

[thearchitector]

moving to pydantic is my next pet project

[goatrocks]

cooldown collab?

[goatrocks]

we can cut a pre-release and have some alpha/uat testing done here @nicholas-lockhart I think it would be worth it if folks have time to help test?

[madisonmay]

we should get this merged relatively soon so it doesn't rot on the vine