Implement comments for tables, columns

Added support for SQL comments on :class:`.Table` and :class:`.Column`
objects, via the new :paramref:`.Table.comment` and
:paramref:`.Column.comment` arguments.   The comments are included
as part of DDL on table creation, either inline or via an appropriate
ALTER statement, and are also reflected back within table reflection,
as well as via the :class:`.Inspector`.   Supported backends currently
include MySQL, Postgresql, and Oracle.

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Fixes: #1546
Change-Id: Ib90683850805a2b4ee198e420dc294f32f15d35d

3 files changed, 55 insertions, 1 deletions

diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py
index 3968663fb..73cb7eeec 100644
--- a/lib/sqlalchemy/engine/default.py
+++ b/lib/sqlalchemy/engine/default.py
@@ -41,6 +41,8 @@ class DefaultDialect(interfaces.Dialect):
     type_compiler = compiler.GenericTypeCompiler
     preparer = compiler.IdentifierPreparer
     supports_alter = True
+    supports_comments = False
+    inline_comments = False
 
     # the first value we'd get for an autoincrement
     # column.
diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index d0eff1cb1..57f8b8dda 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -422,6 +422,25 @@ class Dialect(object):
 
         raise NotImplementedError()
 
+    def get_table_comment(
+            self, connection, table_name, schema=None, **kw):
+        r"""Return the "comment" for the table identified by `table_name`.
+
+        Given a string `table_name` and an optional string `schema`, return
+        table comment information as a dictionary with this key:
+
+        text
+           text of the comment
+
+        Raises ``NotImplementedError`` for dialects that don't support
+        comments.
+
+        .. versionadded:: 1.2
+
+        """
+
+        raise NotImplementedError()
+
     def normalize_name(self, name):
         """convert the given name to lowercase if it is detected as
         case insensitive.
diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py
index dfa81f4ca..531be3939 100644
--- a/lib/sqlalchemy/engine/reflection.py
+++ b/lib/sqlalchemy/engine/reflection.py
@@ -506,6 +506,26 @@ class Inspector(object):
         return self.dialect.get_unique_constraints(
             self.bind, table_name, schema, info_cache=self.info_cache, **kw)
 
+    def get_table_comment(self, table_name, schema=None, **kw):
+        """Return information about the table comment for ``table_name``.
+
+        Given a string ``table_name`` and an optional string ``schema``,
+        return table comment information as a dictionary with these keys:
+
+        text
+            text of the comment.
+
+        Raises ``NotImplementedError`` for a dialect that does not support
+        comments.
+
+        .. versionadded:: 1.2
+
+        """
+
+        return self.dialect.get_table_comment(
+            self.bind, table_name, schema, info_cache=self.info_cache,
+            **kw)
+
     def get_check_constraints(self, table_name, schema=None, **kw):
         """Return information about check constraints in `table_name`.
 
@@ -624,6 +644,10 @@ class Inspector(object):
             table_name, schema, table, cols_by_orig_name,
             include_columns, exclude_columns, reflection_options)
 
+        self._reflect_table_comment(
+            table_name, schema, table, reflection_options
+        )
+
     def _reflect_column(
         self, table, col_d, include_columns,
             exclude_columns, cols_by_orig_name):
@@ -643,7 +667,7 @@ class Inspector(object):
 
         col_kw = dict(
             (k, col_d[k])
-            for k in ['nullable', 'autoincrement', 'quote', 'info', 'key']
+            for k in ['nullable', 'autoincrement', 'quote', 'info', 'key', 'comment']
             if k in col_d
         )
 
@@ -841,3 +865,12 @@ class Inspector(object):
         for const_d in constraints:
             table.append_constraint(
                 sa_schema.CheckConstraint(**const_d))
+
+    def _reflect_table_comment(
+            self, table_name, schema, table, reflection_options):
+        try:
+            comment_dict = self.get_table_comment(table_name, schema)
+        except NotImplementedError:
+            return
+        else:
+            table.comment = comment_dict.get('text', None)