Code review fixes (1/x)

- Planning to finish QE setup in the how-to doc then switch back to the
  topic doc to explain the workflow.

Author: aclark4life

django_mongodb_backend/fields/__init__.py

@@ -4,19 +4,18 @@
 from .embedded_model import EmbeddedModelField
 from .embedded_model_array import EmbeddedModelArrayField
 from .encryption import (
-    EncryptedBigIntegerField,
     EncryptedBinaryField,
     EncryptedBooleanField,
     EncryptedCharField,
     EncryptedDateField,
     EncryptedDateTimeField,
     EncryptedDecimalField,
+    EncryptedDurationField,
     EncryptedEmailField,
     EncryptedFieldMixin,
     EncryptedFloatField,
     EncryptedGenericIPAddressField,
     EncryptedIntegerField,
-    EncryptedPositiveBigIntegerField,
     EncryptedPositiveIntegerField,
     EncryptedPositiveSmallIntegerField,
     EncryptedSmallIntegerField,
@@ -33,19 +32,18 @@
     "ArrayField",
     "EmbeddedModelArrayField",
     "EmbeddedModelField",
-    "EncryptedBigIntegerField",
     "EncryptedBinaryField",
     "EncryptedBooleanField",
     "EncryptedCharField",
     "EncryptedDateField",
     "EncryptedDateTimeField",
     "EncryptedDecimalField",
+    "EncryptedDurationField",
     "EncryptedEmailField",
     "EncryptedFieldMixin",
     "EncryptedFloatField",
     "EncryptedGenericIPAddressField",
     "EncryptedIntegerField",
-    "EncryptedPositiveBigIntegerField",
     "EncryptedPositiveIntegerField",
     "EncryptedPositiveSmallIntegerField",
     "EncryptedSmallIntegerField",

django_mongodb_backend/fields/encryption.py

@@ -23,10 +23,6 @@ def deconstruct(self):
         return name, path, args, kwargs
 
 
-class EncryptedBigIntegerField(EncryptedFieldMixin, models.BigIntegerField):
-    pass
-
-
 class EncryptedBinaryField(EncryptedFieldMixin, models.BinaryField):
     pass
 
@@ -51,6 +47,10 @@ class EncryptedDecimalField(EncryptedFieldMixin, models.DecimalField):
     pass
 
 
+class EncryptedDurationField(EncryptedFieldMixin, models.DurationField):
+    pass
+
+
 class EncryptedEmailField(EncryptedFieldMixin, models.EmailField):
     pass
 
@@ -67,10 +67,6 @@ class EncryptedIntegerField(EncryptedFieldMixin, models.IntegerField):
     pass
 
 
-class EncryptedPositiveBigIntegerField(EncryptedFieldMixin, models.PositiveBigIntegerField):
-    pass
-
-
 class EncryptedPositiveIntegerField(EncryptedFieldMixin, models.PositiveIntegerField):
     pass
 

django_mongodb_backend/management/commands/showencryptedfieldsmap.py

@@ -7,21 +7,27 @@
 
 
 class Command(BaseCommand):
-    help = "Generate an `encrypted_fields_map` of encrypted fields for all encrypted"
-    " models in the database for use with `AutoEncryptionOpts` in"
-    " client configuration."
+    help = """
+    This command shows the mapping of encrypted fields to attributes
+    including  data type, data keys and query types. It can be used to set the
+    ``encrypted_fields_map`` in ``AutoEncryptionOpts``. Defaults to showing
+    existing keys from the configured key vault.
+    """
 
     def add_arguments(self, parser):
         parser.add_argument(
             "--database",
             default=DEFAULT_DB_ALIAS,
-            help="Specify the database to use for generating the encrypted"
-            "fields map. Defaults to the 'default' database.",
+            help="""
+            Specifies the database to use. Defaults to ``default``.""",
         )
         parser.add_argument(
             "--create-new-keys",
             action="store_true",
-            help="Create the encrypted fields map.",
+            help="""
+            If specified, this option will create and show new encryption
+            keys instead of showing existing keys from the configured key vault.
+            """,
         )
 
     def handle(self, *args, **options):

docs/source/howto/queryable-encryption.rst

@@ -2,66 +2,83 @@
 Configuring Queryable Encryption
 ================================
 
-.. versionadded:: 5.2.0b2
+.. versionadded:: 5.2.0rc1
 
-.. admonition:: Queryable Encryption Compatibility
+.. admonition:: MongoDB requirements
 
-   You can use Queryable Encryption on a MongoDB 7.0 or later replica
-   set or sharded cluster, but not a standalone instance.
-   :ref:`This table <manual:qe-compatibility-reference>` shows which MongoDB
-   server products support which Queryable Encryption mechanisms.
+    Queryable Encryption can be used with MongoDB replica sets or sharded
+    clusters running version 7.0 or later. Standalone instances are not
+    supported. The following table summarizes which MongoDB server products
+    support each Queryable Encryption mechanism.
 
-Configuring Queryable Encryption in Django is similar to
-:doc:`manual:core/queryable-encryption/quick-start` but with some additional
-steps required for Django.
+    - :ref:`manual:qe-compatibility-reference`
 
-Prerequisites
--------------
+Installation
+============
 
-In addition to :doc:`installing </intro/install>` and :doc:`configuring
-</intro/configure>` Django MongoDB Backend, you will need to install some
-additional packages to use Queryable Encryption. This can be done with the
-optional dependency ``encryption`` in the ``django-mongodb-backend`` package::
+In addition to the :doc:`installation </intro/install>` and :doc:`configuration
+</intro/configure>` steps for Django MongoDB Backend, enabling Queryable
+Encryption requires support for encryption and a Key Management Service (KMS).
+You can install these additional dependencies with the following command::
 
     pip install django-mongodb-backend[encryption]
 
-Settings
---------
+Configuring the ``DATABASES`` setting
+=====================================
 
-Due to a limited set of
-:doc:`manual:core/queryable-encryption/reference/supported-operations`, a second
-encrypted database and corresponding database router are needed to use Queryable
-Encryption in Django, as well as a KMS provider and credentials.
+In addition to :ref:`configuring-databases-setting`, you must also configure an
+encrypted database in your ``DATABASES`` setting.
 
-Here's how to set it up in your Django settings::
+This database will be used to store encrypted fields in your models. The
+following example shows how to configure an encrypted database using the
+``AutoEncryptionOpts`` from the ``pymongo.encryption_options`` module.
+
+This example uses a local KMS provider and a key vault namespace for storing
+encryption keys.
+
+.. code-block:: python
 
     import os
 
     from django_mongodb_backend import parse_uri
     from pymongo.encryption_options import AutoEncryptionOpts
 
     DATABASES = {
-        ...
+        # ...
         "encrypted": parse_uri(
             DATABASE_URL,
             options={
                 "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="my_encrypted_database.keyvault",
+                    key_vault_namespace="keyvault.keyvault",
                     kms_providers={"local": {"key": os.urandom(96)}},
                 )
             },
             db_name="encrypted",
         ),
     }
 
+Configuring the ``DATABASE_ROUTERS`` setting
+============================================
+
+Similar to :ref:`configuring-database-routers-setting` for using embedded
+models, to use Queryable Encryption, you must also configure the
+``DATABASE_ROUTERS`` setting to route queries to the encrypted database.
+
+This is done by adding a custom router that routes queries to the encrypted
+database based on the model's metadata. The following example shows how to
+configure a custom router for Queryable Encryption:
+
+.. code-block:: python
+
     class EncryptedRouter:
         """
-        A database router for an encrypted database to be used with a
-        "patientdata" app that contains models with encrypted fields.
+        A router for routing queries to the encrypted database for Queryable
+        Encryption.
         """
 
         def allow_migrate(self, db, app_label, model_name=None, **hints):
-            # The patientdata app's models are only created in the encrypted database.
+            # The patientdata app's models are only created in the encrypted
+            # database.
             if app_label == "patientdata":
                 return db == "encrypted"
             # Don't create other app's models in the encrypted database.
@@ -72,80 +89,8 @@ Here's how to set it up in your Django settings::
         def kms_provider(self, model, **hints):
             return "local"
 
-    DATABASE_ROUTERS = [EncryptedRouter()]
-
-.. admonition:: KMS providers and credentials
-
-    The above example uses a local KMS provider with a randomly generated
-    key. In a production environment, you should use a secure KMS provider
-    such as AWS KMS, Azure Key Vault, or GCP KMS.
-
-    Please refer to :ref:`manual:qe-fundamentals-kms-providers`
-    for more information on configuring KMS providers and credentials as well as
-    :doc:`manual:core/queryable-encryption/fundamentals/keys-key-vaults`
-    for information on creating and managing data encryption keys.
-
-    You can also refer to the `Python Queryable Encryption Tutorial
-    <https://github.com/mongodb/docs/tree/adad2b1ae41ec81a6e5682842850030813adc1e5/source/includes/qe-tutorials/python>`_.
-
-Encrypted fields map
-~~~~~~~~~~~~~~~~~~~~
-
-In addition to the :ref:`settings described in the how-to guide
-<queryable-encryption-settings>` you will need to provide a
-``encrypted_fields_map`` to the ``AutoEncryptionOpts``.
 
-You can use the :djadmin:`showencryptedfieldsmap` management command to generate
-the schema map for your encrypted fields and then use the results in your
-settings::
-
-    python manage.py showencryptedfieldsmap --database=encrypted
-
-.. admonition:: Didn't work?
-
-    If you get the error ``Unknown command: 'showencryptedfieldsmap'``, ensure
-    ``"django_mongodb_backend"`` is in your :setting:`INSTALLED_APPS` setting.
-
-Crypt shared library
-~~~~~~~~~~~~~~~~~~~~
-
-Additionally, you will need to ensure that the :ref:`crypt shared library is
-available <manual:qe-reference-shared-library>` to your Python environment.
-The crypt shared library is recommended over mongocryptd for Queryable
-Encryption because it doesn't require an additional daemon process to run to
-facilitate Queryable Encryption operations.
-
-Settings
-~~~~~~~~
-
-Now include the crypt shared library path and generated schema map in your
-Django settings::
-
-    from bson.binary import Binary
-    from pymongo.encryption_options import AutoEncryptionOpts
-
-
-    DATABASES["encrypted"] = {
-        ...
-        "OPTIONS": {
-            "auto_encryption_opts": AutoEncryptionOpts(
-                ...
-                crypt_shared_lib_path="/path/to/mongo_crypt_v1",
-                encrypted_fields_map = {
-                    "encryption__patientrecord": {
-                        "fields": [
-                            {
-                                "bsonType": "string",
-                                "path": "ssn",
-                                "queries": {"queryType": "equality"},
-                                "keyId": Binary(b"\x14F\x89\xde\x8d\x04K7\xa9\x9a\xaf_\xca\x8a\xfb&", 4),
-                            },
-                        }
-                    },
-                },
-            ),
-        },
-    }
+    DATABASE_ROUTERS = [EncryptedRouter]
 
-You are now ready to use :doc:`Queryable Encryption
-</topics/queryable-encryption>`.
+Configuring KMS Providers
+=========================

docs/source/index.rst

@@ -23,8 +23,6 @@ Having trouble? We’d like to help!
 
 - Try the :doc:`faq` – it’s got answers to many common questions.
 
-- The :doc:`howto/index` section has step-by-step guides for common tasks.
-
 - Looking for specific information? Try the :ref:`genindex`, :ref:`modindex`,
   or the detailed :doc:`table of contents <contents>`.
 
@@ -48,7 +46,7 @@ Models
 - :doc:`ref/database`
 - :doc:`ref/contrib/gis`
 - :doc:`ref/django-admin`
-- :doc:`ref/queryable-encryption`
+- :doc:`ref/models/encrypted-fields`
 
 **Topic guides:**
 

docs/source/ref/django-admin.rst

@@ -22,14 +22,15 @@ Available commands
 .. django-admin:: showencryptedfieldsmap
 
     This command shows the mapping of encrypted fields to attributes including
-    data type, data keys and query types. Defaults to showing existing keys from
-    the configured key vault.
+    data type, data keys and query types. It can be used to set the
+    ``encrypted_fields_map`` in ``AutoEncryptionOpts``. Defaults to showing
+    existing keys from the configured key vault.
 
     .. django-admin-option:: --database DATABASE
 
         Specifies the database to use. Defaults to ``default``.
 
     .. django-admin-option:: --create-new-keys
 
-        If specified, this option will create new encryption keys for use in
-        production workflows.
+        If specified, this option will create and show new encryption keys
+        instead of showing existing keys from the configured key vault.

docs/source/ref/index.rst

@@ -9,7 +9,7 @@ API reference
    forms
    contrib/index
    database
-   queryable-encryption
+   models/encrypted-fields
    django-admin
    utils
    settings