fiftyone.core.odm.workspace¶

App Space configuration.

Copyright 2017-2024, Voxel51, Inc.
voxel51.com

Classes:

`AppComponent`(args, *kwargs)	Base class for App components.
`Panel`(args, *kwargs)	Document for a panel (tab) within a Workspace in the App.
`Space`(args, *kwargs)	Document for configuration of a Space in the App.
`WorkspaceDocument`(args, *kwargs)	Document for configuration of a saved workspace in the App.

Functions:

default_workspace_factory()

Creates a default top-level instance of Space

class fiftyone.core.odm.workspace.AppComponent(*args, **kwargs)¶

Bases: fiftyone.core.odm.embedded_document.EmbeddedDocument

Base class for App components.

Attributes:

`component_id`	A unicode string field.
`STRICT`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, …])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields’ values are valid and that required fields are present.

Classes:

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass

component_id¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False¶

clean()¶

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)¶

Clears the field from the document.

Parameters: field_name – the field name
Raises: ValueError – if the field does not exist

copy()¶

Returns a deep copy of the document.

Returns: a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶

Generates a customizable string representation of the document.

Parameters

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names¶: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)¶

field_to_python(field_name, value)¶

classmethod from_dict(d, extended=False)¶

Loads the document from a BSON/JSON dictionary.

Parameters

d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)¶

Loads the document from a JSON string.

Returns: a SerializableDocument

get_field(field_name)¶

Gets the field of the document.

Parameters: field_name – the field name
Returns: the field value
Raises: AttributeError – if the field does not exist

get_text_score()¶: Get text score from text query

has_field(field_name)¶

Determines whether the document has a field of the given name.

Parameters: field_name – the field name
Returns: True/False

iter_fields()¶

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns: an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)¶

Merges the contents of the given document into this document.

Parameters

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass¶

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

mro()

Return a type’s method resolution order.

set_field(field_name, value, create=True)¶

Sets the value of a field of the document.

Parameters

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)¶

Serializes this document to a BSON/JSON dictionary.

Parameters: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns: a dict

to_json(pretty_print=False)¶

Serializes the document to a JSON string.

Parameters: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns: a JSON string

to_mongo(*args, **kwargs)¶: Return as SON data ready for use with MongoDB.

validate(clean=True)¶

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.workspace.Panel(*args, **kwargs)¶

Bases: fiftyone.core.odm.workspace.AppComponent

Document for a panel (tab) within a Workspace in the App.

Parameters

component_id – the component ID
type – the Panel type
pinned – whether the Panel is currently pinned
state – an optional Panel state dict

Attributes:

`type`	A unicode string field.
`pinned`	A boolean field.
`state`	A dictionary field that wraps a standard Python dictionary.
`STRICT`
`component_id`	A unicode string field.
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, …])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields’ values are valid and that required fields are present.

Classes:

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass

type¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

pinned¶

A boolean field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

state¶

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters

field (None) – an optional Field instance describing the type of the values in the dict
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False¶

clean()¶

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)¶

Clears the field from the document.

Parameters: field_name – the field name
Raises: ValueError – if the field does not exist

component_id¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

copy()¶

Returns a deep copy of the document.

Returns: a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶

Generates a customizable string representation of the document.

Parameters

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names¶: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)¶

field_to_python(field_name, value)¶

classmethod from_dict(d, extended=False)¶

Loads the document from a BSON/JSON dictionary.

Parameters

d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)¶

Loads the document from a JSON string.

Returns: a SerializableDocument

get_field(field_name)¶

Gets the field of the document.

Parameters: field_name – the field name
Returns: the field value
Raises: AttributeError – if the field does not exist

get_text_score()¶: Get text score from text query

has_field(field_name)¶

Determines whether the document has a field of the given name.

Parameters: field_name – the field name
Returns: True/False

iter_fields()¶

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns: an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)¶

Merges the contents of the given document into this document.

Parameters

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass¶

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

mro()

Return a type’s method resolution order.

set_field(field_name, value, create=True)¶

Sets the value of a field of the document.

Parameters

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)¶

Serializes this document to a BSON/JSON dictionary.

Parameters: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns: a dict

to_json(pretty_print=False)¶

Serializes the document to a JSON string.

Parameters: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns: a JSON string

to_mongo(*args, **kwargs)¶: Return as SON data ready for use with MongoDB.

validate(clean=True)¶

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.workspace.Space(*args, **kwargs)¶

Bases: fiftyone.core.odm.workspace.AppComponent

Document for configuration of a Space in the App.

Parameters

component_id – the component’s ID
children – the list of Component children of this space, if any
orientation (["horizontal", "vertical"]) – the orientation of this space’s children
active_child – the component_id of this space’s currently active child
sizes – the ordered list of relative sizes for children of a space in [0, 1]

Attributes:

`children`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`orientation`	A unicode string field.
`active_child`	A unicode string field.
`sizes`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`name`
`STRICT`
`component_id`	A unicode string field.
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, …])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields’ values are valid and that required fields are present.

Classes:

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass

children¶

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters

field (None) – an optional Field instance describing the type of the list elements
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

orientation¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

active_child¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

sizes¶

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters

field (None) – an optional Field instance describing the type of the list elements
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

property name¶

STRICT = False¶

clean()¶

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)¶

Clears the field from the document.

Parameters: field_name – the field name
Raises: ValueError – if the field does not exist

component_id¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

copy()¶

Returns a deep copy of the document.

Returns: a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶

Generates a customizable string representation of the document.

Parameters

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names¶: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)¶

field_to_python(field_name, value)¶

classmethod from_dict(d, extended=False)¶

Loads the document from a BSON/JSON dictionary.

Parameters

d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)¶

Loads the document from a JSON string.

Returns: a SerializableDocument

get_field(field_name)¶

Gets the field of the document.

Parameters: field_name – the field name
Returns: the field value
Raises: AttributeError – if the field does not exist

get_text_score()¶: Get text score from text query

has_field(field_name)¶

Determines whether the document has a field of the given name.

Parameters: field_name – the field name
Returns: True/False

iter_fields()¶

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns: an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)¶

Merges the contents of the given document into this document.

Parameters

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass¶

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

mro()

Return a type’s method resolution order.

set_field(field_name, value, create=True)¶

Sets the value of a field of the document.

Parameters

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)¶

Serializes this document to a BSON/JSON dictionary.

Parameters: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns: a dict

to_json(pretty_print=False)¶

Serializes the document to a JSON string.

Parameters: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns: a JSON string

to_mongo(*args, **kwargs)¶: Return as SON data ready for use with MongoDB.

validate(clean=True)¶

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.workspace.WorkspaceDocument(*args, **kwargs)¶

Bases: fiftyone.core.odm.document.Document

Document for configuration of a saved workspace in the App.

Contains a single Space as a child, which can in turn contain multiple children.

Attributes:

`child`	A field that stores instances of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` object.
`color`	A string field that holds a hex color string like ‘#FF6D04’.
`created_at`	A datetime field.
`dataset_id`	An Object ID field.
`description`	A unicode string field.
`last_loaded_at`	A datetime field.
`last_modified_at`	A datetime field.
`slug`	A unicode string field.
`STRICT`
`field_names`	An ordered tuple of the public fields of this document.
`id`	A field wrapper around MongoDB’s ObjectIds.
`in_db`	Whether the document has been inserted into the database.
`name`
`pk`	Get the primary key.

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Methods:

`cascade_save`(**kwargs)	Recursively save any references and generic references on the document.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_index`(key_or_list[, background])	Ensure that the given indexes are in place.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, …])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`modify`([query])	Perform an atomic update of the document in the database and reload the document object using updated version.
`register_delete_rule`(document_cls, …)	This method registers the delete rules to apply when removing this object.
`reload`(fields, *kwargs)	Reloads the document from the database.
`save`([upsert, validate, safe])	Saves the document to the database.
`select_related`([max_depth])	Handles dereferencing of `DBRef` objects to a maximum depth in order to cut down the number queries to mongodb.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`switch_collection`(collection_name[, …])	Temporarily switch the collection for a document instance.
`switch_db`(db_alias[, keep_created])	Temporarily switch the database for a document instance.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields’ values are valid and that required fields are present.

Classes:

my_metaclass

alias of mongoengine.base.metaclasses.TopLevelDocumentMetaclass

child¶

A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object.

Parameters

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

color¶

A string field that holds a hex color string like ‘#FF6D04’.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at¶

A datetime field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

dataset_id¶

An Object ID field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

description¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_loaded_at¶

A datetime field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_modified_at¶

A datetime field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

slug¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

exception DoesNotExist¶

Bases: mongoengine.errors.DoesNotExist

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception MultipleObjectsReturned¶

Bases: mongoengine.errors.MultipleObjectsReturned

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

STRICT = False¶

cascade_save(**kwargs)¶: Recursively save any references and generic references on the document.

clean()¶

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)¶

Clears the field from the document.

Parameters: field_name – the field name
Raises: ValueError – if the field does not exist

classmethod compare_indexes()¶: Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.

copy(new_id=False)¶

Returns a deep copy of the document.

Parameters: new_id (False) – whether to generate a new ID for the copied document. By default, the ID is left as None and will be automatically populated when the document is added to the database

copy_with_new_id()¶

classmethod create_index(keys, background=False, **kwargs)¶

Creates the given indexes if required.

Parameters

keys – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering
background – Allows index creation in the background

delete(signal_kwargs=None, **write_concern)¶

Delete the Document from the database. This will only take effect if the document has been previously saved.

Parameters

signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.
write_concern – Extra keyword arguments are passed down which will be used as options for the resultant getLastError command. For example, save(..., w: 2, fsync: True) will wait until at least two servers have recorded the write and will force an fsync on the primary server.

classmethod drop_collection()¶

Drops the entire collection associated with this Document type from the database.

Raises OperationError if the document has no collection set (i.g. if it is abstract)

classmethod ensure_index(key_or_list, background=False, **kwargs)¶

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters

key_or_list – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering
background – Allows index creation in the background

classmethod ensure_indexes()¶

Checks the document meta data and ensures all the indexes exist.

Global defaults can be set in the meta - see Defining documents

By default, this will get called automatically upon first interaction with the Document collection (query, save, etc) so unless you disabled auto_create_index, you shouldn’t have to call this manually.

Note

You can disable automatic index creation by setting auto_create_index to False in the documents meta data

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶

Generates a customizable string representation of the document.

Parameters

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names¶: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)¶

field_to_python(field_name, value)¶

classmethod from_dict(d, extended=False)¶

Loads the document from a BSON/JSON dictionary.

Parameters

d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)¶

Loads the document from a JSON string.

Returns: a SerializableDocument

get_field(field_name)¶

Gets the field of the document.

Parameters: field_name – the field name
Returns: the field value
Raises: AttributeError – if the field does not exist

get_text_score()¶: Get text score from text query

has_field(field_name)¶

Determines whether the document has a field of the given name.

Parameters: field_name – the field name
Returns: True/False

id¶: A field wrapper around MongoDB’s ObjectIds.

property in_db¶: Whether the document has been inserted into the database.

iter_fields()¶

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns: an iterator that emits (name, value) tuples

classmethod list_indexes()¶

Lists all indexes that should be created for the Document collection. It includes all the indexes from super- and sub-classes.

Note that it will only return the indexes’ fields, not the indexes’ options

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)¶

Merges the contents of the given document into this document.

Parameters

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

modify(query=None, **update)¶

Perform an atomic update of the document in the database and reload the document object using updated version.

Returns True if the document has been updated or False if the document in the database doesn’t match the query.

Note

All unsaved changes that have been made to the document are rejected if the method returns True.

Parameters

query – the update will be performed only if the document in the database matches the query
update – Django-style update keyword arguments

my_metaclass¶

alias of mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

`get_auto_id_names`(new_class)	Find a name for the automatic ID field for the given new class.
`mro`()	Return a type’s method resolution order.

property name¶

property pk¶: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)¶: This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)¶

Reloads the document from the database.

Parameters: *fields – an optional args list of specific fields to reload

save(upsert=False, validate=True, safe=False, **kwargs)¶

Saves the document to the database.

If the document already exists, it will be updated, otherwise it will be created.

Parameters

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns

self

select_related(max_depth=1)¶: Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)¶

Sets the value of a field of the document.

Parameters

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

switch_collection(collection_name, keep_created=True)¶

Temporarily switch the collection for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_collection('old-users')
user.save()

Parameters

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True