o Sb&@s.dZGdddZGdddeZddZdS)a Support for MongoDB Stable API. .. _versioned-api-ref: MongoDB Stable 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:: Stable API requires MongoDB >=5.0. To configure MongoDB Stable 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 >>> >>> # 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 :meth:`~pymongo.database.Database.command` helper. .. note:: Declaring an API version on the :class:`~pymongo.mongo_client.MongoClient` **and** specifying stable 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 ``````````` 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:: >>> 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 ======= c@seZdZdZdZdS)ServerApiVersionz[An enum that defines values for :attr:`ServerApi.version`. .. versionadded:: 3.12 1N)__name__ __module__ __qualname____doc__V1rr9/tmp/pip-target-onvjaxws/lib/python/pymongo/server_api.pyrXsrc@s>eZdZdZd ddZeddZeddZed d ZdS) ServerApizMongoDB Stable API.NcCsv|tjkr td|f|durt|tstdt|f|dur0t|ts0tdt|f||_||_||_ dS)aOptions to configure MongoDB Stable API. :Parameters: - `version`: The API version string. Must be one of the values in :class:`ServerApiVersion`. - `strict` (optional): Set to ``True`` to enable API strict mode. Defaults to ``None`` which means "use the server's default". - `deprecation_errors` (optional): Set to ``True`` to enable deprecation errors. Defaults to ``None`` which means "use the server's default". .. versionadded:: 3.12 zUnknown ServerApi version: %sNzJWrong type for ServerApi strict, value must be an instance of bool, not %szVWrong type for ServerApi deprecation_errors, value must be an instance of bool, not %s) rr ValueError isinstancebool TypeErrortype_version_strict_deprecation_errors)selfversionstrictdeprecation_errorsrrr __init__es"  zServerApi.__init__cC|jS)zfThe API version setting. This value is sent to the server in the "apiVersion" field. )rrrrr rzServerApi.versioncCr)zsThe API strict mode setting. When set, this value is sent to the server in the "apiStrict" field. )rrrrr rrzServerApi.strictcCr)zThe API deprecation errors setting. When set, this value is sent to the server in the "apiDeprecationErrors" field. )rrrrr rszServerApi.deprecation_errors)NN) rrrrrpropertyrrrrrrr r bs   r cCsB|sdS|j|d<|jdur|j|d<|jdur|j|d<dSdS)zInternal helper which adds API versioning options to a command. :Parameters: - `cmd`: The command. - `server_api` (optional): A :class:`ServerApi` or ``None``. NZ apiVersionZ apiStrictZapiDeprecationErrors)rrr)cmdZ server_apirrr _add_to_commands    rN)rrobjectr rrrrr sI ;