Updated docs and added a NotRegistered exception

For handling GenericReferences that reference documents that haven't
been imported.

Closes #170

mongoengine/base.py

@@ -7,22 +7,32 @@ import pymongo
 import pymongo.objectid
 
 
-_document_registry = {}
-
-def get_document(name):
-    return _document_registry[name]
+class NotRegistered(Exception):
+    pass
 
 
 class ValidationError(Exception):
     pass
 
 
+_document_registry = {}
+
+def get_document(name):
+    if name not in _document_registry:
+        raise NotRegistered("""
+            `%s` has not been registered in the document registry.
+            Importing the document class automatically registers it, has it
+            been imported?
+        """.strip() % name)
+    return _document_registry[name]
+
+
 class BaseField(object):
     """A base class for fields in a MongoDB document. Instances of this class
     may be added to subclasses of `Document` to define a document's schema.
     """
 
-    # Fields may have _types inserted into indexes by default 
+    # Fields may have _types inserted into indexes by default
     _index_with_types = True
     _geo_index = False
 
@@ -32,7 +42,7 @@ class BaseField(object):
     creation_counter = 0
     auto_creation_counter = -1
 
-    def __init__(self, db_field=None, name=None, required=False, default=None, 
+    def __init__(self, db_field=None, name=None, required=False, default=None,
                  unique=False, unique_with=None, primary_key=False,
                  validation=None, choices=None):
         self.db_field = (db_field or name) if not primary_key else '_id'
@@ -57,7 +67,7 @@ class BaseField(object):
             BaseField.creation_counter += 1
 
     def __get__(self, instance, owner):
-        """Descriptor for retrieving a value from a field in a document. Do 
+        """Descriptor for retrieving a value from a field in a document. Do
         any necessary conversion between Python and MongoDB types.
         """
         if instance is None:
@@ -167,8 +177,8 @@ class DocumentMetaclass(type):
                 superclasses.update(base._superclasses)
 
             if hasattr(base, '_meta'):
-                # Ensure that the Document class may be subclassed - 
-                # inheritance may be disabled to remove dependency on 
+                # Ensure that the Document class may be subclassed -
+                # inheritance may be disabled to remove dependency on
                 # additional fields _cls and _types
                 if base._meta.get('allow_inheritance', True) == False:
                     raise ValueError('Document %s may not be subclassed' %
@@ -211,12 +221,12 @@ class DocumentMetaclass(type):
 
         module = attrs.get('__module__')
 
-        base_excs = tuple(base.DoesNotExist for base in bases 
+        base_excs = tuple(base.DoesNotExist for base in bases
                           if hasattr(base, 'DoesNotExist')) or (DoesNotExist,)
         exc = subclass_exception('DoesNotExist', base_excs, module)
         new_class.add_to_class('DoesNotExist', exc)
 
-        base_excs = tuple(base.MultipleObjectsReturned for base in bases 
+        base_excs = tuple(base.MultipleObjectsReturned for base in bases
                           if hasattr(base, 'MultipleObjectsReturned'))
         base_excs = base_excs or (MultipleObjectsReturned,)
         exc = subclass_exception('MultipleObjectsReturned', base_excs, module)
@@ -238,9 +248,9 @@ class TopLevelDocumentMetaclass(DocumentMetaclass):
 
     def __new__(cls, name, bases, attrs):
         super_new = super(TopLevelDocumentMetaclass, cls).__new__
-        # Classes defined in this package are abstract and should not have 
+        # Classes defined in this package are abstract and should not have
         # their own metadata with DB collection, etc.
-        # __metaclass__ is only set on the class with the __metaclass__ 
+        # __metaclass__ is only set on the class with the __metaclass__
         # attribute (i.e. it is not set on subclasses). This differentiates
         # 'real' documents from the 'Document' class
         if attrs.get('__metaclass__') == TopLevelDocumentMetaclass:
@@ -366,7 +376,7 @@ class BaseDocument(object):
         are present.
         """
         # Get a list of tuples of field names and their current values
-        fields = [(field, getattr(self, name)) 
+        fields = [(field, getattr(self, name))
                   for name, field in self._fields.items()]
 
         # Ensure that each field is matched to a valid value

mongoengine/fields.py

@@ -339,7 +339,7 @@ class ListField(BaseField):
 
         if isinstance(self.field, ReferenceField):
             referenced_type = self.field.document_type
-            # Get value from document instance if available 
+            # Get value from document instance if available
             value_list = instance._data.get(self.name)
             if value_list:
                 deref_list = []
@@ -522,6 +522,9 @@ class GenericReferenceField(BaseField):
     """A reference to *any* :class:`~mongoengine.document.Document` subclass
     that will be automatically dereferenced on access (lazily).
 
+    note:  Any documents used as a generic reference must be registered in the
+    document registry.  Importing the model will automatically register it.
+
     .. versionadded:: 0.3
     """
 
@@ -648,7 +651,7 @@ class GridFSProxy(object):
         if not self.newfile:
             self.new_file()
             self.grid_id = self.newfile._id
-        self.newfile.writelines(lines) 
+        self.newfile.writelines(lines)
 
     def read(self, size=-1):
         try: