MongoListProxy¶
Data Structure¶
A MongoListProxy
manages a list of subdocuments
as shown in the following structure. See Proxy Overview for a list of all
supported data structures.
{ # parent document
'_id' : ...,
'tickets' : [ # container is a list
{
'_sdkey' : '1', # subdocument with key '1'
...
},
{
'_sdkey' : '2', # subdocument with key '2'
...
},
{
'_sdkey' : '3', # subdocument with key '3'
...
},
],
}
This data structure can be accessed as:
class Tickets( mongo_objects.MongoListProxy ):
container_name = 'tickets'
class Events( mongo_objects.MongoUserDict ):
collection_name = 'events'
database = ... pymongo database connection object ...
Proxy Keys¶
Assigning Keys on Create¶
Python lists don’t natively use keys to access content, so the subdocument proxy key is added to each subdocument dictionary under the key _sdkey.
We recommend using the built-in system of auto-assigning unique integers as proxy keys to avoid changing keys and invalidating existing documents or URLs.
Locating Subdocuments¶
It is too slow to iterate through the list of subdocuments on every
access to find the correct key. MongoListProxy
makes the
following look-up optimization.
Each proxy object stores both the key and a sequence number representing the list index that held that key during the most recent data access.
When accessing the proxy object, the subdocument at the currently saved sequence number is examined. If the key matches the key for the proxy object, that subdocument is immediately returned.
Otherwise, the list is rescanned from the front until a subdocument is located with the correct proxy key. Once the key is located, the sequence number is stored as a hint for next time and the subdocument at the sequence location is returned.
Initializing Objects¶
__init__()
accepts three arguments, parent, key and seq. parent
is required. At least one of key and seq must also be provided.
- # If only key is provided, the key is saved in the object. No validation is
performed. The first time the proxy is accessed, the list will be scanned for the correct subdocument.
- # If only seq is provided, the key for the subdocument currently at that location
in the list is saved as the proxy key. The seq value is saved as a hint for the next access. If the list changes, the proxy key will be located again and the sequence number updated.
- # If both key and seq are provided, the key is saved in the proxy object but
not validated. The sequence number is saved as a hint for the next access and will be validated at that time.
Class Reference¶
- class mongo_objects.MongoListProxy(parent, key=None, seq=None)¶
Implement proxy object using a list as a container
- classmethod get_proxies(parent)¶
Return all proxy objects in the container_name list container.
- Parameters:
parent (MongoUserDict or proxy object) – parent document or subdocument
- Returns:
list of proxy objects
- Return type:
MongoListProxy
subclasses
- classmethod get_proxy(parent, key=None, seq=None)¶
Return a single proxy object passing the arguments through to calling
__init__()
At least one of key and seq must be provided. See
__init__()
method for how these arguments are handled.- 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:
MongoListProxy
subclass
- __init__(parent, key=None, seq=None)¶
Instantiate a new proxy object from a list container.
At least one of key and seq must be provided.
If only key is provided, the key is saved in the object. No validation is performed. The first time the proxy is accessed, the list will be scanned for the correct subdocument.
If only seq is provided, the key for the subdocument currently at that location in the list is saved as the proxy key. The seq value is saved as a hint for the next access. If the list changes, the proxy key will be located again and the sequence number updated.
If both key and seq are provided, the key is saved in the proxy object but not validated. The sequence number is saved as a hint for the next access and will be validated at that time.
- Parameters:
parent (MongoUserDict or proxy object) – parent document or subdocument
key (int, optional) – unique key identifying an existing member of the list container
seq – index into the list container
- Raises:
MongoObjectsNonexistentKey – if key does not already exist in the list container
- container_name¶
Users must override this to provide the name of the dictionary or list container
- classmethod create(parent, subdoc=None, autosave=None)¶
Add a new subdocument to the list 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, None) – should the parent document be saved after this new content is added. None uses the ultimate parent class autosave_default value.
- 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=None)¶
Delete the subdocument from the container list. Remove the key and sequence 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, None) – should the parent document be saved after the proxy content is deleted. None uses the ultimate parent class autosave_default value.
- classmethod exists(parent, key)¶
Return True if the key already exists in the list 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 withMongoUserDict
.
- 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(*args, **kwargs)¶
Update the subdocument dictionary with new values
- values()¶
Return the values in the subdocument dictionary
Polymorphic Class Reference¶
Polymorphic proxies are supported by PolymorphicMongoListProxy
. All the
attributes and methods of MongoListProxy
are supported with the following
overrides.
- class mongo_objects.PolymorphicMongoListProxy(parent, key=None, seq=None)¶
Polymorphic version of MongoListProxy
- classmethod get_proxies(parent)¶
Return all proxy objects in the container_name list container with the correct polymorphic subclasses.
- Parameters:
parent (MongoUserDict or proxy object) – parent document or subdocument
- Returns:
list of proxy objects
- Return type:
MongoListProxy
subclasses
- classmethod get_proxy(parent, key=None, seq=None)¶
Return a single list proxy object. Determine the correct subclass type and pass the arguments to
__init__()
At least one of key and seq must be provided. See
__init__()
method for how these arguments are handled.- Parameters:
parent (MongoUserDict or proxy object) – parent document or subdocument
key (str, optional) – the key identifying this subdocument
seq (int, optional) – the current index in the list container of the subdocument
- Returns:
proxy object
- Return type:
PolymorphicMongoListProxy
subclass- Raises:
MongoObjectsPolymorphicMismatch – if the resulting object is not of type cls or a subclass of cls