docs update merge

Author: qwiglydee

rest_framework_mongoengine/fields.py

@@ -82,15 +82,6 @@ def run_validators(self, value):
         super(DocumentField, self).run_validators(value)
 
 
-class AttributedDocumentField(DocumentField):
-    """ DocumentField that gets attribute value in ``to_representation``.
-
-    Used internally.
-    """
-    def get_attribute(self, instance):
-        return serializers.Field.get_attribute(self, instance)
-
-
 class GenericEmbeddedField(serializers.Field):
     """ Field for generic embedded documents.
 
@@ -132,9 +123,11 @@ class GenericField(serializers.Field):
 
     Recursively traverses lists and dicts.
     Primitive values are serialized using ``django.utils.encoding.smart_text`` (keeping json-safe intact).
-    Embedded documents handled using GenericEmbeddedField.
+    Embedded documents handled using temporary GenericEmbeddedField.
+
+    No validation performed.
 
-    TODO: catch objectids and dbrefs.
+    Note: it will not work properly if a value contains some complex elements.
     """
     embedded_doc_field = GenericEmbeddedField
 
@@ -170,6 +163,11 @@ def parse_data(self, data):
             return data
 
 
+class AttributedDocumentField(DocumentField):
+    def get_attribute(self, instance):
+        return serializers.Field.get_attribute(self, instance)
+
+
 class GenericEmbeddedDocumentField(GenericEmbeddedField, AttributedDocumentField):
     """ Field for GenericEmbeddedDocumentField.
 
@@ -189,9 +187,13 @@ class DynamicField(GenericField, AttributedDocumentField):
 class ReferenceField(serializers.Field):
     """ Field for References.
 
+    Should be specified with ``model`` or ``queryset`` argument pointing to referenced model.
+
     Internal value: DBRef.
 
-    Representation: ``str(id)``, or  ``{ _id: str(id) }``.
+    Representation: ``str(id)``, or ``{ _id: str(id) }`` (for compatibility with GenericReference).
+
+    Validation checks existance of referenced object.
     """
     default_error_messages = {
         'invalid_input': _('Invalid input. Expected `str` or `{ _id: str }`.'),
@@ -203,11 +205,13 @@ class ReferenceField(serializers.Field):
     pk_field_class = ObjectIdField
     """ Serializer field class used to handle object ids. Override it in derived class if you have other type of ids."""
 
-    def __init__(self, model=None, **kwargs):
+    def __init__(self, model=None, queryset=None, **kwargs):
         if model is not None:
             self.queryset = model.objects
+        elif queryset is not None:
+            self.queryset = queryset
         else:
-            self.queryset = kwargs.pop('queryset', self.queryset)
+            self.queryset = None
 
         self.pk_field = self.pk_field_class()
 
@@ -284,17 +288,19 @@ class GenericReferenceField(serializers.Field):
     Internal value: Document, retrieved with only id field. The mongengine does not support DBRef here.
 
     Representation: ``{ _cls: str, _id: str }``.
+
+    Validation checks existance of given class and existance of referenced model.
     """
 
     pk_field_class = ObjectIdField
-    """ Serializer field class used to handle object ids """
+    """ Serializer field class used to handle object ids. Override it in derived class if you have other type of ids."""
 
     default_error_messages = {
         'not_a_dict': serializers.DictField.default_error_messages['not_a_dict'],
         'missing_items': _('Expected a dict with `_cls` and `_id` items.'),
         'invalid_id': _('Cannot parse "{pk_value}" as {pk_type}.'),
         'undefined_model': _('Document `{doc_cls}` has not been defined.'),
-        'unmapped_colection': _('Cannot find Document for collection "{collection}".'),
+        'undefined_collecion': _('No document defined for collection `{collection}`.'),
         'not_found': _('Document with id={pk_value} does not exist.'),
     }
 
@@ -315,7 +321,7 @@ def to_internal_value(self, value):
             doc_name = value['_cls']
             doc_id = value['_id']
         except KeyError:
-            self.fail('missing_class')
+            self.fail('missing_items')
         try:
             doc_cls = get_document(doc_name)
         except NotRegistered:
@@ -342,7 +348,7 @@ def to_representation(self, value):
             doc_collection = value.collection
             class_match = [ k for k,v in _document_registry.items() if v._get_collection_name() == doc_collection ]
             if len(class_match) != 1:
-                self.fail('undefined_model', collection=doc_collection)
+                self.fail('unmapped_collection', collection=doc_collection)
             doc_cls = class_match[0]
         return { '_cls': doc_cls, '_id': self.pk_field.to_representation(doc_id) }
 
@@ -363,6 +369,8 @@ class GeoPointField(MongoValidatingField, serializers.Field):
     """ Field for 2D point values.
 
     Internal value and representation: ``[ x, y ]``
+
+    Validation is delegated to mongoengine field.
     """
     default_error_messages = {
         'not_a_list': _("Points must be a list of coordinates, instead got {input_value}."),
@@ -389,11 +397,13 @@ def to_representation(self, value):
 class GeoJSONField(MongoValidatingField, serializers.Field):
     """ Field for GeoJSON values.
 
+    Shouldbe specified with argument ``geo_type`` referencing to GeoJSON geometry type ('Point', 'LineSting', etc)
+
     Internal value: ``[ coordinates ]`` (as required by mongoengine fields).
 
     Representation: ``{ 'type': str, 'coordinates': [ coords ] }`` (GeoJSON geometry format).
 
-    Validation: delegated to mongoengine.
+    Validation: delegated to corresponding mongoengine field.
     """
 
     default_error_messages = {
@@ -409,7 +419,7 @@ class GeoJSONField(MongoValidatingField, serializers.Field):
         'MultiPolygon': me_fields.MultiPolygonField
     }
 
-    def __init__(self, geo_type=None, *args, **kwargs):
+    def __init__(self, geo_type, *args, **kwargs):
         assert geo_type in self.valid_geo_types
         self.mongo_field = self.valid_geo_types[geo_type]
         super(GeoJSONField, self).__init__(*args, **kwargs)

rest_framework_mongoengine/generics.py

@@ -1,9 +1,3 @@
-"""
-Adaptation of DRF generics.
-
-You should use them instead of original DRF classes.
-"""
-
 from rest_framework import mixins
 from rest_framework import generics as drf_generics
 

rest_framework_mongoengine/routers.py

@@ -1,9 +1,3 @@
-"""
-Adaptaion of DRF routers.
-
-You should use them instead of original DRF classes.
-"""
-
 from rest_framework import routers as drf_routers
 
 

rest_framework_mongoengine/serializers.py

@@ -95,29 +95,27 @@ def raise_errors_on_nested_writes(method_name, serializer, validated_data):
 class DocumentSerializer(serializers.ModelSerializer):
     """ Serializer for Documents.
 
-    Replacement of DRF ModelSerializer, with almost the same API and features.
-
-    Regocnized primitve fields:
-
-        ``StringField``
-        ``URLField``
-        ``EmailField``
-        ``IntField``
-        ``LongField``
-        ``FloatField``
-        ``DecimalField``
-        ``BooleanField``
-        ``DateTimeField``
-        ``ComplexDateTimeField``
-        ``ObjectIdField``
-        ``SequenceField`` (assumes it has integer counter)
-        ``UUIDField``
-        ``GeoPointField``
-        ``GeoJsonBaseField`` (all those fields)
-
-    Compound fields: ``ListField`` and ``DictField`` mapped to corresponding DRF fields, with respect to nested field specification.
-
-    The ``ReferenceField`` is handled like ``ForeignKey`` in DRF: there nestted serializer autogenerated if serializer depth greater then 0, otherwise it's handled by it's own (results as ``str(id)``.
+    Recognized primitve fields:
+
+        * ``StringField``
+        * ``URLField``
+        * ``EmailField``
+        * ``IntField``
+        * ``LongField``
+        * ``FloatField``
+        * ``DecimalField``
+        * ``BooleanField``
+        * ``DateTimeField``
+        * ``ComplexDateTimeField``
+        * ``ObjectIdField``
+        * ``SequenceField`` (assumes it has integer counter)
+        * ``UUIDField``
+        * ``GeoPointField``
+        * ``GeoJsonBaseField`` (all those fields)
+
+    Compound fields: ``ListField`` and ``DictField`` are mapped to corresponding DRF fields, with respect to nested field specification.
+
+    The ``ReferenceField`` is handled like ``ForeignKey`` in DRF: there nested serializer autogenerated if serializer depth greater then 0, otherwise it's handled by it's own (results as ``str(id)``).
 
     For ``EmbeddedDocumentField`` also nested serializer autogenerated for non-zero depth, otherwise it is skipped. TODO: THIS IS PROBABLY WRONG AND SHOULD BE FIXED.
 
@@ -488,7 +486,10 @@ def __repr__(self):
 
 
 class EmbeddedDocumentSerializer(DocumentSerializer):
-    """ Serializer for EmbeddedDocuments. """
+    """ Serializer for EmbeddedDocuments.
+
+    Skips id field and uniqueness validation.
+    """
 
     def get_default_field_names(self, declared_fields, model_info):
         # skip id field
@@ -512,7 +513,7 @@ def to_internal_value(self, data):
 class DynamicDocumentSerializer(DocumentSerializer):
     """ Serializer for DynamicDocuments.
 
-    Maps all undefined fields to ``DynamicField``.
+    Maps all undefined fields to :class:`fields.DynamicField`.
     """
     def to_representation(self, instance):
         ret = super(DynamicDocumentSerializer,self).to_representation(instance)

rest_framework_mongoengine/validators.py

@@ -17,7 +17,7 @@ def exclude_current_instance(self, queryset):
 class UniqueValidator(MongoValidatorMixin, validators.UniqueValidator):
     """ Replacement of DRF UniqueValidator.
 
-    Used by ``DocumentSerializer`` for fields, present in unique indexes.
+    Used by :class:`DocumentSerializer` for fields, present in unique indexes.
     """
     def __call__(self, value):
         queryset = self.queryset
@@ -36,7 +36,7 @@ def __repr__(self):
 class UniqueTogetherValidator(MongoValidatorMixin, validators.UniqueTogetherValidator):
     """ Replacement of DRF UniqueTogetherValidator.
 
-    Used by ``DocumentSerializer`` for fields, present in unique indexes.
+    Used by :class:`DocumentSerializer` for fields, present in unique indexes.
     """
     def __call__(self, attrs):
         self.enforce_required_fields(attrs)

rest_framework_mongoengine/viewsets.py

@@ -1,9 +1,3 @@
-"""
-Adaptation of DRF viewsets.
-
-You should use them instead of original DRF classes.
-"""
-
 from rest_framework import mixins
 from rest_framework.viewsets import ViewSetMixin
 from rest_framework_mongoengine.generics import GenericAPIView