Function sort_tables

lib/sqlalchemy/sql/ddl.py:1711–1791

Sort a collection of :class:`_schema.Table` objects based on dependency. This is a dependency-ordered sort which will emit :class:`_schema.Table` objects such that they will follow their dependent :class:`_schema.Table` objects. Tables are dependent on another based on the prese

(
    tables: Iterable[TableClause],
    skip_fn: Optional[Callable[[ForeignKeyConstraint], bool]] = None,
    extra_dependencies: Optional[
        typing_Sequence[Tuple[TableClause, TableClause]]
    ] = None,
)

def sort_tables(
    tables: Iterable[TableClause],
    skip_fn: Optional[Callable[[ForeignKeyConstraint], bool]] = None,
    extra_dependencies: Optional[
        typing_Sequence[Tuple[TableClause, TableClause]]
    ] = None,
) -> List[Table]:
    """Sort a collection of :class:`_schema.Table` objects based on
    dependency.

    This is a dependency-ordered sort which will emit :class:`_schema.Table`
    objects such that they will follow their dependent :class:`_schema.Table`
    objects.
    Tables are dependent on another based on the presence of
    :class:`_schema.ForeignKeyConstraint`
    objects as well as explicit dependencies
    added by :meth:`_schema.Table.add_is_dependent_on`.

    .. warning::

        The :func:`._schema.sort_tables` function cannot by itself
        accommodate automatic resolution of dependency cycles between
        tables, which are usually caused by mutually dependent foreign key
        constraints. When these cycles are detected, the foreign keys
        of these tables are omitted from consideration in the sort.
        A warning is emitted when this condition occurs, which will be an
        exception raise in a future release.   Tables which are not part
        of the cycle will still be returned in dependency order.

        To resolve these cycles, the
        :paramref:`_schema.ForeignKeyConstraint.use_alter` parameter may be
        applied to those constraints which create a cycle.  Alternatively,
        the :func:`_schema.sort_tables_and_constraints` function will
        automatically return foreign key constraints in a separate
        collection when cycles are detected so that they may be applied
        to a schema separately.

    :param tables: a sequence of :class:`_schema.Table` objects.

    :param skip_fn: optional callable which will be passed a
     :class:`_schema.ForeignKeyConstraint` object; if it returns True, this
     constraint will not be considered as a dependency.  Note this is
     **different** from the same parameter in
     :func:`.sort_tables_and_constraints`, which is
     instead passed the owning :class:`_schema.ForeignKeyConstraint` object.

    :param extra_dependencies: a sequence of 2-tuples of tables which will
     also be considered as dependent on each other.

    .. seealso::

        :func:`.sort_tables_and_constraints`

        :attr:`_schema.MetaData.sorted_tables` - uses this function to sort


    """