PYTHON-5328 CRUD Support in Driver for Prefix/Suffix/Substring Indexes (#2521)

blink1073 · web-flow · commit d7316afb632f · 2025-09-10T10:35:35.000-05:00
diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -4,6 +4,13 @@ Changes in Version 4.15.0 (XXXX/XX/XX)
 --------------------------------------
 PyMongo 4.15 brings a number of changes including:
 
+- Added :class:`~pymongo.encryption_options.TextOpts`,
+  :attr:`~pymongo.encryption.Algorithm.TEXTPREVIEW`,
+  :attr:`~pymongo.encryption.QueryType.PREFIXPREVIEW`,
+  :attr:`~pymongo.encryption.QueryType.SUFFIXPREVIEW`,
+  :attr:`~pymongo.encryption.QueryType.SUBSTRINGPREVIEW`,
+  as part of the experimental Queryable Encryption text queries beta.
+  ``pymongocrypt>=1.16`` is required for text query support.
 - Added :class:`bson.decimal128.DecimalEncoder` and :class:`bson.decimal128.DecimalDecoder`
   to support encoding and decoding of BSON Decimal128 values to decimal.Decimal values using the TypeRegistry API.
 
diff --git a/pymongo/asynchronous/encryption.py b/pymongo/asynchronous/encryption.py
@@ -67,7 +67,7 @@
 from pymongo.asynchronous.pool import AsyncBaseConnection
 from pymongo.common import CONNECT_TIMEOUT
 from pymongo.daemon import _spawn_daemon
-from pymongo.encryption_options import AutoEncryptionOpts, RangeOpts
+from pymongo.encryption_options import AutoEncryptionOpts, RangeOpts, TextOpts
 from pymongo.errors import (
     ConfigurationError,
     EncryptedCollectionError,
@@ -516,6 +516,11 @@ class Algorithm(str, enum.Enum):
 
     .. versionadded:: 4.4
     """
+    TEXTPREVIEW = "TextPreview"
+    """**BETA** - TextPreview.
+
+    .. versionadded:: 4.15
+    """
 
 
 class QueryType(str, enum.Enum):
@@ -541,6 +546,24 @@ class QueryType(str, enum.Enum):
     .. versionadded:: 4.4
     """
 
+    PREFIXPREVIEW = "prefixPreview"
+    """**BETA** - Used to encrypt a value for a prefixPreview query.
+
+    .. versionadded:: 4.15
+    """
+
+    SUFFIXPREVIEW = "suffixPreview"
+    """**BETA** - Used to encrypt a value for a suffixPreview query.
+
+    .. versionadded:: 4.15
+    """
+
+    SUBSTRINGPREVIEW = "substringPreview"
+    """**BETA** - Used to encrypt a value for a substringPreview query.
+
+    .. versionadded:: 4.15
+    """
+
 
 def _create_mongocrypt_options(**kwargs: Any) -> MongoCryptOptions:
     # For compat with pymongocrypt <1.13, avoid setting the default key_expiration_ms.
@@ -876,6 +899,7 @@ async def _encrypt_helper(
         contention_factor: Optional[int] = None,
         range_opts: Optional[RangeOpts] = None,
         is_expression: bool = False,
+        text_opts: Optional[TextOpts] = None,
     ) -> Any:
         self._check_closed()
         if isinstance(key_id, uuid.UUID):
@@ -895,6 +919,12 @@ async def _encrypt_helper(
                 range_opts.document,
                 codec_options=self._codec_options,
             )
+        text_opts_bytes = None
+        if text_opts:
+            text_opts_bytes = encode(
+                text_opts.document,
+                codec_options=self._codec_options,
+            )
         with _wrap_encryption_errors():
             encrypted_doc = await self._encryption.encrypt(
                 value=doc,
@@ -905,6 +935,7 @@ async def _encrypt_helper(
                 contention_factor=contention_factor,
                 range_opts=range_opts_bytes,
                 is_expression=is_expression,
+                text_opts=text_opts_bytes,
             )
             return decode(encrypted_doc)["v"]
 
@@ -917,6 +948,7 @@ async def encrypt(
         query_type: Optional[str] = None,
         contention_factor: Optional[int] = None,
         range_opts: Optional[RangeOpts] = None,
+        text_opts: Optional[TextOpts] = None,
     ) -> Binary:
         """Encrypt a BSON value with a given key and algorithm.
 
@@ -937,9 +969,14 @@ async def encrypt(
             used.
         :param range_opts: Index options for `range` queries. See
             :class:`RangeOpts` for some valid options.
+        :param text_opts: Index options for `textPreview` queries. See
+            :class:`TextOpts` for some valid options.
 
         :return: The encrypted value, a :class:`~bson.binary.Binary` with subtype 6.
 
+        .. versionchanged:: 4.9
+           Added the `text_opts` parameter.
+
         .. versionchanged:: 4.9
            Added the `range_opts` parameter.
 
@@ -960,6 +997,7 @@ async def encrypt(
                 contention_factor=contention_factor,
                 range_opts=range_opts,
                 is_expression=False,
+                text_opts=text_opts,
             ),
         )
 
diff --git a/pymongo/encryption_options.py b/pymongo/encryption_options.py
@@ -18,7 +18,7 @@
 """
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Mapping, Optional
+from typing import TYPE_CHECKING, Any, Mapping, Optional, TypedDict
 
 from pymongo.uri_parser_shared import _parse_kms_tls_options
 
@@ -295,3 +295,85 @@ def document(self) -> dict[str, Any]:
             if v is not None:
                 doc[k] = v
         return doc
+
+
+class TextOpts:
+    """**BETA** Options to configure encrypted queries using the text algorithm.
+
+    TextOpts is currently unstable API and subject to backwards breaking changes."""
+
+    def __init__(
+        self,
+        substring: Optional[SubstringOpts] = None,
+        prefix: Optional[PrefixOpts] = None,
+        suffix: Optional[SuffixOpts] = None,
+        case_sensitive: Optional[bool] = None,
+        diacritic_sensitive: Optional[bool] = None,
+    ) -> None:
+        """Options to configure encrypted queries using the text algorithm.
+
+        :param substring: Further options to support substring queries.
+        :param prefix: Further options to support prefix queries.
+        :param suffix: Further options to support suffix queries.
+        :param case_sensitive: Whether text indexes for this field are case sensitive.
+        :param diacritic_sensitive: Whether text indexes for this field are diacritic sensitive.
+
+        .. versionadded:: 4.15
+        """
+        self.substring = substring
+        self.prefix = prefix
+        self.suffix = suffix
+        self.case_sensitive = case_sensitive
+        self.diacritic_sensitive = diacritic_sensitive
+
+    @property
+    def document(self) -> dict[str, Any]:
+        doc = {}
+        for k, v in [
+            ("substring", self.substring),
+            ("prefix", self.prefix),
+            ("suffix", self.suffix),
+            ("caseSensitive", self.case_sensitive),
+            ("diacriticSensitive", self.diacritic_sensitive),
+        ]:
+            if v is not None:
+                doc[k] = v
+        return doc
+
+
+class SubstringOpts(TypedDict):
+    """**BETA** Options for substring text queries.
+
+    SubstringOpts is currently unstable API and subject to backwards breaking changes.
+    """
+
+    # strMaxLength is the maximum allowed length to insert. Inserting longer strings will error.
+    strMaxLength: int
+    # strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+    strMinQueryLength: int
+    # strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+    strMaxQueryLength: int
+
+
+class PrefixOpts(TypedDict):
+    """**BETA** Options for prefix text queries.
+
+    PrefixOpts is currently unstable API and subject to backwards breaking changes.
+    """
+
+    # strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+    strMinQueryLength: int
+    # strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+    strMaxQueryLength: int
+
+
+class SuffixOpts(TypedDict):
+    """**BETA** Options for suffix text queries.
+
+    SuffixOpts is currently unstable API and subject to backwards breaking changes.
+    """
+
+    # strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+    strMinQueryLength: int
+    # strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+    strMaxQueryLength: int
diff --git a/pymongo/synchronous/encryption.py b/pymongo/synchronous/encryption.py
@@ -61,7 +61,7 @@
 from pymongo import _csot
 from pymongo.common import CONNECT_TIMEOUT
 from pymongo.daemon import _spawn_daemon
-from pymongo.encryption_options import AutoEncryptionOpts, RangeOpts
+from pymongo.encryption_options import AutoEncryptionOpts, RangeOpts, TextOpts
 from pymongo.errors import (
     ConfigurationError,
     EncryptedCollectionError,
@@ -513,6 +513,11 @@ class Algorithm(str, enum.Enum):
 
     .. versionadded:: 4.4
     """
+    TEXTPREVIEW = "TextPreview"
+    """**BETA** - TextPreview.
+
+    .. versionadded:: 4.15
+    """
 
 
 class QueryType(str, enum.Enum):
@@ -538,6 +543,24 @@ class QueryType(str, enum.Enum):
     .. versionadded:: 4.4
     """
 
+    PREFIXPREVIEW = "prefixPreview"
+    """**BETA** - Used to encrypt a value for a prefixPreview query.
+
+    .. versionadded:: 4.15
+    """
+
+    SUFFIXPREVIEW = "suffixPreview"
+    """**BETA** - Used to encrypt a value for a suffixPreview query.
+
+    .. versionadded:: 4.15
+    """
+
+    SUBSTRINGPREVIEW = "substringPreview"
+    """**BETA** - Used to encrypt a value for a substringPreview query.
+
+    .. versionadded:: 4.15
+    """
+
 
 def _create_mongocrypt_options(**kwargs: Any) -> MongoCryptOptions:
     # For compat with pymongocrypt <1.13, avoid setting the default key_expiration_ms.
@@ -869,6 +892,7 @@ def _encrypt_helper(
         contention_factor: Optional[int] = None,
         range_opts: Optional[RangeOpts] = None,
         is_expression: bool = False,
+        text_opts: Optional[TextOpts] = None,
     ) -> Any:
         self._check_closed()
         if isinstance(key_id, uuid.UUID):
@@ -888,6 +912,12 @@ def _encrypt_helper(
                 range_opts.document,
                 codec_options=self._codec_options,
             )
+        text_opts_bytes = None
+        if text_opts:
+            text_opts_bytes = encode(
+                text_opts.document,
+                codec_options=self._codec_options,
+            )
         with _wrap_encryption_errors():
             encrypted_doc = self._encryption.encrypt(
                 value=doc,
@@ -898,6 +928,7 @@ def _encrypt_helper(
                 contention_factor=contention_factor,
                 range_opts=range_opts_bytes,
                 is_expression=is_expression,
+                text_opts=text_opts_bytes,
             )
             return decode(encrypted_doc)["v"]
 
@@ -910,6 +941,7 @@ def encrypt(
         query_type: Optional[str] = None,
         contention_factor: Optional[int] = None,
         range_opts: Optional[RangeOpts] = None,
+        text_opts: Optional[TextOpts] = None,
     ) -> Binary:
         """Encrypt a BSON value with a given key and algorithm.
 
@@ -930,9 +962,14 @@ def encrypt(
             used.
         :param range_opts: Index options for `range` queries. See
             :class:`RangeOpts` for some valid options.
+        :param text_opts: Index options for `textPreview` queries. See
+            :class:`TextOpts` for some valid options.
 
         :return: The encrypted value, a :class:`~bson.binary.Binary` with subtype 6.
 
+        .. versionchanged:: 4.9
+           Added the `text_opts` parameter.
+
         .. versionchanged:: 4.9
            Added the `range_opts` parameter.
 
@@ -953,6 +990,7 @@ def encrypt(
                 contention_factor=contention_factor,
                 range_opts=range_opts,
                 is_expression=False,
+                text_opts=text_opts,
             ),
         )
 
diff --git a/test/__init__.py b/test/__init__.py
@@ -32,6 +32,7 @@
 import warnings
 from inspect import iscoroutinefunction
 
+from pymongo.encryption_options import _HAVE_PYMONGOCRYPT
 from pymongo.errors import AutoReconnect
 from pymongo.synchronous.uri_parser import parse_uri
 
@@ -524,6 +525,19 @@ def require_version_max(self, *ver):
             "Server version must be at most %s" % str(other_version),
         )
 
+    def require_libmongocrypt_min(self, *ver):
+        other_version = Version(*ver)
+        if not _HAVE_PYMONGOCRYPT:
+            version = Version.from_string("0.0.0")
+        else:
+            from pymongocrypt import libmongocrypt_version
+
+            version = Version.from_string(libmongocrypt_version())
+        return self._require(
+            lambda: version >= other_version,
+            "Libmongocrypt version must be at least %s" % str(other_version),
+        )
+
     def require_auth(self, func):
         """Run a test only if the server is running with auth enabled."""
         return self._require(
diff --git a/test/asynchronous/__init__.py b/test/asynchronous/__init__.py
@@ -33,6 +33,7 @@
 from inspect import iscoroutinefunction
 
 from pymongo.asynchronous.uri_parser import parse_uri
+from pymongo.encryption_options import _HAVE_PYMONGOCRYPT
 from pymongo.errors import AutoReconnect
 
 try:
@@ -524,6 +525,19 @@ def require_version_max(self, *ver):
             "Server version must be at most %s" % str(other_version),
         )
 
+    def require_libmongocrypt_min(self, *ver):
+        other_version = Version(*ver)
+        if not _HAVE_PYMONGOCRYPT:
+            version = Version.from_string("0.0.0")
+        else:
+            from pymongocrypt import libmongocrypt_version
+
+            version = Version.from_string(libmongocrypt_version())
+        return self._require(
+            lambda: version >= other_version,
+            "Libmongocrypt version must be at least %s" % str(other_version),
+        )
+
     def require_auth(self, func):
         """Run a test only if the server is running with auth enabled."""
         return self._require(
diff --git a/test/asynchronous/test_encryption.py b/test/asynchronous/test_encryption.py
diff --git a/test/test_encryption.py b/test/test_encryption.py
diff --git a/uv.lock b/uv.lock
