From: Frazer McLean <frazer@frazermclean.co.uk>
Date: Mon, 25 Jul 2016 22:02:03 +0000 (+0200)
Subject: Add docstring to declarative_base
X-Git-Tag: rel_1_1_0~46^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=87d5982e582f2439e6d6fad8b38d9f2122811f1c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 b94104be83..e08976f152 100644
--- 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 e67e79d555..1abd0467e0 100644
--- 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 ae1a85f8b5..67018d7379 100644
--- 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):