PYTHON-2453 Add documentation

Author: ShaneHarvey

doc/api/pymongo/index.rst

@@ -54,6 +54,7 @@ Sub-modules:
    read_preferences
    results
    son_manipulator
+   server_api
    uri_parser
    write_concern
    event_loggers

doc/api/pymongo/server_api.rst

@@ -0,0 +1,11 @@
+:mod:`server_api` -- Support for MongoDB Versioned API
+======================================================
+
+.. automodule:: pymongo.server_api
+   :synopsis: Support for MongoDB Versioned API
+
+   .. autoclass:: pymongo.server_api.ServerApi
+      :members:
+
+   .. autoclass:: pymongo.server_api.ServerApiVersion
+      :members:

doc/changelog.rst

@@ -9,6 +9,11 @@ Breaking Changes in 4.0
 
 - Removed :mod:`~pymongo.thread_util`.
 
+Notable improvements
+....................
+
+- Support for MongoDB Versioned API, see :class:`~pymongo.server_api.ServerApi`.
+
 Issues Resolved
 ...............
 

pymongo/mongo_client.py

@@ -503,7 +503,8 @@ def __init__(
 
           - `server_api`: A
             :class:`~pymongo.server_api.ServerApi` which configures this
-            client to use Versioned API.
+            client to use Versioned API. See :ref:`versioned-api-ref` for
+            details.
 
         .. mongodoc:: connections
 

pymongo/server_api.py

@@ -12,11 +12,42 @@
 # implied.  See the License for the specific language governing
 # permissions and limitations under the License.
 
-"""Support for MongoDB Versioned API."""
+"""Support for MongoDB Versioned API.
+
+.. _versioned-api-ref:
+
+MongoDB Versioned API
+=====================
+
+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'))
+
+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::
+
+    >>> client = MongoClient(server_api=ServerApi('1', strict=True))
+    >>> 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'
+
+Classes
+=======
+"""
 
 
 class ServerApiVersion:
-    """An enum that defines values for ServerApi `version`.
+    """An enum that defines values for :attr:`ServerApi.version`.
 
     .. versionadded:: 3.12
     """
@@ -26,11 +57,21 @@ class ServerApiVersion:
 
 
 class ServerApi(object):
-    """MongoDB Versioned API.
-
-    .. versionadded:: 3.12
-    """
+    """MongoDB Versioned API."""
     def __init__(self, version, strict=None, deprecation_errors=None):
+        """Options to configure MongoDB Versioned 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
+        """
         if version != ServerApiVersion.V1:
             raise ValueError("Unknown ServerApi version: %s" % (version,))
         if strict is not None and not isinstance(strict, bool):
@@ -42,9 +83,34 @@ def __init__(self, version, strict=None, deprecation_errors=None):
             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
+        self._version = version
+        self._strict = strict
+        self._deprecation_errors = deprecation_errors
+
+    @property
+    def version(self):
+        """The API version setting.
+
+        This value is sent to the server in the "apiVersion" field.
+        """
+        return self._version
+
+    @property
+    def strict(self):
+        """The API strict mode setting.
+
+        When set, this value is sent to the server in the "apiStrict" field.
+        """
+        return self._strict
+
+    @property
+    def deprecation_errors(self):
+        """The API deprecation errors setting.
+
+        When set, this value is sent to the server in the
+        "apiDeprecationErrors" field.
+        """
+        return self._deprecation_errors
 
 
 def _add_to_command(cmd, server_api):