Add stub files for pymongo #346
Conversation
There was a problem hiding this comment.
First off, thank you for this effort! And thanks for the patience while our team was away on holiday.
I only gave a quick look through and I have a few questions. I see this is for PyMongo 3.5.1 we'll need to update it for 3.6 before we merge. That will mostly involve adding a session: ClientSession argument to many, many methods but I would hold off on this until we settle on some other decisions.
I think we should only add stubs for the public modules, functions, and classes (basically everything in https://github.com/mongodb/mongo-python-driver/tree/master/doc/api/pymongo). That will reduce the maintenance burden when refactoring pymongo's internals and avoid advertising code that is intended to be private.
More importantly, do you know of a way to automatically test that the stub files correctly describe the code? Perhaps using https://github.com/python/mypy?
| service_name: str | ||
| canonicalize_host_name: bool | ||
| service_realm: Any | ||
| def _build_credentials_tuple(mech: str, source: str, user: str, passwd: str, extra: Dict[str, Any]) -> MongoCredential: ... |
There was a problem hiding this comment.
I don't think we should bother adding type hints to private functions/methods like this. Let's stick to things that are publicly documented.
| UpdateMany, | ||
| ReplaceOne) | ||
| from pymongo.read_preferences import ReadPreference | ||
| from pymongo.write_concern import WriteConcern |
There was a problem hiding this comment.
Are these imports necessary?
|
@behackett: Is type information for |
|
An emphatic yes. That said, we don't currently have the work scheduled, but everyone on the Python team here is interested. |
|
How far away is what's on this PR from what would be acceptable for merging? |
|
Honestly, I don't remember why I closed this. It might have been a mistake. We opened https://jira.mongodb.org/browse/PYTHON-1439 to track it, and it's still open. |
|
@behackett please reopen it then :-) |
|
I think I understand what happened here. The performance branch was deleted (presumably by me not realizing this would happen), which auto closed this PR. Since the target branch was deleted this can't be reopened. It would have to be recreated, preferable against master. |
|
@behackett Thanks for your work on this PR! Is there anything I can do to help get this merged? We're excited to use official type stubs for mongo instead of using our own. |
|
I'd like to provide an update as this project was just completed. While working on this project our team realized that we would be more comfortable following a more conservative approach to adding type hints. Instead of including type annotations or stub files directly in pymongo we decided to ship stub files as a separate package: 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. @GrierPhillips you'll notice that you are already a contributor because I merged these changes as a starting point for the new project. Thank you for your contribution! 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: Or simply install pymongo-stubs to get a better IDE experience: |
This pull request is in reference to the jira ticket Stub Files for PyMongo.
These are the stub files that I use for pymongo version 3.5.1 and I have yet to run into any issues. That is not to say that they have been fully tested. These files would benefit from a review by someone with a better understanding of the internal operations of PyMongo as there are numerous cases where I used Any when I was unsure of an argument or return type.