Adding type annotations to codebase

[hww-nikhilshankarnoble]

Creating Github Discussion as requested!

There have previously been bits of type hinting introduced in the gazu API, but they've had to be ripped out in order to maintain Python 2.7 compatibility (see #342 #343). However, now that Python 2 compatibility has been dropped, I'd like to ask if there's a willingness within the CG-Wire team for type annotations to be introduced and maintained in the codebase?

What are type annotations?

This article from the FastAPI documentation will do a better job of explaining them than I will be able to, but in short:

Python allows for developers to declare type "hints"/"annotations" to describe the type of the variable when they are defined, for use by IDEs and type checkers. Python is not a statically typed language and these hints aren't enforced at runtime, but can allow for a lot of really useful IDE feedback and error checking.

Take for example, the following call where VS Code guesses that the return type is a str and gives autocomplete for that, whereas actually it will either be a dictionary or None:

It also means that you won't be warned by the IDE when passing an incorrect object type in as a parameter:

Example of type annotating a function

As an example, this is how the type annotations would be added to the function below:

def get_project_by_name(project_name, client=default):
    """
    Args:
        project_name (str): Name of claimed project.

    Returns:
        dict: Project corresponding to given name.
    """
    return raw.fetch_first("projects", {"name": project_name}, client=client)

would become:

def get_project_by_name(
    project_name: str, client: KitsuClient = default
) -> dict | None:
    """
    Args:
        project_name (str): Name of claimed project.

    Returns:
        dict: Project corresponding to given name.
    """
    return raw.fetch_first("projects", {"name": project_name}, client=client)

Once this is done, you can see that we get lovely autocompletion and error checking in the IDE, with it being able to validate paramater arguments and give proper autocompletion on returns as it will know the types:

Python compatibility

While some of the type annotation functionality was first introduced in Python 3.10, it can be used in Python 3.7+ versions by simply adding the below import at the top of the file

from __future__ import annotations

As long as that's included there should be no issues with compatibility going back to 3.7 - which I believe is the earliest supported version currently? Correct me if that's wrong.

Changes

These type hints don't have to be introduced wholesale, they can be progressively added over time and multiple PRs - I'm happy to do the leg work of adding the hints, I just want to make sure that it's something that you're interested in before committing the time towards it :) and that you'd be interested in maintaining these annotations moving forwards as the API continues to evolve.

Let me know if there's anything you want me to flesh out more!

Cheers,
Nikhil

[hww-nikhilshankarnoble]

@EvanBldy let me know if you have any thoughts here :)

[johhnry]

Hi @hww-nikhilshankarnoble in order to do that I started making type-stubs for Gazu : https://github.com/johhnry/gazu-stubs
These are not complete and might be missing some subtilities but it works pretty well for now !

This is the alternative from adding the types directly in the source code, but on the other hand it's another package to maintain.

[johhnry]

You're right, that's the main disadvantage. If they drop support for 2.7, what's the minimum 3.x required version then ?

[hww-nikhilshankarnoble]

I haven't found it explicitly stated anywhere yet, but the following release announcement says that <3.6 support was dropped in gazu-0.9.0:
https://discord.com/channels/331817093244780555/719530620853682207/1081176588948869213

From Frank:

Hello all, we did a lot of Kitsu Python dependencies upgrades. Most of them doesn't support old versions of Python. So our next release, the 0.16.0 (Zou and Kitsu) 0.9.0 for Gazu will come with some breaking changes:

• Gazu (the python client for our API) will no longer support Python versions below 3.6.

[hww-nikhilshankarnoble]

@EvanBldy / @frankrousseau would you be able to shed some light on the minimum supported version of Python for the latest gazu version? If Python 3.6 compatibility is still required then Joseph's stub package is probably the best option as the from __future__ import annotations future was only introduced in 3.7

[frankrousseau]

Evan follows Python version better than me. But currently he is on vacation. We will see that when he will be back.

On my side, I don't like much types in Python, but I get that now gazu is stable and widely used. So it makes sense to introduce them. 

[johhnry]

@frankrousseau so there's two options: either you include type hints in Gazu's Python code, either we maintain a community library (like Python typeshed) which is gazu-stubs or another one. Since Gazu doesn't change that much, maintaining the type stubs separately is not a great deal.

For reference, about stub-only packages:

Third parties seeking to distribute stub files are encouraged to contact the maintainer of the package about distribution alongside the package. If the maintainer does not wish to maintain or package stub files or type information inline, then a third party stub-only package can be created.

(Source: https://typing.python.org/en/latest/spec/distributing.html#stub-only-packages)

[hww-nikhilshankarnoble]

Hi @EvanBldy have you had a chance to look at this proposal?

[frankrousseau]

Hi @hww-nikhilshankarnoble,

We can proceed with the typing. We will create a v.1.1.0 that will not support Python <3.7 anymore