From 09b18244ccb80c58dc203208cf1ca04f7381f8f7 Mon Sep 17 00:00:00 2001 From: Shane Harvey Date: Tue, 7 Jun 2022 15:46:13 -0400 Subject: [PATCH] PYTHON-3293 Document Queryable Encryption API is in beta (#965) --- doc/changelog.rst | 3 ++- pymongo/collection.py | 15 ++++++++++++++- pymongo/database.py | 16 ++++++++++------ pymongo/encryption.py | 21 +++++++++++++++++---- pymongo/encryption_options.py | 12 ++++++++---- 5 files changed, 51 insertions(+), 16 deletions(-) diff --git a/doc/changelog.rst b/doc/changelog.rst index 5497b4f3e..c53ec2201 100644 --- a/doc/changelog.rst +++ b/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 ......... diff --git a/pymongo/collection.py b/pymongo/collection.py index 9f3f73198..27550e0fb 100644 --- a/pymongo/collection.py +++ b/pymongo/collection.py @@ -159,9 +159,14 @@ class Collection(common.BaseObject, Generic[_DocumentType]): - `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 @@ class Collection(common.BaseObject, Generic[_DocumentType]): 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 @@ class Collection(common.BaseObject, Generic[_DocumentType]): :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 @@ class Collection(common.BaseObject, Generic[_DocumentType]): 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, diff --git a/pymongo/database.py b/pymongo/database.py index 393f63c8c..c9447c1a7 100644 --- a/pymongo/database.py +++ b/pymongo/database.py @@ -336,9 +336,8 @@ class Database(common.BaseObject, Generic[_DocumentType]): :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 @@ class Database(common.BaseObject, Generic[_DocumentType]): - ``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 @@ class Database(common.BaseObject, Generic[_DocumentType]): :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 @@ class Database(common.BaseObject, Generic[_DocumentType]): .. 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. diff --git a/pymongo/encryption.py b/pymongo/encryption.py index a088bd2da..0a8bf69a3 100644 --- a/pymongo/encryption.py +++ b/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 @@ class ClientEncryption(object): :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. diff --git a/pymongo/encryption_options.py b/pymongo/encryption_options.py index eedc2ee23..c5e6f4783 100644 --- a/pymongo/encryption_options.py +++ b/pymongo/encryption_options.py @@ -148,12 +148,12 @@ class AutoEncryptionOpts(object): - `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 @@ class AutoEncryptionOpts(object): } } + .. 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.