Rename Table.tometadata to to_metadata

Renamed the :meth:`_schema.Table.tometadata` method to
:meth:`_schema.Table.to_metadata`.  The previous name remains with a
deprecation warning.

Updated the "decorate" utility function to support decoration
of functions that include non-builtins as default values.

Moves test for deprecated "databases" package into
test/dialect/test_deprecations.py

Fixes: #5413
Fixes: #5426
Change-Id: I6ed899871c935f9e46360127c17ccb7cf97cea6e

3 files changed, 44 insertions, 15 deletions

diff --git a/lib/sqlalchemy/sql/events.py b/lib/sqlalchemy/sql/events.py
index 51556d929..d7836a5a0 100644
--- a/lib/sqlalchemy/sql/events.py
+++ b/lib/sqlalchemy/sql/events.py
@@ -60,7 +60,7 @@ class DDLEvents(event.Events):
 
     For all :class:`.DDLEvent` events, the ``propagate=True`` keyword argument
     will ensure that a given event handler is propagated to copies of the
-    object, which are made when using the :meth:`_schema.Table.tometadata`
+    object, which are made when using the :meth:`_schema.Table.to_metadata`
     method::
 
         from sqlalchemy import DDL
@@ -71,7 +71,7 @@ class DDLEvents(event.Events):
             propagate=True
         )
 
-        new_table = some_table.tometadata(new_metadata)
+        new_table = some_table.to_metadata(new_metadata)
 
     The above :class:`.DDL` object will also be associated with the
     :class:`_schema.Table` object represented by ``new_table``.
@@ -109,7 +109,7 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
 
@@ -131,7 +131,7 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
 
@@ -153,7 +153,7 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
 
@@ -175,7 +175,7 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
 
@@ -190,7 +190,7 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
 
@@ -205,7 +205,7 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
 
@@ -284,6 +284,6 @@ class DDLEvents(event.Events):
         modifier for this event; when True, the listener function will
         be established for any copies made of the target object,
         i.e. those copies that are generated when
-        :meth:`_schema.Table.tometadata` is used.
+        :meth:`_schema.Table.to_metadata` is used.
 
         """
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 3df1c9f91..ac6276c1c 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -867,6 +867,11 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
             bind = _bind_or_error(self)
         bind._run_ddl_visitor(ddl.SchemaDropper, self, checkfirst=checkfirst)
 
+    @util.deprecated(
+        "1.4",
+        ":meth:`_schema.Table.tometadata` is renamed to "
+        ":meth:`_schema.Table.to_metadata`",
+    )
     def tometadata(
         self,
         metadata,
@@ -878,6 +883,26 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         associated with a different
         :class:`_schema.MetaData`.
 
+        See :meth:`_schema.Table.to_metadata` for a full description.
+
+        """
+        return self.to_metadata(
+            metadata,
+            schema=schema,
+            referred_schema_fn=referred_schema_fn,
+            name=name,
+        )
+
+    def to_metadata(
+        self,
+        metadata,
+        schema=RETAIN_SCHEMA,
+        referred_schema_fn=None,
+        name=None,
+    ):
+        """Return a copy of this :class:`_schema.Table` associated with a
+        different :class:`_schema.MetaData`.
+
         E.g.::
 
             m1 = MetaData()
@@ -885,7 +910,11 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
             user = Table('user', m1, Column('id', Integer, primary_key=True))
 
             m2 = MetaData()
-            user_copy = user.tometadata(m2)
+            user_copy = user.to_metadata(m2)
+
+        .. versionchanged:: 1.4  The :meth:`_schema.Table.to_metadata` function
+           was renamed from :meth:`_schema.Table.tometadata`.
+
 
         :param metadata: Target :class:`_schema.MetaData` object,
          into which the
@@ -905,12 +934,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
             m2 = MetaData(schema='newschema')
 
             # user_copy_one will have "newschema" as the schema name
-            user_copy_one = user.tometadata(m2, schema=None)
+            user_copy_one = user.to_metadata(m2, schema=None)
 
             m3 = MetaData()  # schema defaults to None
 
             # user_copy_two will have None as the schema name
-            user_copy_two = user.tometadata(m3, schema=None)
+            user_copy_two = user.to_metadata(m3, schema=None)
 
         :param referred_schema_fn: optional callable which can be supplied
          in order to provide for the schema name that should be assigned
@@ -929,7 +958,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
                     else:
                         return to_schema
 
-                new_table = table.tometadata(m2, schema="alt_schema",
+                new_table = table.to_metadata(m2, schema="alt_schema",
                                         referred_schema_fn=referred_schema_fn)
 
          .. versionadded:: 0.9.2
@@ -1548,7 +1577,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
     def copy(self, **kw):
         """Create a copy of this ``Column``, uninitialized.
 
-        This is used in :meth:`_schema.Table.tometadata`.
+        This is used in :meth:`_schema.Table.to_metadata`.
 
         """
 
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 5d7f80b1b..186f885d8 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -1391,7 +1391,7 @@ class Enum(Emulated, String, SchemaType):
            will be copied to the "schema" attribute of this
            :class:`.Enum`, replacing whatever value was passed for the
            ``schema`` attribute.   This also takes effect when using the
-           :meth:`_schema.Table.tometadata` operation.
+           :meth:`_schema.Table.to_metadata` operation.
 
         :param validate_strings: when True, string values that are being
            passed to the database in a SQL statement will be checked