server_api – Support for MongoDB Stable API

Support for MongoDB Stable API.

MongoDB Stable API

Starting in MongoDB 5.0, applications can specify the server API version to use when creating a 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

Stable API requires MongoDB >=5.0.

To configure MongoDB Stable API, pass the server_api keyword option to MongoClient:

>>> 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.

Note

Declaring an API version on the MongoClient and specifying stable API options in 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 MongoClient instance.

Strict Mode

Configuring strict mode will cause the MongoDB server to reject all commands that are not part of the declared ServerApi.version. This includes command options and aggregation pipeline stages.

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 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

class pymongo.server_api.ServerApi(version, strict=None, deprecation_errors=None)

Options to configure MongoDB Stable API.

Parameters:

  • version (str) – The API version string. Must be one of the values in ServerApiVersion.

  • strict (Optional[bool]) – Set to True to enable API strict mode. Defaults to None which means “use the server’s default”.

  • deprecation_errors (Optional[bool]) – Set to True to enable deprecation errors. Defaults to None which means “use the server’s default”.

Added in version 3.12.

property deprecation_errors: bool | None

The API deprecation errors setting.

When set, this value is sent to the server in the “apiDeprecationErrors” field.

property strict: bool | None

The API strict mode setting.

When set, this value is sent to the server in the “apiStrict” field.

property version: str

The API version setting.

This value is sent to the server in the “apiVersion” field.

class pymongo.server_api.ServerApiVersion

An enum that defines values for ServerApi.version.

Added in version 3.12.

V1 = '1'

Server API version “1”.