ming.encryption module

class ming.encryption.DecryptedField(field_type: type[T], encrypted_field: str)

Creates a field that acts as an automatic getter/setter for the target field name specified encrypted_field.

Note

Interally :class:.DecryptedField uses getattr and setattr on self using the encrypted_field name.

class MyDocument(Document):
    email_encrypted = Field(ming.schema.Binary)
    email = DecryptedField(str, 'email_encrypted')

Parameters:

• field_type – The Type of the decrypted field

• encrypted_field – The name of the encrypted attribute to operate on

class ming.encryption.EncryptedDictWrapper(doc, tracker, schema, instance)

Generic dict wrapper that transparently encrypts/decrypts specified fields.

This class wraps the underlying document data and intercepts get/set operations to automatically decrypt values when reading and encrypt values when writing for fields with the _encrypted suffix convention.

Supports: - Virtual name access (access ‘username’ but store ‘username_encrypted’) - Nested dicts with encrypted fields - Lists with encrypted items or encrypted fields in list items

Parameters:

• doc – The underlying document dict

• tracker – Ming’s state tracker for dirty detection (optional, can be None for Document models)

• schema – The schema defining the field types

• instance – The parent instance (for encryption/decryption methods)

_get_virtual_key(storage_key)

Get the virtual name for a storage key.

_mark_dirty(value)

Mark the value as modified for dirty tracking.

_resolve_key(key)

Resolve a key to its storage name.

Accepts both virtual names (‘username’) and storage names (‘username_encrypted’). Returns the storage name.

keys()

Return virtual names for keys.

class ming.encryption.EncryptedListWrapper(doc, tracker, item_schema, instance, items_encrypted=False)

List wrapper that transparently encrypts/decrypts list items.

This class wraps a list and intercepts get/set operations to automatically decrypt values when reading and encrypt values when writing.

Handles: - Lists of encrypted strings (when parent field has _encrypted suffix) - Lists of dicts with encrypted fields - Nested lists

Parameters:

• doc – The underlying list

• tracker – Ming’s state tracker for dirty detection (optional, can be None for Document models)

• item_schema – Schema for list items (e.g., S.Binary, dict schema, or nested list)

• instance – Parent instance for encryption methods

• items_encrypted – True if list items themselves should be encrypted

_encrypt_item(item)

Encrypt or process a single item for writing.

_mark_dirty()

Mark the list as modified for dirty tracking.

_wrap_item(item)

Wrap or decrypt a single item for reading.

class ming.encryption.EncryptedMixin

A mixin intended to be used with Document or MappedClass to provide encryption. All configuration is handled by an instance of a ming.encryption.EncryptionConfig that is passed to the ming.datastore.DataStore instance that the Document/MappedClass is bound to.

Generally, don’t use this directly, but instead call the methods on the Document/MappedClass you’re working with.

classmethod _encrypted_field_index() → dict[str, object]

Return nested-encryption declarations keyed by field name.

classmethod decr(b: bytes | None) → str | None

Decrypts a string using the encryption configuration of the ming datastore that this class is bound to.

decrypt_some_fields() → dict

Returns a dict with raw data. Removes encrypted fields and replaces them with decrypted data. Useful for json.

classmethod decrypted_field_names() → list[str]

Returns a list of field names that have _encrypted counterts.

For example, if a class has fields email and email_encrypted, this method would return ['email'].

classmethod encr(s: str | None, provider='local') → bytes | None

Encrypts a string using the encryption configuration of the ming datastore that this class is bound to. Most of the time, you won’t need to call this directly, as it is used by the ming.encryption.EncryptedDocumentMixin.encrypt_some_fields() method.

classmethod encrypt_some_fields(data: dict) → dict

Encrypts some fields in a dictionary using the encryption configuration of the ming datastore that this class is bound to.

This handles both: 1. Top-level encrypted fields (e.g., email → email_encrypted) 2. Nested encrypted fields in NestedEncryptedField/NestedEncryptedProperty schemas

(e.g., author.username → author.username_encrypted)

Parameters:

data – a dictionary of data to be encrypted

Returns:

a modified copy of the data param with the currently-unencrypted-but-encryptable fields replaced with _encrypted counterparts.

classmethod encrypted_field_names() → list[str]

Returns the field names of all encrypted fields. Fields are assumed to be encrypted if they end with _encrypted.

For example if a class has fields email and email_encrypted, this method would return ['email_encrypted'].

class ming.encryption.EncryptionConfig(config: dict)

A class to hold the encryption configuration for a ming datastore.

Parameters:

config – a dictionary that closely resembles various features of the MongoDB encryption that we support.

property key_vault_namespace: str

Describes which mongodb database/collection combo your auto-generated encryption data keys will be stored.

This is a string in the format <database>.<collection>.

property kms_providers: dict

Returns the kms providers used in this configuration. These values are passed directly to pymongo.

See the documentation for the pymongo.encryption.ClientEncryption constructor for more information on valid values for kms_providers.

A typical example of the kms_providers field using the local provider would look like this:

property provider_options: dict

Returns all of the provider options used by this configuration when calling the underlying pymongo.encryption.ClientEncryption.create_data_key() method.

See the documentation for pymongo’s pymongo.encryption.ClientEncryption.create_data_key() method for more information on valid values for provider_options.

A typical example of the provider_options field using the local provider would look like this:

exception ming.encryption.MingEncryptionError

class ming.encryption.NestedEncryptedField(*args, **kwargs)

Field declaration for nested dict/list schemas with encrypted leaves.

class ming.encryption.NestedEncryptedFieldDescriptor(field: NestedEncryptedField)

Descriptor for NestedEncryptedField.

class ming.encryption.NestedEncryptedProperty(*args, **kwargs)

FieldProperty declaration for nested dict/list schemas with encrypted leaves.

ming.encryption._analyze_schema(schema)

Analyze a schema to extract field mappings and type information.

Parameters:

schema – The schema dict to analyze

Returns:

A tuple of (virtual_to_storage, storage_to_virtual, encrypted_fields, nested_dicts, nested_lists)

ming.encryption._encrypt_dict_recursive(value, schema, encr_func)

Encrypt a dict value, handling virtual name mapping.

Parameters:

• value – The dict value to encrypt

• schema – The schema defining the dict structure

• encr_func – The encryption function to use

Returns:

A new dict with encrypted values and storage field names

ming.encryption._encrypt_list_recursive(value, schema, encr_func, field_name, force_encrypt=False)

Encrypt a list value.

ming.encryption._encrypt_value_recursive(value, schema, encr_func, field_name=None, force_encrypt=False)

Recursively encrypt a value according to its schema.

ming.encryption._get_virtual_name(storage_name)

Get the user-facing name by stripping the _encrypted suffix.

Parameters:

storage_name – The storage/schema field name (e.g., ‘username_encrypted’)

Returns:

The virtual name for user access (e.g., ‘username’)

ming.encryption._is_dict_schema(schema_type)

Check if a schema type represents a dict.

Parameters:

schema_type – The schema type to check

Returns:

True if the schema represents a dict

ming.encryption._is_encrypted_field(field_name, field_type)

Check if a field should be encrypted based on naming convention.

A field is encrypted if: 1. Its name ends with ‘_encrypted’ 2. Its type is S.Binary

Parameters:

• field_name – The field name to check

• field_type – The schema type of the field

Returns:

True if the field should be encrypted

ming.encryption._is_list_schema(schema_type)

Check if a schema type represents a list.

Parameters:

schema_type – The schema type to check

Returns:

True if the schema represents a list