Simon API

The following is a look into the API inside Simon.

Connection

Manage database connections

simon.connection.connect(host='localhost', name=None, username=None, password=None, port=None, alias=None, **kwargs)

Connect to a database.

Parameters:

• host (str.) – Hostname, IP address, or MongoDB URI of the host.
• name – (optional) The name of the MongoDB database.
• username (str.) – (optional) The username to use for authentication.
• password (str.) – (optional) The password to use for authentication.
• port (int.) – (optional) The port of the MongoDB host.
• alias (str.) – (optional) An alias to use for accessing the database. If no value is provided, name will be used.
• **kwargs (**kwargs.) – All other keyword arguments accepted by pymongo.connection.Connection.

Returns:

pymongo.database.Database – the database.

Raises :

ConnectionError

Changed in version 0.2.0: connect() now accepts replica_set as a kwarg, it is preferred over replicaSet

simon.connection.get_database(name)

Return a reference to a database.

Parameters:name (str.) – The name of the database. Returns:pymongo.database.Database – a database object.

exception simon.connection.ConnectionError

Raised when a database connection cannot be opened.

Model

class simon.Model(**fields)

Base class for all Simon models.

exception MultipleDocumentsFound

Raised when more than one document is found.

exception Model.NoDocumentFound

Raised when an object matching a query is not found.

classmethod Model.all()

Return all documents in the collection.

If sort has been defined on the Meta class it will be used to order the records.

classmethod Model.create(**fields)

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:

• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.
• **fields (**kwargs.) – Keyword arguments to add to the document.

Returns:

Model – the new document.

Raises :

TypeError

Model.delete(**kwargs)

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:

• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.

Raises :

TypeError

classmethod Model.find(q=None, *qs, **fields)

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:

• q (Q.) – (optional) A logical query to use with the query.
• *qs (*args.) – DEPRECATED Use q instead.
• **fields (**kwargs.) – Keyword arguments specifying the query.

Returns:

QuerySet – query set containing objects matching query.

Changed in version 0.3.0: qs is being deprecated in favor of q

classmethod Model.get(q=None, *qs, **fields)

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:

• q (Q.) – (optional) A logical query to use with the query.
• *qs (*args.) – DEPRECATED Use q instead.
• **fields (**kwargs.) – Keyword arguments specifying the query.

Returns:

Model – object matching query.

Raises :

MultipleDocumentsFound, NoDocumentFound

Changed in version 0.3.0: qs is being deprecated in favor of q

classmethod Model.get_or_create(**fields)

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:

• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.
• **fields (**kwargs.) – Keyword arguments specifying the query.

Returns:

tuple – the Model and whether the document was created.

Raises :

MultipleDocumentsFound

Model.increment(field=None, value=1, **fields)

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:

• field (str.) – (optional) Name of the field to increment.
• value (int.) – (optional) Value to increment field by.
• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.
• **fields (**kwargs.) – Keyword arguments specifying fields and increment values.

Raises :

TypeError, ValueError

Model.pop(fields, **kwargs)

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:

• 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.

Raises :

TypeError

New in version 0.5.0.

Model.pull(field=None, value=None, **fields)

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:

• field (str.) – (optional) Name of the field to pull from.
• value (scalar or list.) – (optional) Value to pull from field.
• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.
• **fields (**kwargs.) – Keyword arguments specifying fields and the values to pull.

Raises :

TypeError, ValueError

New in version 0.5.0.

Model.push(field=None, value=None, allow_duplicates=True, **fields)

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:

• 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.
• **fields (**kwargs.) – Keyword arguments specifying fields and the values to push.

Raises :

TypeError, ValueError

New in version 0.5.0.

Model.raw_update(fields, **kwargs)

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:

• fields (dict.) – The document to save to the database.
• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.

Raises :

TypeError

Model.remove_fields(fields, **kwargs)

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:

• fields (str, list, or tuple.) – The names of the fields to remove.
• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.

Raises :

TypeError

Model.rename(field_from=None, field_to=None, **fields)

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:

• field_from (str.) – (optional) Name of the field to rename.
• field_to (int.) – (optional) New name for field_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.
• **fields (**kwargs.) – Keyword arguments specifying fields and their new names.

Raises :

TypeError, ValueError

New in version 0.5.0.

Model.save(**kwargs)

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:

• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.

Raises :

TypeError

Changed in version 0.4.0: created is always added to inserted documents when auto_timestamp is True

Model.save_fields(fields, **kwargs)

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:

• fields (str, list, or tuple.) – The names of the fields to update.
• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.

Raises :

AttributeError, TypeError

Model.update(**fields)

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:

• safe (bool.) – (optional) DEPRECATED Use w instead.
• w (int.) – (optional) The number of servers that must receive the update for it to be successful.
• **fields (**kwargs.) – The fields to update.

Raises :

TypeError

Geo

Helper functions to ease geospatial queries

simon.geo.box(lower_left_point, upper_right_point)

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:

• lower_left_point (list.) – The lower-left bound of the box.
• upper_right_point (list.) – The upper-right bound of the box.

Returns:

dict – the $box query.

Raises :

TypeError, ValueError.

simon.geo.circle(point, radius)

Build a $circle query.

This is a convenience function for $within queries that use $circle as their shape.

Parameters:

• point (list.) – The center of the circle.
• radius (int.) – The distance from the center of the circle.

Returns:

dict – the $circle query.

Raises :

TypeError, ValueError.

simon.geo.near(point, max_distance=None, unique_docs=False)

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:

• 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.
• unique_docs – (optional) If True will only return unique documents.

Returns:

dict – the $near query.

Raises :

TypeError, ValueError.

simon.geo.polygon(*points)

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.

simon.geo.within(shape, *bounds, **bounds_map)

Build a $within query.

This is a convenience function for $within queries.

Parameters:

• shape (str.) – The shape of the bounding area.
• *bounds (*args.) – Coordinate pairs defining the bounding area.
• **bounds_map (**kwargs.) – Named coordinate pairs defining the bounding area.

Returns:

dict – the $within query.

Raises :

RuntimeError.

Query

Query functionality

class simon.query.Q(**fields)

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.

class simon.query.QuerySet(cursor=None, cls=None)

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.

count()

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.

distinct(key)

Return distinct values for key in the QuerySet.

Parameters:key (str.) – Name of the key. Returns:list – distinct values for the key.

limit(limit)

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(skip)

Skip a number of documents in the QuerySet.

Parameters:skip (int.) – Number of documents to skip. Returns:QuerySet – the documents remaining.

sort(*fields)

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

Utils

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.

simon.utils.current_datetime()

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.

simon.utils.get_nested_key(values, key)

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:

• values (dict.) – The dictionary.
• key’ – The path of the nested key.

Returns:

The value associated with the nested key.

Raises :

KeyError

simon.utils.guarantee_object_id(value)

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

simon.utils.ignored(*args, **kwds)

Context manager to ignore specifed exceptions

with ignored(OSError):

os.remove(somefile)

simon.utils.is_atomic(document)

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.

simon.utils.map_fields(field_map, fields, with_operators=False, flatten_keys=False)

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:

• $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

The following aggregation operators are also supported:

• $addToSet returns an unique array of all values found in the selected field
• $push returns an array of all values found in the selected field
• $first returns the first value encountered for its group
• $last returns the last value encountered for its group
• $max returns the hightest value for the field
• $min returns the lowest non-null value for the field
• $avg returns the average value for the field
• $sum returns the sum of values for the field

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.

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

simon.utils.parse_kwargs(**kwargs)

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.

simon.utils.remove_nested_key(original, key)

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:

• original (dict.) – The original dictionary to be updated.
• key (str.) – The key to be removed.

Returns:

dict – the updated dictionary

Raises :

TypeError, KeyError

simon.utils.set_write_concern(options, force_write_concern)

Set the w parameter for write concern.

If force_write_concern is a value greater than zero, write concern will be used.

Parameters:

• options (dict.) – The potential write concern settings.
• force_write_concern (int.) – A value to override options with.

New in version 0.6.0.

simon.utils.update_nested_keys(original, updates)

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:

• original (dict.) – The original dictionary to be updated.
• updates (dict.) – The dictionary with updates to apply.

Returns:

dict – the updated dictionary.

Raises :

TypeError