Adding type hints so static analyzers like mypy can work with google.cloud.storage

[maroux]

Thanks for stopping by to let us know something could be better!

PLEASE READ: If you have a support contract with Google, please create an issue in the support console instead of filing on GitHub. This will ensure a timely response.

Is your feature request related to a problem? Please describe.
Tools like mypy can use type hints to run static analysis on your code to find bugs in incorrect type usage.
Describe the solution you'd like
Mypy requires type hints to be exported by the library, either as part of the library and exported per PEP 484, or as a separate stubs library per PEP 561.
Describe alternatives you've considered
Currently we're ignoring all typing information for this library.
Additional context

[dahlbaek]

This would be an amazing feature! Is there any information on the current status?

[sshishov]

Also waiting for this feature as type hints become pretty standard in python nowadays.

[Goldziher]

this is pretty ridiculous that this is missing.

[rmorshea]

How to Fix This

I see a number of different approaches the folks at Google could take to resolve this issue.

Use Runtime Types

The most obvious one would be to use an off-the-shelf tool to generate type hints from types observed at runtime:

• https://pypi.org/project/MonkeyType/
• https://github.com/dropbox/pyannotate

It ought to be relatively trivial to get those runtime types by executing this library's test suite.

While these wouldn't be perfect, it'd at least be a starting point. Over time users could contribute fixes to any incorrect/incomplete annotations that were generated initially.

Use Docstring Types

Beyond this the code base appears to have relatively thorough docstrings which describe the expected types (e.g. get_bucket). There are some :type ...: directives that appear to be somewhat arbitrary (e.g. this timeout parameter) but overall these docstrings seem like they'd be a great starting point from which to generate real annotations with relatively minimal effort.

Why This Matters

As mentioned above, type annotations have become the norm in Python. Similar offerings from AWS (types-boto3) and Azure (built-in) already include very thorough type hints. Personally my experience with Google's product offering here has been lessened by the fact that I have to constantly refer to documentation or dig into docstrings as apposed to having type the hints show up and auto-complete in my IDE. One could pretty easily argue that this has a relatively marginal impact, but if I had to guess, that's where cloud platforms are competing since most common product offerings are nearly identical when it comes to features and pricing.

Beyond the broader business case, type hints would help the maintainers of this library for the same reasons it would help their users. Additionally, unlike docstrings, the accuracy of type hints can be enforced by a type checker. Without this, ensuring that types in docstring remain up to date with their usages is the responsibility of human code reviewers instead of a machine.