Add docstring to declarative_base

Change-Id: I5ad44362515908592f1e8b1e6254a5270d43234a
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/295

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index b94104be83097c39f81aeb1be08f87b446ff07f1..e08976f1521341d1ca421a51f0d74a03b2778c56 100644 (file)
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -63,6 +63,14 @@
         exists in 1.0.x as well, however in 1.1 is more noticeable as
         hybrid_property @expression now returns a wrapped element.
 
+    .. change::
+        :tags: change, orm, declarative
+
+        Constructing a declarative base class that inherits from another class
+        will also inherit its docstring. This means
+        :func:`~.ext.declarative.as_declarative` acts more like a normal class
+        decorator.
+
 .. changelog::
     :version: 1.1.0b3
     :released: July 26, 2016

diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py
index e67e79d555d760c151c990f27dd624a575394172..1abd0467e0b40057793b8fe17848690100a19e00 100644 (file)
--- a/lib/sqlalchemy/ext/declarative/api.py
+++ b/lib/sqlalchemy/ext/declarative/api.py
@@ -301,6 +301,9 @@ def declarative_base(bind=None, metadata=None, mapper=None, cls=object,
       compatible callable to use as the meta type of the generated
       declarative base class.
 
+    .. versionchanged:: 1.1 if :paramref:`.declarative_base.cls` is a single class (rather
+         than a tuple), the constructed base class will inherit its docstring.
+
     .. seealso::
 
         :func:`.as_declarative`
@@ -317,6 +320,9 @@ def declarative_base(bind=None, metadata=None, mapper=None, cls=object,
     class_dict = dict(_decl_class_registry=class_registry,
                       metadata=lcl_metadata)
 
+    if isinstance(cls, type):
+        class_dict['__doc__'] = cls.__doc__
+
     if constructor:
         class_dict['__init__'] = constructor
     if mapper:

diff --git a/test/ext/declarative/test_basic.py b/test/ext/declarative/test_basic.py
index ae1a85f8b5a245301490cbd52cb60a5e1e1fcb57..67018d737980a39149e759596c8597aab0e3e40c 100644 (file)
--- a/test/ext/declarative/test_basic.py
+++ b/test/ext/declarative/test_basic.py
@@ -1722,6 +1722,15 @@ class DeclarativeTest(DeclarativeTestBase):
             ]
         )
 
+    def test_cls_docstring(self):
+
+        class MyBase(object):
+            """MyBase Docstring"""
+
+        Base = decl.declarative_base(cls=MyBase)
+
+        eq_(Base.__doc__, MyBase.__doc__)
+
 
 def _produce_test(inline, stringbased):