Typing issues with `invoke.tasks.task` decorator

Start at the public invoke.tasks.task decorator and compare its current annotations with the complete .pyi typings in the linked soucelover/invoke-issue repository. Check the example under a strict Pyright configuration; done means the decorator and its return type no longer produce the reported partially unknown or untyped-decorator errors.

Issue

Public function invoke.tasks.task is very poorly typed. There is no specification for parameters, but that's not a very big deal. Return type is incomplete though (Callable generic type requires arguments), and it can result in type checkers showing errors.

from invoke.tasks import task  # Error: Type of "task" is partially unknown\nType of "task" is "(...) -> ((...) -> Unknown)"


@task  # Error: Untyped function decorator obscures type of function; ignoring decorator
def up(ctx: Context, ...) -> None:
    ...

Frankly, didn't test with other type checkers. Only with Pyrefly, but it silently approves unknown types in default configuration, so it doesn't show any errors.

Fix for type hints

Some time before I've tried to address this issue and created typings for our command to work with. We work with strict Pyright configuration, so it's important that it at least doesn't show errors for code of external libraries itself.

Those typings can be seen in this repo: https://github.com/soucelover/invoke-issue. You can use them to improve types of the task decorator.

If you want, I can look through types and code, edit type hints and create a pull request. It's no more than a couple of hours of somewhat meticulous work, so, considering there's a whole complete set of typing files in the repo above, you'll simply need to review my code and see if those typings are the way to go.

By the way, I think I've taken some type ideas from types-invoke library. It's obsolete by now, but in some places it's better typed than current invoke code. And surely, I didn't use LLMs for types, so it's at least not a slop code.

Also, .pyi files in the repo cover the whole library with some things that can be called private interfaces. I can't tell whether other functions and classes need to be retyped, I don't remember what type hints differ, but that's the thing for if I'll get to work with types in this repo.

Motivation

Well, invoke features pretty good typing: all functions have type hints and some classes use generics. So, maybe, there's need for me to write about this, but anyway.

I think public interfaces in frequently used libraries and tools compatible with latest versions of Python at least should be well-typed. And by that I mean most of the type checking work flows should work as intended, even if it's Pyright in strict mode or somewhat customized mypy.

Better types are always better as all better things, but they might not be the priority or break historical conventions. So it's reasonable if there is some intention to the way type hints are written right now. But otherwise, let's work with it.