The following is a look into the API inside Simon.
Manage database connections
Connect to a database.
Parameters: |
|
---|---|
Returns: | pymongo.database.Database – the database. |
Raises : |
Changed in version 0.2.0: connect() now accepts replica_set as a kwarg, it is preferred over replicaSet
Return a reference to a database.
Parameters: | name (str.) – The name of the database. |
---|---|
Returns: | pymongo.database.Database – a database object. |
Raised when a database connection cannot be opened.
Base class for all Simon models.
Raised when more than one document is found.
Raised when an object matching a query is not found.
Return all documents in the collection.
If sort has been defined on the Meta class it will be used to order the records.
Create a new document and saves it to the database.
This is a convenience method to create a new document. It will instantiate a new Model from the keyword arguments, call save(), and return the instance.
If the model has the required_fields options set, a TypeError will be raised if any of the fields are not provided.
Parameters: |
|
---|---|
Returns: | Model – the new document. |
Raises : | TypeError |
Delete a single document from the database.
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: |
|
---|---|
Raises : | TypeError |
Return multiple documents from the database.
This will find a return multiple documents matching the query specified through **fields. If sort has been defined on the Meta class it will be used to order the records.
Parameters: |
|
---|---|
Returns: | QuerySet – query set containing objects matching query. |
Changed in version 0.3.0: qs is being deprecated in favor of q
Return a single document from the database.
This will find and return a single document matching the query specified through **fields. An exception will be raised if any number of documents other than one is found.
Parameters: |
|
---|---|
Returns: | Model – object matching query. |
Raises : |
Changed in version 0.3.0: qs is being deprecated in favor of q
Return an existing or create a new document.
This will find and return a single document matching the query specified through **fields. If no document is found, a new one will be created.
Along with returning the Model instance, a boolean value will also be returned to indicate whether or not the document was created.
Parameters: |
|
---|---|
Returns: | tuple – the Model and whether the document was created. |
Raises : |
Perform an atomic increment.
This can be used to update a single field:
>>> obj.increment(field, value)
or to update multiple fields at a time:
>>> obj.increment(field1=value1, field2=value2)
Note that the latter does not set the values of the fields, but rather specifies the values they should be incremented by.
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: |
|
---|---|
Raises : | TypeError, ValueError |
Perform an atomic pop.
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: |
|
---|---|
Raises : | TypeError |
New in version 0.5.0.
Perform an atomic pull.
With MongoDB there are two types of pull operations: $pull and $pullAll. As the name implies, $pullAll is intended to pull all values in a list from the field, while $pull is meant for single values.
This method will determine the correct operator(s) to use based on the value(s) being pulled. Updates can consist of either operator alone or both together.
This can be used to update a single field:
>>> obj.pull(field, value)
or to update multiple fields at a time:
>>> obj.pull(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: |
|
---|---|
Raises : | TypeError, ValueError |
New in version 0.5.0.
Perform an atomic push.
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: |
|
---|---|
Raises : | TypeError, ValueError |
New in version 0.5.0.
Perform an update using a raw document.
This method should be used carefully as it will perform the update exactly, potentially performing a full document replacement.
Also, for simple updates, it is preferred to use the save() or update() methods as they will usually result in less data being transferred back from the database.
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.
Unlike save(), modified will not be updated.
Parameters: |
|
---|---|
Raises : | TypeError |
Remove the specified fields from the document.
The specified fields will be removed from the document in the database as well as the object. This operation cannot be undone.
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.
Unlike save(), modified will not be updated.
If the model has the required_fields options set, a TypeError will be raised if attempting to remove one of the required fields.
Parameters: |
|
---|---|
Raises : | TypeError |
Perform an atomic rename.
This can be used to update a single field:
>>> obj.rename(original, new)
or to update multiple fields at a time:
>>> obj.increment(original1=new1, original2=new2)
Note that the latter does not set the values of the fields, but rather specifies the name they should be renamed to.
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_from and field_to or through **fields, a ValueError will be raised.
Parameters: |
|
---|---|
Raises : | TypeError, ValueError |
New in version 0.5.0.
Save the document to the database.
When saving a new document for a model with auto_timestamp set to True, created will be added with the current datetime in UTC. modified will always be set with the current datetime in UTC.
If the model has the required_fields options set, a TypeError will be raised if any of the fields have not been associated with the instance.
Parameters: |
|
---|---|
Raises : | TypeError |
Changed in version 0.4.0: created is always added to inserted documents when auto_timestamp is True
Save the specified fields.
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.
Unlike save(), modified will not be updated.
Parameters: |
|
---|---|
Raises : | AttributeError, TypeError |
Perform an atomic update.
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.
Unlike save(), modified will not be updated.
Parameters: |
|
---|---|
Raises : | TypeError |
Helper functions to ease geospatial queries
Build a $box query.
This is a convenience function for $within queries that use $box as their shape.
lower_left_point and upper_right_point are a pair of coordinates, each as a list, that combine to define the bounds of the box in which to search.
Parameters: |
|
---|---|
Returns: | dict – the $box query. |
Raises : | TypeError, ValueError. |
Build a $circle query.
This is a convenience function for $within queries that use $circle as their shape.
Parameters: |
|
---|---|
Returns: | dict – the $circle query. |
Raises : | TypeError, ValueError. |
Build a $near query.
This is a convenience function 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 function 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: |
|
---|---|
Returns: | dict – the $near query. |
Raises : | TypeError, ValueError. |
Build a $polygon query.
This is a convenience function for $within queries that use $polygon as their shape.
points should either be expressed as a series of list‘s or a single dict containing dict‘s providing pairs of coordinates that behind the polygon.
Parameters: | *points (*args.) – The bounds of the polygon. |
---|---|
Returns: | dict – the $polygon query. |
Raises : | TypeError, ValueError. |
Build a $within query.
This is a convenience function for $within queries.
Parameters: |
|
---|---|
Returns: | dict – the $within query. |
Raises : | RuntimeError. |
Query functionality
Wrapper around logical ANDs and ORs.
The Q class serves as a wrapper around query conditions to allow for logical ANDs and ORs through & and |, respectively.
Wrapper around MongoDB cursors.
The QuerySet class wraps around Cursor. When given a Model class, it will return documents wrapped in an instances of the class. Otherwise documents will be returned as dict.
Return the number of documents in the QuerySet.
If no cursor has been associated with the query set, TypeError will be raised.
Returns: | int – the number of documents. |
---|---|
Raises : | TypeError. |
Return distinct values for key in the QuerySet.
Parameters: | key (str.) – Name of the key. |
---|---|
Returns: | list – distinct values for the key. |
Apply a limit to the documents in the QuerySet.
Parameters: | limit (int.) – Number of documents to return. |
---|---|
Returns: | QuerySet – the documents with the limit applied. |
Skip a number of documents in the QuerySet.
Parameters: | skip (int.) – Number of documents to skip. |
---|---|
Returns: | QuerySet – the documents remaining. |
Sort the documents in the QuerySet.
By default all sorting is done in ascending order. To switch any key to sort in descending order, place a - before the name of the key.
>>> qs.sort('id')
>>> qs.sort('grade', '-score')
Parameters: | *fields (*args.) – Names of the fields to sort by. |
---|---|
Returns: | QuerySet – the sorted documents. |
Changed in version 0.3.0: Sorting doesn’t occur until documents are loaded
Helper utilities
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.
Get the current datetime in UTC formatted for MongoDB.
Python includes microseconds in its datetime values. MongoDB, on the other hand, only retains them down to milliseconds. This function will not only get the current time in UTC, but it will also remove microseconds from the value.
Returns: | datetime – the current datetime formatted for MongoDB. |
---|
New in version 0.2.0.
Get a value for a nested dictionary key.
This function can be used to retrieve the value nested within a dictionary. The entire path should be provided as the value for key, using a . as the delimiter (e.g., 'path.to.the.key‘).
If key does not exist in values, KeyError will be raised. The exception will be raised in the reverse order of the recursion so that the original value is used.
Parameters: |
|
---|---|
Returns: | The value associated with the nested key. |
Raises : | KeyError |
Convert a value into an Object ID.
This function 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.
Any value of None will be replaced with a newly generated ObjectId.
Parameters: | value – the ID. |
---|---|
Returns: | ObjectId or dict – the Object ID. |
Raises : | TypeError, InvalidId |
Context manager to ignore specifed exceptions
Check for atomic update operators.
This function 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.
Parameters: | document (dict.) – The document to containing the update. |
---|---|
Returns: | bool – True if document is an atomic update. |
New in version 0.3.0.
Map attribute names to document keys.
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:
The following aggregation operators are also supported:
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: |
|
---|---|
Returns: | dict – key/value pairs renamed based on cls‘s field_map mapping. |
Changed in version 0.7.0: $group operators are supported All lowercase operators are supported
Parse embedded documents from dictionary keys.
This takes a kwargs dictionary whose keys contain __ and convert them to a new dictionary with new keys created by splitting the originals on the __.
Parameters: | **kwargs (**kwargs.) – Keyword arguments to parse. |
---|---|
Returns: | dict – dictionary with nested keys generated from the names of the arguments. |
Remove keys within a nested dictionary.
This function can remove a key from within a nested dictionary. Nested keys should be specified using a . as the delimiter. If no delimiter is found, the key will be removed from the root dictionary.
If original is not a dictionary, a TypeError will be raised. If key doesn’t exist in original, a KeyError will be raised.
Parameters: |
|
---|---|
Returns: | dict – the updated dictionary |
Raises : | TypeError, KeyError |
Set the w parameter for write concern.
If force_write_concern is a value greater than zero, write concern will be used.
Parameters: |
|
---|
New in version 0.6.0.
Update keys within nested dictionaries.
This function simulates merging two dictionaries. It allows specific keys within a dictionary or nested dictionary without overwriting the the entire dictionary.
If either original or updates is not a dictionary, a TypeError will be raised.
Parameters: |
|
---|---|
Returns: | dict – the updated dictionary. |
Raises : | TypeError |