MongoDictProxy

Data Structure

A MongoDictProxy manages a dictionary of subdocuments as shown in the following structure. See Proxy Overview for a list of all supported data structures.

{                           # parent document
    '_id' : ...,
    'ticketTypes' : {       # container is a dictionary
        '1' : {
            ...             # subdocument with key '1'
            },
        '2' : {
            ...             # subdocument with key '2'
            },
        '3' : {
            ...             # subdocument with key '3'
            },
    },
}

This data structure can be accessed as:

class TicketTypes( mongo_objects.MongoDictProxy ):
    container_name = 'ticket_types'

class Events( mongo_objects.MongoUserDict ):
    collection_name = 'events'
    database = ... pymongo database connection object ...

Proxy Keys

Assigning Keys on Create

The subdocument proxy key is the actual dictionary key used to identify the subdocument in the containing dictionary.

We recommend using the built-in system of auto-assigning unique integers as proxy keys. While it is tempting to generate the key from something in the content of the subdocument, this means changing keys when the subdocument changes. Changing keys invalidates already existing proxy objects as well as any subdocument IDs already published as URLs.

Validating Keys

Proxy keys must already exist when creating objects by constructor or by get_proxy(). To create a new object and assign a new key, use create().

freds_ticket = Ticket( event, '1' )
sallys_ticket = Ticket.get_proxy( event, '2' )

Class Reference

class mongo_objects.MongoDictProxy(parent, key)

Implement proxy object using a dictionary as a container

classmethod get_proxies(parent)

Return all proxy objects in the container_name dictionary container.

Parameters:

parent (MongoUserDict or proxy object) – parent document or subdocument

Returns:

list of proxy objects

Return type:

MongoDictProxy subclasses

classmethod get_proxy(parent, key)

Return a single proxy object passing the arguments through to calling __init__()

Parameters:

  • parent (MongoUserDict or proxy object) – parent document or subdocument

  • key (str) – unique key identifying an existing member of the dictionary container

Returns:

proxy object

Return type:

MongoDictProxy subclass

__init__(parent, key)

Instantiate a new proxy object from a dictionary container.

Parameters:

  • parent (MongoUserDict or proxy object) – parent document or subdocument

  • key (str) – unique key identifying an existing member of the dictionary container

Raises:

MongoObjectsNonexistentKey – if key does not already exist in the dictionary container

container_name

Users must override this to provide the name of the dictionary or list container

classmethod create(parent, subdoc=None, autosave=True)

Add a new subdocument to the dictionary container. Auto-assign the ID and return the new proxy object.

Parameters:

  • parent (MongoUserDict or proxy object) – parent document or subdocument

  • subdoc (dict) – new subdocument to be added

  • autosave (bool) – should the parent document be saved after this new content is added

Returns:

a proxy object to the new data

Return type:

MongoDictProxy subclass

classmethod create_key(parent, subdoc)

Create a unique key value for this subdocument. The default implementation requests a hex string for the next unique integer as saved in the MongoUserDict parent object.

Users may override this using data from the subdoc or other methods to generate a unique key. It is recommended that the key not be changed once the object is created as it will invalidate any existing proxies and any subdocument_id strings.

Parameters:

  • parent (MongoUserDict or proxy object) – parent document or subdocument

  • subdoc (dict) – the subdocument for which a new key is being created. The default implementation ignores this parameter but users may find it useful when overriding this method.

Returns:

a unique string suitable for use as a MongoDB dictionary key

data()

Convenience method to behave similar to UserDict.

Returns:

The subdocument dictionary proxied from the parent document

Return type:

dict

delete(autosave=True)

Delete the subdocument from the container dictionary. Remove the key so the proxy can’t be referenced again. By default save the parent document.

Once a proxy object is deleted the underlying dictionary no longer exists so all values disappear immediately.

Parameters:

autosave (bool) – should the parent document be saved after the proxy content is deleted

classmethod exists(parent, key)

Return True if the key already exists in the dictionary container

Parameters:

  • parent (MongoUserDict or proxy object) – parent document or subdocument

  • key (str) – key being queried

get(key, default=None)

Get a value from the subdocument dictionary

id()

Return the full proxy ID including the parent document ID. This is really just a wrapper around proxy_id() but keeps the parallel with MongoUserDict.

items()

Return the items in the subdocument dictionary

keys()

Return the keys in the subdocument dictionary

proxy_id(*args, include_parent_doc_id=False)

Assemble a list of proxy IDs into a single string. Each proxy passes the request up to it’s parent adding each ID (key) along the way.

Parameters:

include_parent_doc_id (bool) – whether to include the parent document ID in the resulting ID string

Returns:

One or more proxy IDs separated by subdoc_key_sep

Return type:

str

save()

Saving the subdocument means saving the parent object, so we simply pass the save request up the line.

setdefault(key, default=None)

Set a default value in the subdocument dictionary

update(values)

Update the subdocument dictionary with new values

values()

Return the values in the subdocument dictionary

Polymorphic Class Reference

Polymorphic proxies are supported by PolymorphicMongoDictProxy. All the attributes and methods of MongoDictProxy are supported with the following overrides.

class mongo_objects.PolymorphicMongoDictProxy(parent, key)

Polymorphic version of MongoDictProxy

classmethod get_proxies(parent)

Return all proxy objects in the container_name dictionary container with the correct polymorphic subclass.

Parameters:

parent (MongoUserDict or proxy object) – parent document or subdocument

Returns:

list of proxy objects

Return type:

PolymorphicMongoDictProxy subclasses

classmethod get_proxy(parent, key)

Return a single dictionary proxy object. Determine the correct subclass type and pass the arguments to __init__()

Parameters:

  • parent (MongoUserDict or proxy object) – parent document or subdocument

  • key (str) – the key identifying this subdocument

Returns:

proxy object

Return type:

PolymorphicMongoDictProxy subclass

Raises:

MongoObjectsPolymorphicMismatch – if the resulting object is not of type cls or a subclass of cls