feat: Use mongengine field metadata and class docstrings for default field descriptions.

Author: zrlay

graphene_mongo/converter.py

@@ -17,7 +17,7 @@
 
 from .advanced_types import PointFieldType, MultiPolygonFieldType
 from .fields import MongoengineConnectionField
-from .utils import import_single_dispatch
+from .utils import import_single_dispatch, get_field_description
 
 singledispatch = import_single_dispatch()
 
@@ -33,36 +33,36 @@ def convert_mongoengine_field(field, registry=None):
 @convert_mongoengine_field.register(mongoengine.StringField)
 @convert_mongoengine_field.register(mongoengine.URLField)
 def convert_field_to_string(field, registry=None):
-    return String(description=field.db_field, required=field.required)
+    return String(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.UUIDField)
 @convert_mongoengine_field.register(mongoengine.ObjectIdField)
 def convert_field_to_id(field, registry=None):
-    return ID(description=field.db_field, required=field.required)
+    return ID(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.IntField)
 @convert_mongoengine_field.register(mongoengine.LongField)
 def convert_field_to_int(field, registry=None):
-    return Int(description=field.db_field, required=field.required)
+    return Int(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.BooleanField)
 def convert_field_to_boolean(field, registry=None):
-    return Boolean(description=field.db_field, required=field.required)
+    return Boolean(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.DecimalField)
 @convert_mongoengine_field.register(mongoengine.FloatField)
 def convert_field_to_float(field, registry=None):
-    return Float(description=field.db_field, required=field.required)
+    return Float(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.DictField)
 @convert_mongoengine_field.register(mongoengine.MapField)
 def convert_dict_to_jsonstring(field, registry=None):
-    return JSONString(description=field.db_field, required=field.required)
+    return JSONString(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.PointField)
@@ -77,7 +77,7 @@ def convert_multipolygon_to_field(field, register=None):
 
 @convert_mongoengine_field.register(mongoengine.DateTimeField)
 def convert_field_to_datetime(field, registry=None):
-    return DateTime(description=field.db_field, required=field.required)
+    return DateTime(description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.ListField)
@@ -99,7 +99,7 @@ def convert_field_to_list(field, registry=None):
             and not isinstance(field.field, relations):
         base_type = type(base_type)
 
-    return List(base_type, description=field.db_field, required=field.required)
+    return List(base_type, description=get_field_description(field, registry), required=field.required)
 
 
 @convert_mongoengine_field.register(mongoengine.EmbeddedDocumentField)
@@ -111,6 +111,6 @@ def dynamic_type():
         _type = registry.get_type_for_model(model)
         if not _type:
             return None
-        return Field(_type)
+        return Field(_type, description=get_field_description(field, registry))
 
     return Dynamic(dynamic_type)

graphene_mongo/tests/models.py

@@ -13,19 +13,24 @@
 
 
 class Editor(Document):
+    """
+    An Editor of a publication.
+    """
 
     meta = {'collection': 'test_editor'}
     id = StringField(primary_key=True)
-    first_name = StringField(required=True)
-    last_name = StringField(required=True)
-    metadata = MapField(field=StringField())
+    first_name = StringField(required=True, help_text="Editor's first name.", db_field='fname')
+    last_name = StringField(required=True, help_text="Editor's last name.")
+    metadata = MapField(field=StringField(), help_text="Arbitrary metadata.")
 
 
 class Article(Document):
 
     meta = {'collection': 'test_article'}
-    headline = StringField(required=True)
-    pub_date = DateTimeField(default=datetime.now)
+    headline = StringField(required=True, help_text="The article headline.")
+    pub_date = DateTimeField(default=datetime.now,
+                             verbose_name="publication date",
+                             help_text="The date of first press.")
     editor = ReferenceField(Editor)
     reporter = ReferenceField('Reporter')
 
@@ -41,7 +46,7 @@ class EmbeddedArticle(EmbeddedDocument):
 
 class Reporter(Document):
 
-    meta = {'collection': 'test_repoter'}
+    meta = {'collection': 'test_reporter'}
     id = StringField(primary_key=True)
     first_name = StringField(required=True)
     last_name = StringField(required=True)

graphene_mongo/tests/test_converter.py

@@ -221,3 +221,49 @@ class Meta:
     assert isinstance(graphene_field, graphene.List)
     dynamic_field = graphene_field.get_type()
     assert dynamic_field._of_type == P
+
+
+def test_should_description_convert_common_metadata():
+
+    class A(MongoengineObjectType):
+
+        class Meta:
+            model = Article
+
+    headline_field = convert_mongoengine_field(
+        Article._fields['headline'], A._meta.registry
+    )
+    assert headline_field.kwargs['description'] == "The article headline."
+
+    pubDate_field = convert_mongoengine_field(
+        Article._fields['pub_date'], A._meta.registry
+    )
+    assert pubDate_field.kwargs['description'] == "Publication Date\nThe date of first press."
+
+    firstName_field = convert_mongoengine_field(
+        Editor._fields['first_name'], A._meta.registry
+    )
+    assert firstName_field.kwargs['description'] == "Editor's first name.\n(fname)"
+
+    metadata_field = convert_mongoengine_field(
+        Editor._fields['metadata'], A._meta.registry
+    )
+    assert metadata_field.kwargs['description'] == "Arbitrary metadata."
+
+
+def test_should_description_convert_reference_metadata():
+
+    class A(MongoengineObjectType):
+
+        class Meta:
+            model = Article
+
+    class E(MongoengineObjectType):
+
+        class Meta:
+            model = Editor
+
+    editor_field = convert_mongoengine_field(
+        Article._fields['editor'], A._meta.registry
+    ).get_type()
+    assert editor_field.description == "An Editor of a publication."

graphene_mongo/utils.py

@@ -1,8 +1,11 @@
-import inspect
-import mongoengine
+from __future__ import unicode_literals
 
+import inspect
 from collections import OrderedDict
 
+import mongoengine
+from graphene.utils.trim_docstring import trim_docstring
+
 
 def get_model_fields(model, excluding=None):
     excluding = excluding or []
@@ -62,3 +65,25 @@ def get_type_for_document(schema, document):
             _type._meta, 'document', None)
         if document == type_document:
             return _type
+
+
+def get_field_description(field, registry=None):
+    """
+    Common metadata includes verbose_name and help_text.
+
+    http://docs.mongoengine.org/apireference.html#fields
+    """
+    parts = []
+    if hasattr(field, 'document_type'):
+        doc = trim_docstring(field.document_type.__doc__)
+        if doc:
+            parts.append(doc)
+    if hasattr(field, 'verbose_name'):
+        parts.append(field.verbose_name.title())
+    if hasattr(field, 'help_text'):
+        parts.append(field.help_text)
+    if field.db_field != field.name:
+        name_format = "(%s)" if parts else "%s"
+        parts.append(name_format % field.db_field)
+
+    return "\n".join(parts)