Provide mypy stubs for the Python SDK

[samschott]

Why is this feature valuable to you? Does it solve a problem you're having?
Type checking of Python code can be incredibly helpful to write readable and maintainable code.

Describe the solution you'd like
Currently, these stubs can be mostly automatically generated from https://github.com/dropbox/dropbox-api-spec using stone. However, it would be convenient if you could make those stubs available as a separate package on PyPI typeshed which gets updated with new releases of the SDK.

[greg-db]

Thanks for sharing this. I'm passing this along as a feature request to the team. I can't promise if or when that might be implemented though.

[SimonSchick]

I think this would be great, in a strict mypy env the dropbox sdk is practically unusable due to mypy/pylance just inferring None for anything, you have all of the return types already in the docstrings, it would be an easy feat to autogenerate the types either inline (this would involve dropping python 2.7, up until 3.7) or generate type stubs.

[pdc1]

+1 from me, I was just about to file a bug about this.

It looks like this in my VS Code (pylance). Each call takes extra time/research to figure out what is actually returned, and then some awkward workarounds to get it to work without type errors. I was surprised given Dropbox's support of Python typing in general.

@samschott Do you have any pointers on how to generate stubs using stone? I only need stubs for a few APIs, but if it is easy to "mostly automatically" generate that sounds like an option.

[samschott]

Sure. To generate the stubs yourself, you'll need to (1) install Dropbox's stone library and (2) clone the repo with Dropbox API spec files at https://github.com/dropbox/dropbox-api-spec.

You then cd to the cloned directory and run:

stone python_type_stubs OUTPUT_DIR *.stone -- --package dropbox

This will generate stub files for all API endpoints ("routes") and their input and return types.

This is incidentally very similar to the commands to generate the Python Dropbox SDK code itself which can be found in generate_base_client.py.

[SimonSchick]

Would it be possible to publish a new major version with type stubs then?
Or do you have strict mandates to keep supporting python 2.x 3.x<7 ?

[pdc1]

Thanks! In case it helps anyone else, I was able to generate stubs in VS Code using the approach documented https://github.com/microsoft/pyright/blob/main/docs/type-stubs.md#generating-type-stubs. It took some fiddling to combine the APIs I used into a combined dropbox.pyi but now the APIs have proper return types!

[greg-db]

Thanks for sharing this! This is still open with the team, but I don't have an update on it.

[SoryRawyer]

Hey folks! Sorry if this isn't the right place, but I wanted to add that I had success generating type stubs using mypy's stubgen. After installing dropbox and mypy, these should be the only commands necessary:

$ MOD_PATH=$(python -c "import os, dropbox; print(os.path.dirname(dropbox.__file__))")
$ stubgen $MOD_PATH -o typings

I preferred this to the methods above since it included the entire codebase, which doesn't seem to be the case with the API spec-based solution (the top-level dropbox module and dropbox.exceptions module, among others, don't seem to be included in the stone output). The pyright-based method seems to generate type hints for the entire codebase, but the hints are inaccurate (for example, functions like files_list_folder had None as their generated return type). stubgen seemed to generate correct types with no manual intervention. I'm using Python 3.11.1, dropbox 11.36.0, pyright 1.1.299, and mypy 1.1.1.

I hope this is helpful, and again I apologize if this isn't the right place for this. This thread helped me get started towards this solution so I'm hoping to repay the favor.

[papadeltasierra]

+1 for me please. it appears the correct thing to do is for the authors to create a types-dropbox package that contains these mypy stub files, just like the requests package provides types-requests. I assume this is trivial since the steps for creating the files are clearly known so why is this not already done?

[greg-db]

Thanks for the feedback!

[papadeltasierra]

Silly question, but could you easily fix this by adding a py.typed file to the root of your package? My very simple testing implies that you could although it does seem to make mypy run slowly, presumably because it is generating typing on the fly from the source code.

[papadeltasierra]

Adding --verbose when running mypy implies that mypy will generate typing on the fly but if the *.pyi files are provided, it uses them instead.

[greg-db]

Thanks for the notes! I can't myself offer a promise on if/how this might be addressed, but I've sent this along to the team.

[papadeltasierra]

One last note, if the dropbox API is basically stable, it appears that adding the type hints to the https://github.com/python/typeshed repo will result in a types-dropbox package being created. This might be another way to go, and appears to be the route taken by the developers of the popular requests package.