optional static typing for toolz

[Jasha10]

The type hints described in PEP-484 provide a convenient way to reason about code, and make it possible for static type checkers like mypy to catch type-mismatch errors.

Here is an example of how static type checking might be able to fit in with the toolz library:
Suppose f and g are typed functions defined as follows:

def f(x: A) -> B:
    ...
def g(y: B) -> C:
    ...

Since f is Callable[[A], B] and g is Callable[[B], C], one would expect the composite toolz.compose(g, f) to be Callable[[A], C]. (Here I am using the Callable protocol from the typing module).

Of course, implementing this could be tricky.

[eriknw]

Yeah, this trend is becoming a standard. I'm okay with adding static typing as long as it doesn't hinder readability too much. Hopefully it can be done in a way to improve readability.

Thanks for the suggestion @Jasha10! Are you willing to get this started? I found somebody created some typing information for cytoolz, which may be a good starting point: https://github.com/blindspot-ai/cytoolz-stubs

[Jiehong]

Very good idea!

Using stub files like cytoolz-stubs would not hinder readability much, but it would duplicate all definitions though (https://mypy.readthedocs.io/en/stable/stubs.html#stub-files).

Alternatively, this could be put in the source files directly, with minimal readability impact (IMO, it improves readability). As this uses python 3.5+, and types are supported in python 3.5+, this would not even break compatibility.

(mypy could be used to ensure all types are consistent within this lib as well, as a side effect).

Is there any preferred approach?

[eriknw]

I'd prefer to put annotations in the source files directly. Easier to maintain. It's clear that annotating functions has gained a lot of traction, so it's probably time to jump on the bandwagon.

[multimeric]

I note that toolz supports Python 3.5+. Would a dependency on typing_extensions be acceptable given that there are no other dependencies at the moment? This would expand how expressive we can make the typing.