From fadb8d61babb76ef7bdbc98279096a8900c7328d Mon Sep 17 00:00:00 2001 From: Frazer McLean Date: Sat, 11 Jun 2016 21:47:33 +0200 Subject: 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 Fixes: #1546 Change-Id: Ib90683850805a2b4ee198e420dc294f32f15d35d --- lib/sqlalchemy/sql/schema.py | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'lib/sqlalchemy/sql/schema.py') diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index e6eabc461..accc1fe0d 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -371,6 +371,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :param useexisting: Deprecated. Use :paramref:`.Table.extend_existing`. + :param comment: Optional string that will render an SQL comment on table + creation. + + .. versionadded:: 1.2 Added the :paramref:`.Table.comment` parameter + to :class:`.Table`. + :param \**kw: Additional keyword arguments not mentioned above are dialect specific, and passed in the form ``_``. See the documentation regarding an individual dialect at @@ -494,6 +500,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause): self.implicit_returning = kwargs.pop('implicit_returning', True) + self.comment = kwargs.pop('comment', None) + if 'info' in kwargs: self.info = kwargs.pop('info') if 'listeners' in kwargs: @@ -588,6 +596,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause): if 'info' in kwargs: self.info = kwargs.pop('info') + self.comment = kwargs.pop('comment', None) + if autoload: if not autoload_replace: # don't replace columns already present. @@ -1044,8 +1054,9 @@ class Column(SchemaItem, ColumnClause): :ref:`metadata_defaults_toplevel` :param doc: optional String that can be used by the ORM or similar - to document attributes. This attribute does not render SQL - comments (a future attribute 'comment' will achieve that). + to document attributes on the Python side. This attribute does + **not** render SQL comments; use the :paramref:`.Column.comment` + parameter for this purpose. :param key: An optional string identifier which will identify this ``Column`` object on the :class:`.Table`. When a key is provided, @@ -1159,6 +1170,13 @@ class Column(SchemaItem, ColumnClause): .. versionadded:: 0.8.3 Added the ``system=True`` parameter to :class:`.Column`. + :param comment: Optional string that will render an SQL comment on + table creation. + + .. versionadded:: 1.2 Added the :paramref:`.Column.comment` + parameter to :class:`.Column`. + + """ name = kwargs.pop('name', None) @@ -1205,6 +1223,7 @@ class Column(SchemaItem, ColumnClause): self.autoincrement = kwargs.pop('autoincrement', "auto") self.constraints = set() self.foreign_keys = set() + self.comment = kwargs.pop('comment', None) # check if this Column is proxying another column if '_proxies' in kwargs: @@ -2309,6 +2328,7 @@ class Sequence(DefaultGenerator): % self.__class__.__name__) + @inspection._self_inspects class FetchedValue(_NotAColumnExpr, SchemaEventTarget): """A marker for a transparent database-side default. -- cgit v1.2.1