This will delete the document associated with the instance
object. If the document does not have an _id–this will
most likely indicate that the document has never been saved–
a TypeError will be raised.

Parameters:

safe (bool.) – (optional) DEPRECATED Use w instead.

w (int.) – (optional) The number of servers that must receive the
update for it to be successful.

Values can be popped from either the end or the beginning of a
list. To pop a value from the end of a list, specify the name of
the field. The pop a value from the beginning of a list,
specify the name of the field with a - in front of it.

If the document does not have an _id–this will
most likely indicate that the document has never been saved–
a TypeError will be raised.

Parameters:

fields (str, list, or tuple.) – The names of the fields to pop from.

safe (bool.) – (optional) DEPRECATED Use w instead.

w (int.) – (optional) The number of servers that must receive the
update for it to be successful.

With MongoDB there are three types of push operations:
$push, $pushAll, add $addToSet. As the name implies,
$pushAll is intended to push all values from a list to the
field, while $push is meant for single values. $addToSet
can be used with either type of value, but it will only add a
value to the list if it doesn’t already contain the value.

This method will determine the correct operator(s) to use based
on the value(s) being pushed. Setting allow_duplicates to
False will use $addToSet instead of $push and
$pushAll. Updates that allow duplicates can combine
$push and $pushAll together.

This can be used to update a single field:

>>> obj.push(field,value)

or to update multiple fields at a time:

>>> obj.push(field1=value1,field2=value2)

If the document does not have an _id–this will
most likely indicate that the document has never been saved–
a TypeError will be raised.

If no fields are indicated–either through field or through
**fields, a ValueError will be raised.

Parameters:

field (str.) – (optional) Name of the field to push to.

value (scalar or list.) – (optional) Value to push to field.

allow_duplicates (bool.) – (optional) Whether to allow duplicate
values to be added to the list

safe (bool.) – (optional) DEPRECATED Use w instead.

w (int.) – (optional) The number of servers that must receive the
update for it to be successful.

If only a select number of fields need to be updated, an atomic
update is preferred over a document replacement.
save_fields() takes either a single field name or a list of
field names to update.

All of the specified fields must exist or an
AttributeError will be raised. To add a field to the
document with a blank value, make sure to assign it through
object.attribute='' or something similar before calling
save_fields().

If the document does not have an _id–this will
most likely indicate that the document has never been saved–
a TypeError will be raised.

If only a select number of fields need to be updated, an atomic
update is preferred over a document replacement.
update() takes a series of fields and values through its
keyword arguments. This fields will be updated both in the
database and on the instance.

If the document does not have an _id–this will
most likely indicate that the document has never been saved–
a TypeError will be raised.

This is a convenience method for more complex $near queries. For
simple queries that simply use the point, the regular query syntax
of field__near=[x,y] will suffice. This method provides a way
to include $maxDistance and (if support is added)
$uniqueDocs without needing to structure the query as
field={'$near':[x,y],'$maxDistance':z}.

Note

As of the current release of MongoDB (2.2), $near queries do
not support the $uniqueDocs parameter. It is included here so
that when support is added to MongoDB, no changes to the library
will be needed. - 11 November 2012

Parameters:

point (list, containing exactly two elements.) – The point to use for the geospatial lookup.

max_distance (int.) – (optional) The maximum distance a point can be
from point.

WARNING
The functionality in this module is intended for internal use by Simon.
If using anything in this module directly, be careful when updating
versions of Simon as no guarantees are made about the backward
compatability of its API.

Python includes microseconds in its datetime values. MongoDB,
on the other hand, only retains them down to milliseconds. This
method will not only get the current time in UTC, but it will also
remove microseconds from the value.

This method will convert a value to an ObjectId. If
value is a dict (e.g., with a comparison operator as the key
), the value in the dict will be converted. Any values that are
a list or tuple will be iterated over, and replaced with a
list containing all ObjectId instances.

TypeError will be raised for any value that cannot be
converted to an ObjectId. InvalidId will be raised
for any value that is of the right type but is not a valid value
for an ObjectId.

This method checks for operators in document. If a spec
document is provided instead of a document to save or update, a
false positive will be reported if a logical operator such as
$and or $or is used.

Attribute names will be mapped to document keys using the mapping
specified in field_map. If any of the attribute names contain
__, parse_kwargs() will be called and a second pass
through cls._meta.field_map will be performed.

The two-pass approach is used to allow for keys in embedded
documents to be mapped. Without the first pass, only keys of the
root document could be mapped. Without the second pass, only keys
that do not contain embedded document could be mapped.

The $and and $or operators cannot be mapped to different
keys. Any occurrences of these operators as keys should be
accompanied by a list of dict``s.Each``dict will be put
back into map_fields() to ensure that keys nested within
boolean queries are mapped properly.

If with_operators is set, the following operators will be
checked for and included in the result:

$gt the key’s value is greater than the value given

$gte the key’s value is greater than or equal to the value
given

$lt the key’s value is less than the value given

$lte the key’s value is less than or equal to the value given

$ne the key’s value is not equal to the value given

$all the key’s value matches all values in the given list

$in the key’s value matches a value in the given list

$nin the key’s value is not within the given list

$exists the the key exists

$near the key’s value is near the given location

$size the key’s value has a length equal to the given value

$elemMatch the key’s value is an array satisfying the given
query

To utilize any of the operators, append __ and the name of the
operator sans the $ (e.g., __gt, __lt) to the name of
the key:

map_fields(mapping,{'a__gt':1,'b__lt':2},with_operators=True)

This will check for a greater than 1 and b less than 2 as:

{'a':{'$gt':1},'b':{'$lt':2}}

The $not operator can be used in conjunction with any of the
above operators:

map_fields(mapping,{'a__gt':1,'b__not__lt':2},with_operators=True)

This will check for a greater than 1 and b not less than 2 as:

{'a':{'$gt':1},'b':{'$not':{'$lt':2}}}

If flatten_keys is set, all keys will be kept at the top level
of the result dictionary, using a . to separate each part of a
key. When this happens, the second pass will be omitted.

Parameters:

field_map (dict.) – Key/value pairs defining the field map.

fields (dict.) – Key/value pairs to be used for queries.

with_operators (bool.) – (optional) Whether or not to process
operators.

flatten_keys (bool.) – (optional) Whether to allow the nested keys to
be nested.