[mg]

I don't really like types on the function declaration line.

Instead of this:

    def check_permission(user: User, perm: str, obj: BaseModel | None) -> bool:

I find it much nicer to read something this:

    """
    Check if user is allowed to drive a car
    :user: User             # The application's User model
    :perm: str              # Our magic permission string. Tab seperated.
    :obj : Basemodel | None # Base model of all our objects since 2017
    :returns bool           # True if the user is allowed to drive
    """
    def check_permission(user, perm, obj):

This way I can grok the code much faster and only have to look into the type declaration when I want to. Due to syntax highlighting, it will look really nice. Because the whole type part can be styled in a dimmer color which puts it into the background. And I can define a key combo to show/hide the whole type part.

[Malcolmlisk]

You can do that as a docstring inside the function. There are even some basic rules like...

def extract_coordiates( unreseted_idx_from_df, json_data: dict, notna_idxs: list, na_idxs: list ) -> list:

    """
    Extracting coordinates from the json_data['data'] and returning the 4
    positions of those as an array

    Parameters
    ----------
    json_data: json
        Data extracted from tabula.read_pdf and using output_format='json'
    notna_idxs: list
        List of id's from the dataframe that ha no na values.
    na_idxs: list
        List of id's from the dataframe with na

    Returns
    -------
    List of tuple coordinates:
        [(1, 2), (2, 2), (4, 3), (1, 4)]
    """

Thing is, that you may want to get fast information in the linter with this type hinting. If you need to read the documentation on big functions over and over, that means that's not clear at all, and having basic type hinting while typing the atributes is going to be clearer.

You are right, that some docstrings are necesary. But that does not mean that is the best practice. The best practice is use both, type hinting and docstrings.

[zokier]

I think you misinterpreted parent comment. My reading was that they would have preferred type-hints to be defined as part of docstring style comments instead of having the type hints inline with the code. From tooling point of view it doesn't make any difference, both forms should be functionally equivalent.

[nerdponx]

Sphinx does process type hints in docstring comments, but I'm grateful that Mypy didn't take the approach of requiring a docstring.

[zokier]

What do you think of the py27 backcompat type hint syntax using `# type:` comments: https://peps.python.org/pep-0484/#suggested-syntax-for-pytho...

[mg]

Same. I don't like that the meta stuff inside the function. I prefer to have the function be pure code.