Plan: adding type annotations one function at a time

[hunterhogan]

The General Plan

1. Submit a pull request to add type annotations to only one function.
2. Work with the maintainers to merge the pull request.
3. If another function doesn't have type annotations, go back to step 1.

Prototype Pull Requests

1. Remove unneeded compatibility.py module #620
2. Add inline typing to assoc function in dicttoolz #621

Prototype process

• Add type annotations to toolz and cytoolz hunterhogan/hunterMakesPy#8
• List of pull requests for pytoolz/toolz and pytoolz/cytoolz hunterhogan/hunterMakesPy#6

For example:

• dicttoolz hunterhogan/hunterMakesPy#3
• dicttoolz.dissoc hunterhogan/hunterMakesPy#7

Group effort

Many people have said they want type annotations in toolz, so I hope some of them will get involved. I don't think I can do this by myself. @getzze @mgrinshpon @OutSquareCapital

[mgrinshpon]

@eriknw has stated that this library is in maintenance mode and no further changes are planned outside of python version compatibility. While I wouldn't be upset to no longer maintain toolz-stubs because the library is py.typed, the stubs do work and are pip installable.

[hunterhogan]

@eriknw has stated that this library is in maintenance mode and no further changes are planned outside of python version compatibility.

True. I hope that this plan will make it easier for him to enforce that boundary. It's counterintuitive, so I'll explain a little.

Pressure for types

In this repo and in cytoolz, people have posted Issues, Pull Requests, and comments requesting typing. In one PR, @eriknw wrote:

wow, nice! Thanks @getzze! I'm in the process of moving so it may take me some time to properly review this, but know that this is appreciated and likely to go in :)

#576 (comment)

A few people, such as you, put effort into creating stubs. But most people have essentially said, "I want the maintainers of this project to do more work!" Since the past is prologue, we can assume that other people will continue to pressure the maintainers to do a lot more work.

Two months ago, for example, I think someone more-or-less copy-pasted https://github.com/mgrinshpon/toolz-stubs into one giant pull request in the cytoolz repo. The maintainers didn't need help with copy and paste.

A healthier process

Instead of immediately submitting a PR for every function, I have created a staging area. hunterhogan/hunterMakesPy#6 If the maintainers choose not to merge the PRs, I will not dump 40 PR into the repo. If they want to merge, they can choose the pace.

If other people want typing annotations, I hope they will choose to help create the annotations instead of demanding that the maintainers do more work. They can help by writing annotations or reviewing the existing pull requests, suggesting improvements, or expressing support, which decreases the pressure on the maintainers.

They can help by contributing to the existing stub files in your project (https://github.com/mgrinshpon/toolz-stubs). I want to improve the prototype process by steering people towards those healthier, more helpful options and away from telling the maintainers to do more work.