Data Structure

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

{                           # parent document
    '_id' : ...,
                            # no container dictionary or list
    'venue' : {
        ...                 # subdocument with key 'venue'

This data structure can be accessed as:

class Venue( mongo_objects.MongoSingleProxy ):
    container_name = 'venue'

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

The same MongoSingleProxy proxy definition may be used as a subdocument in multiple document collections, for example, an Address subdocument used in the Customer, Vendor and Employee collections.

Proxy Keys

Assigning Key on Create

The subdocument proxy key is the actual dictionary key used to identify the subdocument in the parent dictionary. Since there is no separate container, this is usually the parent document itself.

The key is defined in the class as container_name. To keep the parallel with MongoDictProxy and MongoListProxy, MongoSingleProxy.get_proxy() accepts a key argument when initializing a new proxy object but it is ignored.

Subdocument IDs

Since the proxy key is an actual dictionary key in our document schema, it is not necessarily safe to share with users in a URL, for example. To protect against data schema leakage, the id() and proxy_id() methods always use "0" when constructing subdocument IDs for MongoSingleProxy instances.

Since the container_name is provided in the class definition, load_proxy_by_id() can create these proxies without problem.

class Event( mongo_objects.MongoUserDict ):

    def load_venue_by_id( cls, venueId ):
        return cls.load_proxy_by_id( venueId, Venue )


Since MongoSingleProxy by definition is a single subdocument, the get_proxies() method is not supported and raises an Exception.

Class Reference

class mongo_objects.MongoSingleProxy(parent, key=None)

Implement proxy object for a single subdocument dictionary

classmethod get_proxy(parent, key=None)

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

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

  • key (str) – ignored; the key is provided by cls.container_name


proxy object

Return type:

MongoSingleProxy subclass

__init__(parent, key=None)

Instantiate a new single proxy object from the parent dictionary.

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

  • key – This parameter is kept for the parallel with the other proxy object but is ignored. The actual key comes from container_name.


MongoObjectsNonexistentKey – if the container_name key does not already exist in the parent dictionary


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

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

Add a new single subdocument dictionary to the parent object. No new key is auto-assigned as single subdocuments are assigned to fixed keys based on the class container_name

  • 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


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.

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


a unique string suitable for use as a MongoDB dictionary key


Convenience method to behave similar to UserDict.


The subdocument dictionary proxied from the parent document

Return type:



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.


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

classmethod exists(parent, key=None)

Return True if the key already exists in the parent document

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

  • key – ignored; the actual key comes from container_name

get(key, default=None)

Get a value from the subdocument dictionary

classmethod get_proxies(parent)

get_proxies() doesn’t make sense for single proxy use.


Exception – always


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.


Return the items in the subdocument dictionary


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.

To avoid disclosing actual key names in URLs, the ID for single proxy objects is forced to "0".


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


One or more proxy IDs separated by subdoc_key_sep

Return type:



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 the subdocument dictionary with new values


Return the values in the subdocument dictionary

Polymorphic Class Reference

Polymorphic proxies are supported by PolymorphicMongoSingleProxy. All the attributes and methods of MongoSingleProxy are supported with the following overrides.

class mongo_objects.PolymorphicMongoSingleProxy(parent, key=None)

Polymorphic version of MongoSingleProxy

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

Add the proxy_subclass_key before passing all arguments to the base class create()

AccessSingleProxy needs to be first in the object inheritance to get super() to work properly

classmethod get_proxy(parent, key=None)

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

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

  • key (str) – ignored; the key is provided by cls.container_name


proxy object

Return type:

PolymorphicMongoSingleProxy subclass


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