'Return a copy of this :class:`.Table` associated with a different
:class:`.MetaData`.
E.g.::
m1 = MetaData()
user = Table(\'user\', m1, Column(\'id\', Integer, priamry_key=True))
m2 = MetaData()
user_copy = user.tometadata(m2)
:param metadata: Target :class:`.MetaData` object, into which the
new :class:`.Table` object will be created.
:param schema: optional string name indicating the target schema.
Defaults to the special symbol :attr:`.RETAIN_SCHEMA` which indicates
that no change to the schema name should be made in the new
:class:`.Table`.  If set to a string name, the new :class:`.Table`
will have this new name as the ``.schema``.  If set to ``None``, the
schema will be set to that of the schema set on the target
:class:`.MetaData`, which is typically ``None`` as well, unless
set explicitly::
m2 = MetaData(schema=\'newschema\')
# user_copy_one will have "newschema" as the schema name
user_copy_one = user.tometadata(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)
:param referred_schema_fn: optional callable which can be supplied
in order to provide for the schema name that should be assigned
to the referenced table of a :class:`.ForeignKeyConstraint`.
The callable accepts this parent :class:`.Table`, the
target schema that we are changing to, the :class:`.ForeignKeyConstraint`
object, and the existing "target schema" of that constraint.  The
function should return the string schema name that should be applied.
E.g.::
def referred_schema_fn(table, to_schema,
constraint, referred_schema):
if referred_schema == \'base_tables\':
return referred_schema
else:
return to_schema
new_table = table.tometadata(m2, schema="alt_schema",
referred_schema_fn=referred_schema_fn)
.. versionadded:: 0.9.2'

def tometadata(self, metadata, schema=RETAIN_SCHEMA, referred_schema_fn=None):

    if (schema is RETAIN_SCHEMA):
        schema = self.schema
    elif (schema is None):
        schema = metadata.schema
    key = _get_table_key(self.name, schema)
    if (key in metadata.tables):
        util.warn(("Table    '%s'    already    exists    within    the    given    MetaData    -    not    copying." % self.description))
        return metadata.tables[key]
    args = []
    for c in self.columns:
        args.append(c.copy(schema=schema))
    table = Table(self.name, metadata, schema=schema, *args, **self.kwargs)
    for c in self.constraints:
        if isinstance(c, ForeignKeyConstraint):
            referred_schema = c._referred_schema
            if referred_schema_fn:
                fk_constraint_schema = referred_schema_fn(self, schema, c, referred_schema)
            else:
                fk_constraint_schema = (schema if (referred_schema == self.schema) else None)
            table.append_constraint(c.copy(schema=fk_constraint_schema, target_table=table))
        else:
            table.append_constraint(c.copy(schema=schema, target_table=table))
    for index in self.indexes:
        if ((len(index.columns) == 1) and list(index.columns)[0].index):
            continue
        Index(index.name, unique=index.unique, *[table.c[col] for col in index.columns.keys()], **index.kwargs)
    return self._schema_item_copy(table)
