PYTHON-2453 Add MongoDB Versioned API

Author: ShaneHarvey

pymongo/bulk.py

@@ -296,6 +296,7 @@ def _execute_command(self, generator, write_concern, session,
                 run.op_type, self.collection.codec_options)
 
             while run.idx_offset < len(run.ops):
+                sock_info.add_server_api(cmd, session)
                 if session:
                     # Start a new retryable write unless one was already
                     # started for this command.

pymongo/client_options.py

@@ -125,6 +125,7 @@ def _parse_pool_options(options):
     event_listeners = options.get('event_listeners')
     appname = options.get('appname')
     driver = options.get('driver')
+    server_api = options.get('server_api')
     compression_settings = CompressionSettings(
         options.get('compressors', []),
         options.get('zlibcompressionlevel', -1))
@@ -138,7 +139,8 @@ def _parse_pool_options(options):
                        _EventListeners(event_listeners),
                        appname,
                        driver,
-                       compression_settings)
+                       compression_settings,
+                       server_api=server_api)
 
 
 class ClientOptions(object):

pymongo/client_session.py

@@ -297,6 +297,9 @@ def __init__(self, opts):
     def active(self):
         return self.state in (_TxnState.STARTING, _TxnState.IN_PROGRESS)
 
+    def starting(self):
+        return self.state == _TxnState.STARTING
+
     def reset(self):
         self.state = _TxnState.NONE
         self.sharded = False
@@ -762,6 +765,12 @@ def in_transaction(self):
         """
         return self._transaction.active()
 
+    @property
+    def _starting_transaction(self):
+        """True if this session is starting a multi-statement transaction.
+        """
+        return self._transaction.starting()
+
     @property
     def _pinned_address(self):
         """The mongos address this transaction was created on."""

pymongo/common.py

@@ -27,6 +27,7 @@
 from pymongo.compression_support import (validate_compressors,
                                          validate_zlib_compression_level)
 from pymongo.driver_info import DriverInfo
+from pymongo.server_api import ServerApi
 from pymongo.encryption_options import validate_auto_encryption_opts_or_none
 from pymongo.errors import ConfigurationError
 from pymongo.monitoring import _validate_event_listeners
@@ -528,6 +529,15 @@ def validate_driver_or_none(option, value):
     return value
 
 
+def validate_server_api_or_none(option, value):
+    """Validate the server_api keyword arg."""
+    if value is None:
+        return value
+    if not isinstance(value, ServerApi):
+        raise TypeError("%s must be an instance of ServerApi" % (option,))
+    return value
+
+
 def validate_is_callable_or_none(option, value):
     """Validates that 'value' is a callable."""
     if value is None:
@@ -643,6 +653,7 @@ def validate_tzinfo(dummy, value):
 NONSPEC_OPTIONS_VALIDATOR_MAP = {
     'connect': validate_boolean_or_string,
     'driver': validate_driver_or_none,
+    'server_api': validate_server_api_or_none,
     'fsync': validate_boolean_or_string,
     'minpoolsize': validate_non_negative_integer,
     'socketkeepalive': validate_boolean_or_string,

pymongo/message.py

@@ -307,6 +307,7 @@ def as_command(self, sock_info):
             self.name = 'explain'
             cmd = SON([('explain', cmd)])
         session = self.session
+        sock_info.add_server_api(cmd, session)
         if session:
             session._apply_to(cmd, False, self.read_preference)
             # Explain does not support readConcern.

pymongo/mongo_client.py

@@ -498,8 +498,18 @@ def __init__(
             and automatically decrypt results. See
             :ref:`automatic-client-side-encryption` for an example.
 
+          | **Versioned API options:**
+          | (If not set explicitly, Versioned API will not be enabled.)
+
+          - `server_api`: A
+            :class:`~pymongo.server_api.ServerApi` which configures this
+            client to use Versioned API.
+
         .. mongodoc:: connections
 
+        .. versionchanged:: 3.12
+           Added the ``server_api`` keyword argument.
+
         .. versionchanged:: 3.11
            Added the following keyword arguments and URI options:
 

pymongo/pool.py

@@ -59,6 +59,7 @@
 from pymongo.network import (command,
                              receive_message)
 from pymongo.read_preferences import ReadPreference
+from pymongo.server_api import _add_to_command
 from pymongo.server_type import SERVER_TYPE
 from pymongo.socket_checker import SocketChecker
 # Always use our backport so we always have support for IP address matching
@@ -309,7 +310,7 @@ class PoolOptions(object):
                  '__wait_queue_timeout', '__wait_queue_multiple',
                  '__ssl_context', '__ssl_match_hostname', '__socket_keepalive',
                  '__event_listeners', '__appname', '__driver', '__metadata',
-                 '__compression_settings', '__max_connecting')
+                 '__compression_settings', '__max_connecting', '__server_api')
 
     def __init__(self, max_pool_size=MAX_POOL_SIZE,
                  min_pool_size=MIN_POOL_SIZE,
@@ -318,7 +319,8 @@ def __init__(self, max_pool_size=MAX_POOL_SIZE,
                  wait_queue_multiple=None, ssl_context=None,
                  ssl_match_hostname=True, socket_keepalive=True,
                  event_listeners=None, appname=None, driver=None,
-                 compression_settings=None, max_connecting=MAX_CONNECTING):
+                 compression_settings=None, max_connecting=MAX_CONNECTING,
+                 server_api=None):
 
         self.__max_pool_size = max_pool_size
         self.__min_pool_size = min_pool_size
@@ -335,6 +337,7 @@ def __init__(self, max_pool_size=MAX_POOL_SIZE,
         self.__driver = driver
         self.__compression_settings = compression_settings
         self.__max_connecting = max_connecting
+        self.__server_api = server_api
         self.__metadata = copy.deepcopy(_METADATA)
         if appname:
             self.__metadata['application'] = {'name': appname}
@@ -487,6 +490,12 @@ def metadata(self):
         """
         return self.__metadata.copy()
 
+    @property
+    def server_api(self):
+        """A pymongo.server_api.ServerApi or None.
+        """
+        return self.__server_api
+
 
 def _negotiate_creds(all_credentials):
     """Return one credential that needs mechanism negotiation, if any.
@@ -697,6 +706,7 @@ def command(self, dbname, spec, slave_ok=False,
             raise ConfigurationError(
                 'Must be connected to MongoDB 3.4+ to use a collation.')
 
+        self.add_server_api(spec, session)
         if session:
             session._apply_to(spec, retryable_write, read_preference)
         self.send_cluster_time(spec, session, client)
@@ -886,6 +896,14 @@ def send_cluster_time(self, command, session, client):
         if self.max_wire_version >= 6 and client:
             client._send_cluster_time(command, session)
 
+    def add_server_api(self, command, session):
+        """Add server_api parameters."""
+        if (session and session.in_transaction and
+                not session._starting_transaction):
+            return
+        if self.opts.server_api:
+            _add_to_command(command, self.opts.server_api)
+
     def update_last_checkin_time(self):
         self.last_checkin_time = _time()
 

pymongo/server_api.py

@@ -0,0 +1,57 @@
+# Copyright 2020-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You
+# may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.  See the License for the specific language governing
+# permissions and limitations under the License.
+
+"""Support for MongoDB Versioned API."""
+
+
+class ServerApiVersion:
+    """An enum that defines values for ServerApi `version`.
+
+    .. versionadded:: 3.12
+    """
+
+    V1 = "1"
+    """Server API version "1"."""
+
+
+class ServerApi(object):
+    """MongoDB Versioned API.
+
+    .. versionadded:: 3.12
+    """
+    def __init__(self, version, strict=None, deprecation_errors=None):
+        if version != ServerApiVersion.V1:
+            raise ValueError("Unknown ServerApi version: %s" % (version,))
+        if strict is not None and not isinstance(strict, bool):
+            raise TypeError(
+                "Wrong type for ServerApi strict, value must be an instance "
+                "of bool, not %s" % (type(strict),))
+        if (deprecation_errors is not None and
+                not isinstance(deprecation_errors, bool)):
+            raise TypeError(
+                "Wrong type for ServerApi deprecation_errors, value must be "
+                "an instance of bool, not %s" % (type(deprecation_errors),))
+        self.version = version
+        self.strict = strict
+        self.deprecation_errors = deprecation_errors
+
+
+def _add_to_command(cmd, server_api):
+    if not server_api:
+        return
+    cmd['apiVersion'] = server_api.version
+    if server_api.strict is not None:
+        cmd['apiStrict'] = server_api.strict
+    if server_api.deprecation_errors is not None:
+        cmd['apiDeprecationErrors'] = server_api.deprecation_errors

pymongo/topology.py

@@ -686,7 +686,8 @@ def _create_pool_for_monitor(self, address):
             ssl_match_hostname=options.ssl_match_hostname,
             event_listeners=options.event_listeners,
             appname=options.appname,
-            driver=options.driver)
+            driver=options.driver,
+            server_api=options.server_api)
 
         return self._settings.pool_class(address, monitor_pool_options,
                                          handshake=False)