mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

PYTHON-2536 Document versioned API usage (#584)

Browse Source 
(cherry picked from commit 1882e99f77)
This commit is contained in:
Prashant Mital 2021-03-31 11:31:06 -05:00 committed by Prashant Mital
parent b18e24a642
commit dfd1e4d028
No known key found for this signature in database
GPG Key ID: 8EFE2B468F727B75
1 changed files with 46 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
pymongo/server_api.py
View File

@ -19,28 +19,67 @@
MongoDB Versioned API
=====================
Starting in MongoDB 5.0, applications can specify the server API version
to use when creating a :class:`~pymongo.mongo_client.MongoClient`. Doing so
ensures that the driver behaves in a manner compatible with that server API
version, regardless of the server's actual release version.
Declaring an API Version
````````````````````````
.. attention:: Versioned API requires MongoDB >=5.0.
To configure MongoDB Versioned API, pass the ``server_api`` keyword option to
:class:`~pymongo.mongo_client.MongoClient`::
from pymongo.mongo_client import MongoClient
from pymongo.server_api import ServerApi
>>> from pymongo.mongo_client import MongoClient
>>> from pymongo.server_api import ServerApi
>>>
>>> # Declare API version "1" for MongoClient "client"
>>> server_api = ServerApi('1')
>>> client = MongoClient(server_api=server_api)
client = MongoClient(server_api=ServerApi('1'))
The declared API version is applied to all commands run through ``client``,
including those sent through the generic
:meth:`~pymongo.database.Database.command` helper.
Note that Versioned API requires MongoDB >=5.0.
.. note:: Declaring an API version on the
:class:`~pymongo.mongo_client.MongoClient` **and** specifying versioned
API options in :meth:`~pymongo.database.Database.command` command document
is not supported and will lead to undefined behaviour.
To run any command without declaring a server API version or using a different
API version, create a separate :class:`~pymongo.mongo_client.MongoClient`
instance.
Strict Mode
```````````
When ``strict`` mode is configured, commands that are not supported in the
given :attr:`ServerApi.version` will fail. For example::
Configuring ``strict`` mode will cause the MongoDB server to reject all
commands that are not part of the declared :attr:`ServerApi.version`. This
includes command options and aggregation pipeline stages.
>>> client = MongoClient(server_api=ServerApi('1', strict=True))
For example::
>>> server_api = ServerApi('1', strict=True)
>>> client = MongoClient(server_api=server_api)
>>> client.test.command('count', 'test')
Traceback (most recent call last):
...
pymongo.errors.OperationFailure: Provided apiStrict:true, but the command count is not in API Version 1, full error: {'ok': 0.0, 'errmsg': 'Provided apiStrict:true, but the command count is not in API Version 1', 'code': 323, 'codeName': 'APIStrictError'
Detecting API Deprecations
``````````````````````````
The ``deprecationErrors`` option can be used to enable command failures
when using functionality that is deprecated from the configured
:attr:`ServerApi.version`. For example::
>>> server_api = ServerApi('1', deprecation_errors=True)
>>> client = MongoClient(server_api=server_api)
Note that at the time of this writing, no deprecated APIs exist.
Classes
=======
"""