PYTHON-2453 Document db.command interaction, requireApiVersion1, other improvements

Author: ShaneHarvey

.evergreen/config.yml

@@ -2028,8 +2028,8 @@ axes:
   - id: requireApiVersion
     display_name: "requireApiVersion"
     values:
-      - id: "requireApiVersion"
-        display_name: "requireApiVersion"
+      - id: "requireApiVersion1"
+        display_name: "requireApiVersion1"
         tags: [ "requireApiVersion_tag" ]
         variables:
           REQUIRE_API_VERSION: "1"
@@ -2625,6 +2625,7 @@ buildvariants:
     requireApiVersion: "*"
   display_name: "requireApiVersion ${python-version}"
   tasks:
+    # Versioned API was introduced in MongoDB 4.7
     - "test-latest-standalone"
 
 - matrix_name: "ocsp-test"

pymongo/database.py

@@ -704,6 +704,12 @@ def command(self, command, value=1, check=True,
         .. note:: :meth:`command` does **not** apply any custom TypeDecoders
            when decoding the command response.
 
+        .. note:: If this client has been configured to use MongoDB Versioned
+           API (see :ref:`versioned-api-ref`), then :meth:`command` will
+           automactically add API versioning options to the given command.
+           Explicitly adding API versioning options in the command and
+           declaring an API version on the client is not supported.
+
         .. versionchanged:: 3.6
            Added ``session`` parameter.
 

pymongo/server_api.py

@@ -114,6 +114,12 @@ def deprecation_errors(self):
 
 
 def _add_to_command(cmd, server_api):
+    """Internal helper which adds API versioning options to a command.
+
+    :Parameters:
+      - `cmd`: The command.
+      - `server_api` (optional): A :class:`ServerApi` or ``None``.
+    """
     if not server_api:
         return
     cmd['apiVersion'] = server_api.version

test/__init__.py

@@ -779,8 +779,9 @@ def sanitize_cmd(cmd):
     cp.pop('$db', None)
     cp.pop('$readPreference', None)
     cp.pop('lsid', None)
-    # Versioned api parameters
-    cp.pop('apiVersion', None)
+    if MONGODB_API_VERSION:
+        # Versioned api parameters
+        cp.pop('apiVersion', None)
     # OP_MSG encoding may move the payload type one field to the
     # end of the command. Do the same here.
     name = next(iter(cp))