PYTHON-3293 Document Queryable Encryption API is in beta (mongodb#965)

Author: ShaneHarvey

doc/changelog.rst

@@ -9,9 +9,10 @@ Changes in Version 4.2
 PyMongo 4.2 brings a number of improvements including:
 
 - Support for MongoDB 6.0.
+- Support for the Queryable Encryption beta with MongoDB 6.0. Note that backwards-breaking
+  changes may be made before the final release.
 - Provisional (beta) support for :func:`pymongo.timeout` to apply a single timeout
   to an entire block of pymongo operations.
-- Beta support for Queryable Encryption with MongoDB 6.0.
 
 Bug fixes
 .........

pymongo/collection.py

@@ -159,9 +159,14 @@ def __init__(
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession` that is used with
             the create collection command
+          - `encrypted_fields`: **(BETA)** Document that describes the encrypted fields for
+            Queryable Encryption. If provided it will be passed to the create collection command.
           - `**kwargs` (optional): additional keyword arguments will
             be passed as options for the create collection command
 
+        .. versionchanged:: 4.2
+           Added ``encrypted_fields`` parameter.
+
         .. versionchanged:: 4.0
            Removed the reindex, map_reduce, inline_map_reduce,
            parallel_scan, initialize_unordered_bulk_op,
@@ -1156,6 +1161,7 @@ def drop(
         self,
         session: Optional["ClientSession"] = None,
         comment: Optional[Any] = None,
+        encrypted_fields: Optional[Mapping[str, Any]] = None,
     ) -> None:
         """Alias for :meth:`~pymongo.database.Database.drop_collection`.
 
@@ -1164,12 +1170,17 @@ def drop(
             :class:`~pymongo.client_session.ClientSession`.
           - `comment` (optional): A user-provided comment to attach to this
             command.
+          - `encrypted_fields`: **(BETA)** Document that describes the encrypted fields for
+            Queryable Encryption.
 
         The following two calls are equivalent:
 
           >>> db.foo.drop()
           >>> db.drop_collection("foo")
 
+        .. versionchanged:: 4.2
+           Added ``encrypted_fields`` parameter.
+
         .. versionchanged:: 4.1
            Added ``comment`` parameter.
 
@@ -1186,7 +1197,9 @@ def drop(
             self.write_concern,
             self.read_concern,
         )
-        dbo.drop_collection(self.__name, session=session, comment=comment)
+        dbo.drop_collection(
+            self.__name, session=session, comment=comment, encrypted_fields=encrypted_fields
+        )
 
     def _delete(
         self,

pymongo/database.py

@@ -336,9 +336,8 @@ def create_collection(
             :class:`~pymongo.collation.Collation`.
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
-          - `encrypted_fields`: Document that describes the encrypted fields for Queryable
-            Encryption.
-            For example::
+          - `encrypted_fields`: **(BETA)** Document that describes the encrypted fields for
+            Queryable Encryption. For example::
 
                 {
                   "escCollection": "enxcol_.encryptedCollection.esc",
@@ -391,6 +390,9 @@ def create_collection(
           - ``comment`` (str): a user-provided comment to attach to this command.
             This option is only supported on MongoDB >= 4.4.
 
+        .. versionchanged:: 4.2
+           Added ``encrypted_fields`` parameter.
+
         .. versionchanged:: 3.11
            This method is now supported inside multi-document transactions
            with MongoDB 4.4+.
@@ -955,9 +957,8 @@ def drop_collection(
             :class:`~pymongo.client_session.ClientSession`.
           - `comment` (optional): A user-provided comment to attach to this
             command.
-          - `encrypted_fields`: Document that describes the encrypted fields for Queryable
-            Encryption.
-            For example::
+          - `encrypted_fields`: **(BETA)** Document that describes the encrypted fields for
+            Queryable Encryption. For example::
 
                 {
                   "escCollection": "enxcol_.encryptedCollection.esc",
@@ -983,6 +984,9 @@ def drop_collection(
         .. note:: The :attr:`~pymongo.database.Database.write_concern` of
            this database is automatically applied to this operation.
 
+        .. versionchanged:: 4.2
+           Added ``encrypted_fields`` parameter.
+
         .. versionchanged:: 4.1
            Added ``comment`` parameter.
 

pymongo/encryption.py

@@ -379,17 +379,26 @@ class Algorithm(str, enum.Enum):
     INDEXED = "Indexed"
     """Indexed.
 
+    .. note:: Support for Queryable Encryption is in beta.
+       Backwards-breaking changes may be made before the final release.
+
     .. versionadded:: 4.2
     """
     UNINDEXED = "Unindexed"
     """Unindexed.
 
+    .. note:: Support for Queryable Encryption is in beta.
+       Backwards-breaking changes may be made before the final release.
+
     .. versionadded:: 4.2
     """
 
 
 class QueryType(enum.IntEnum):
-    """An enum that defines the supported values for explicit encryption query_type.
+    """**(BETA)** An enum that defines the supported values for explicit encryption query_type.
+
+    .. note:: Support for Queryable Encryption is in beta.
+       Backwards-breaking changes may be made before the final release.
 
     .. versionadded:: 4.2
     """
@@ -606,13 +615,17 @@ def encrypt(
             :class:`~bson.binary.Binary` with subtype 4 (
             :attr:`~bson.binary.UUID_SUBTYPE`).
           - `key_alt_name`: Identifies a key vault document by 'keyAltName'.
-          - `index_key_id`: The index key id to use for Queryable Encryption. Must be
+          - `index_key_id`: **(BETA)** The index key id to use for Queryable Encryption. Must be
             a :class:`~bson.binary.Binary` with subtype 4 (:attr:`~bson.binary.UUID_SUBTYPE`).
-          - `query_type` (int): The query type to execute. See
+          - `query_type` (int): **(BETA)** The query type to execute. See
             :class:`QueryType` for valid options.
-          - `contention_factor` (int): The contention factor to use
+          - `contention_factor` (int): **(BETA)** The contention factor to use
             when the algorithm is :attr:`Algorithm.INDEXED`.
 
+        .. note:: `index_key_id`, `query_type`, and `contention_factor` are part of the
+           Queryable Encryption beta. Backwards-breaking changes may be made before the
+           final release.
+
         :Returns:
           The encrypted value, a :class:`~bson.binary.Binary` with subtype 6.
 

pymongo/encryption_options.py

@@ -148,12 +148,12 @@ def __init__(
           - `crypt_shared_lib_path` (optional): Override the path to load the crypt_shared library.
           - `crypt_shared_lib_required` (optional): If True, raise an error if libmongocrypt is
             unable to load the crypt_shared library.
-          - `bypass_query_analysis` (optional):  If ``True``, disable automatic analysis of
-            outgoing commands. Set `bypass_query_analysis` to use explicit
+          - `bypass_query_analysis` (optional): **(BETA)** If ``True``, disable automatic analysis
+            of outgoing commands. Set `bypass_query_analysis` to use explicit
             encryption on indexed fields without the MongoDB Enterprise Advanced
             licensed crypt_shared library.
-          - `encrypted_fields_map`: Map of collection namespace ("db.coll") to documents that
-            described the encrypted fields for Queryable Encryption. For example::
+          - `encrypted_fields_map`: **(BETA)** Map of collection namespace ("db.coll") to documents
+            that described the encrypted fields for Queryable Encryption. For example::
 
                 {
                   "db.encryptedCollection": {
@@ -176,6 +176,10 @@ def __init__(
                   }
                 }
 
+        .. note:: `bypass_query_analysis` and `encrypted_fields_map` are part of the
+           Queryable Encryption beta. Backwards-breaking changes may be made before the
+           final release.
+
         .. versionchanged:: 4.2
            Added `encrypted_fields_map` `crypt_shared_lib_path`, `crypt_shared_lib_required`,
            and `bypass_query_analysis` parameters.