Creating PyMongo Stubs

[GrierPhillips]

I've been working a fair bit with PyMongo lately and thought it would be nice if there were stub files available.

There currently exists a rather basic and seemingly introductory attempt at making PyMongo stubs at https://github.com/mongodb/deluge/tree/master/server/stubs/pymongo. As I said these seem like a work in progress and don't really cut the mustard for any real use.

Unfortunately, the folks at MongoDB have issues disabled on the PyMongo GitHub Repository so I don't have a good way to get their insight into whether this is something they want to handle internally or not.

As such, I went ahead and created stubs for all of the modules in PyMongo for my own personal use. However, I'm sure there are some rough edges that would need smoothing before sending it out into the world.

I'd be more than happy to make a pull request for this, but wanted to follow the protocol before doing anything rash.

[JelleZijlstra]

Thanks for working on this! We still would like to get permission from the project first before adding stubs to typeshed. From their README (https://github.com/mongodb/mongo-python-driver#support--feedback), it sounds like you should try the mongodb-user email list.

[julien-c]

As far as I understand, they've been adding a similar feature to their roadmap for the official Node.js driver (using Typescript typings) so it could be a good time to ask.

[GrierPhillips]

@julien-c I created an issue in jira (Stub Files for PyMongo) that got some response from developers. It looks like there is desire to keep it within the pymongo project, but they are open to outside help.

[julien-c]

Upvoted and watched. Re. the discussion over there, isn't the simpler way to type-hint the actual code itself? (not sure about this)

[GrierPhillips]

I'm not really sure on that one either. I have used both approaches, and I personally prefer stub files. This is more based on keeping the actual code less verbose, but there is a verbosity/documentation trade off involved.

One thing that seems reasonable to consider when deciding which approach to use would be the regularity with which code changes and the time investment it would take to update .pyi files as opposed to type hints in the code. I can't really speak to that for their situation, but it might be something work bringing up to them.

[srittau]

We are closing all third-party stub requests issues without recent activity. We still welcome pull requests that add these to typeshed, although distributing the stubs with the the third-party package itself is preferable.

[ShaneHarvey]

I'd like to provide an update as this project was recently completed by the PyMongo team and we've released stubs as a separate package in:  pymongo-stubs.

pymongo-stubs' source code is hosted on GitHub (mongodb-labs/pymongo-stubs). The initial release is compatible with PyMongo >=3.11,<4.0 and Python >=3.6.

Our longer term plan is to get feedback on the type hints and later (in PyMongo 4.0) incorporate them directly into the codebase as inline type annotations (in PYTHON-2432). For now you are welcome to try out the stubs like this:

python3 -m pip install pymongo-stubs
python3 -m pip install mypy
mypy <codebase that uses pymongo>

Or simply install pymongo-stubs to get a better IDE experience:

[terencehonles]

I'm glad I bumped into this @ShaneHarvey. I didn't realize these have existed for awhile 😅