From 9437d9ee733b6150e473edfe6179d050f5246d42 Mon Sep 17 00:00:00 2001 From: Prashant Mital Date: Tue, 30 Mar 2021 16:48:53 -0500 Subject: [PATCH 1/4] PYTHON-2536 Document Versioned API Usage --- pymongo/server_api.py | 48 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/pymongo/server_api.py b/pymongo/server_api.py index cf739659e3..b4eb3024bb 100644 --- a/pymongo/server_api.py +++ b/pymongo/server_api.py @@ -19,28 +19,62 @@ 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 +```````````````````````` + 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 - - client = MongoClient(server_api=ServerApi('1')) + >>> 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) + +The declared API version is applied to all commands run through ``client``, +including those sent through the generic command helper. Specifying versioned +API options in the command document **and** declaring an API version +on the client 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. Note that Versioned API requires MongoDB >=5.0. 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. + +For example:: - >>> client = MongoClient(server_api=ServerApi('1', strict=True)) + >>> 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 ======= """ From 200ba97a5c159a9c0141166cb95e6806769f32cc Mon Sep 17 00:00:00 2001 From: Prashant Mital Date: Wed, 31 Mar 2021 00:27:10 -0500 Subject: [PATCH 2/4] add whitespace around '=' --- pymongo/server_api.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pymongo/server_api.py b/pymongo/server_api.py index b4eb3024bb..4984877616 100644 --- a/pymongo/server_api.py +++ b/pymongo/server_api.py @@ -56,7 +56,7 @@ For example:: - >>> server_api=ServerApi('1', strict=True) + >>> server_api = ServerApi('1', strict=True) >>> client = MongoClient(server_api=server_api) >>> client.test.command('count', 'test') Traceback (most recent call last): @@ -70,7 +70,7 @@ when using functionality that is deprecated from the configured :attr:`ServerApi.version`. For example:: - >>> server_api=ServerApi('1', deprecation_errors=True) + >>> 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. From d6f40ad3637d0ced17747f3dc379cb51888df90f Mon Sep 17 00:00:00 2001 From: Prashant Mital Date: Wed, 31 Mar 2021 01:02:43 -0500 Subject: [PATCH 3/4] cleanup --- pymongo/server_api.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/pymongo/server_api.py b/pymongo/server_api.py index 4984877616..5cbe0edd08 100644 --- a/pymongo/server_api.py +++ b/pymongo/server_api.py @@ -27,6 +27,8 @@ 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`:: @@ -38,15 +40,18 @@ >>> client = MongoClient(server_api=server_api) The declared API version is applied to all commands run through ``client``, -including those sent through the generic command helper. Specifying versioned -API options in the command document **and** declaring an API version -on the client is not supported and will lead to undefined behaviour. +including those sent through the generic +:meth:`~pymongo.database.Database.command` helper. + +.. 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. -Note that Versioned API requires MongoDB >=5.0. - Strict Mode ``````````` From 6f21c023b7327c79f2e406cdcb5419a1201b6754 Mon Sep 17 00:00:00 2001 From: Prashant Mital Date: Wed, 31 Mar 2021 11:28:31 -0500 Subject: [PATCH 4/4] use two colons --- pymongo/server_api.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pymongo/server_api.py b/pymongo/server_api.py index 5cbe0edd08..4a1b925ca9 100644 --- a/pymongo/server_api.py +++ b/pymongo/server_api.py @@ -27,7 +27,7 @@ Declaring an API Version ```````````````````````` -.. attention: Versioned API requires MongoDB >=5.0. +.. attention:: Versioned API requires MongoDB >=5.0. To configure MongoDB Versioned API, pass the ``server_api`` keyword option to :class:`~pymongo.mongo_client.MongoClient`::