Allow MetaData as the target for column_reflect event

The :meth:`_event.DDLEvents.column_reflect` event may now be applied to a
:class:`_schema.MetaData` object where it will take effect for the
:class:`_schema.Table` objects local to that collection.

Fixes: #5712
Change-Id: I6044baa72d096ebd1fd99128270119747d1461b9

4 files changed, 74 insertions, 13 deletions

diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py
index 5770eab8c..142637693 100644
--- a/lib/sqlalchemy/engine/reflection.py
+++ b/lib/sqlalchemy/engine/reflection.py
@@ -841,6 +841,7 @@ class Inspector(object):
 
         orig_name = col_d["name"]
 
+        table.metadata.dispatch.column_reflect(self, table, col_d)
         table.dispatch.column_reflect(self, table, col_d)
 
         # fetch name again as column_reflect is allowed to
diff --git a/lib/sqlalchemy/ext/automap.py b/lib/sqlalchemy/ext/automap.py
index 97dff7f4e..8fe318dfb 100644
--- a/lib/sqlalchemy/ext/automap.py
+++ b/lib/sqlalchemy/ext/automap.py
@@ -529,6 +529,36 @@ the :meth:`.AutomapBase.prepare` method is required; if not called, the classes
 we've declared are in an un-mapped state.
 
 
+.. _automap_intercepting_columns:
+
+Intercepting Column Definitions
+===============================
+
+The :class:`_schema.MetaData` and :class:`_schema.Table` objects support an
+event hook :meth:`_events.DDLEvents.column_reflect` that may be used to intercept
+the information reflected about a database column before the :class:`_schema.Column`
+object is constructed.   For example if we wanted to map columns using a
+naming convention such as ``"attr_<columnname>"``, the event could
+be applied as::
+
+    @event.listens_for(Base.metadata, "column_reflect")
+    def column_reflect(inspector, table, column_info):
+        # set column.key = "attr_<lower_case_name>"
+        column_info['key'] = "attr_%s" % column_info['name'].lower()
+
+    # run reflection
+    Base.prepare(engine, reflect=True)
+
+.. versionadded:: 1.4.0b2 the :meth:`_events.DDLEvents.column_reflect` event
+   may be applied to a :class:`_schema.MetaData` object.
+
+.. seealso::
+
+      :meth:`_events.DDLEvents.column_reflect`
+
+      :ref:`mapper_automated_reflection_schemes` - in the ORM mapping documentation
+
+
 """  # noqa
 from .declarative import declarative_base as _declarative_base
 from .. import util
diff --git a/lib/sqlalchemy/sql/events.py b/lib/sqlalchemy/sql/events.py
index 23ea2d8d2..58d04f7aa 100644
--- a/lib/sqlalchemy/sql/events.py
+++ b/lib/sqlalchemy/sql/events.py
@@ -213,8 +213,31 @@ class DDLEvents(event.Events):
         """Called for each unit of 'column info' retrieved when
         a :class:`_schema.Table` is being reflected.
 
-        Currently, this event may only be applied to the :class:`_schema.Table`
-        class directly::
+        This event is most easily used by applying it to a specific
+        :class:`_schema.MetaData` instance, where it will take effect for
+        all :class:`_schema.Table` objects within that
+        :class:`_schema.MetaData` that undergo reflection::
+
+            metadata = MetaData()
+
+            @event.listens_for(metadata, 'column_reflect')
+            def receive_column_reflect(inspector, table, column_info):
+                # receives for all Table objects that are reflected
+                # under this MetaData
+
+
+            # will use the above event hook
+            my_table = Table("my_table", metadata, autoload_with=some_engine)
+
+
+        .. versionadded:: 1.4.0b2 The :meth:`_events.DDLEvents.column_reflect`
+           hook may now be applied to a :class:`_schema.MetaData` object as
+           well as the :class:`_schema.MetaData` class itself where it will
+           take place for all :class:`_schema.Table` objects associated with
+           the targeted :class:`_schema.MetaData`.
+
+        It may also be applied to the :class:`_schema.Table` class across
+        the board::
 
             from sqlalchemy import Table
 
@@ -222,7 +245,8 @@ class DDLEvents(event.Events):
             def receive_column_reflect(inspector, table, column_info):
                 # receives for all Table objects that are reflected
 
-        Or applied using the
+        It can also be applied to a specific :class:`_schema.Table` at the
+        point that one is being reflected using the
         :paramref:`_schema.Table.listeners` parameter::
 
             t1 = Table(
@@ -257,14 +281,6 @@ class DDLEvents(event.Events):
               or :func:`_expression.text` object as well.  Is applied to the
               :paramref:`_schema.Column.server_default` parameter
 
-              .. versionchanged:: 1.1.6
-
-                    The :meth:`.DDLEvents.column_reflect` event allows a non
-                    string :class:`.FetchedValue`,
-                    :func:`_expression.text`, or derived object to be
-                    specified as the value of ``default`` in the column
-                    dictionary.
-
         The event is called before any action is taken against
         this dictionary, and the contents can be modified; the following
         additional keys may be added to the dictionary to further modify
@@ -290,4 +306,12 @@ class DDLEvents(event.Events):
         i.e. those copies that are generated when
         :meth:`_schema.Table.to_metadata` is used.
 
+        .. seealso::
+
+            :ref:`mapper_automated_reflection_schemes` -
+            in the ORM mapping documentation
+
+            :ref:`automap_intercepting_columns` -
+            in the :ref:`automap_toplevel` documentation
+
         """
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index c1f7ab58a..b7e5dac31 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -389,8 +389,10 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         which will be passed to :func:`.event.listen` upon construction.
         This alternate hook to :func:`.event.listen` allows the establishment
         of a listener function specific to this :class:`_schema.Table` before
-        the "autoload" process begins.  Particularly useful for
-        the :meth:`.DDLEvents.column_reflect` event::
+        the "autoload" process begins.  Historically this has been intended
+        for use with the :meth:`.DDLEvents.column_reflect` event, however
+        note that this event hook may now be associated with the
+        :class:`_schema.MetaData` object directly::
 
             def listen_for_reflect(table, column_info):
                 "handle the column reflection event"
@@ -403,6 +405,10 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
                     ('column_reflect', listen_for_reflect)
                 ])
 
+        .. seealso::
+
+            :meth:`_events.DDLEvents.column_reflect`
+
     :param must_exist: When ``True``, indicates that this Table must already
         be present in the given :class:`_schema.MetaData` collection, else
         an exception is raised.