# sql/schema.py

# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors

# <see AUTHORS file>

#

# This module is part of SQLAlchemy and is released under

# the MIT License: https://www.opensource.org/licenses/mit-license.php

"""The schema module provides the building blocks for database metadata.

Each element within this module describes a database entity which can be

created and dropped, or is otherwise part of such an entity. Examples include

tables, columns, sequences, and indexes.

All entities are subclasses of :class:`~sqlalchemy.schema.SchemaItem`, and as

defined in this module they are intended to be agnostic of any vendor-specific

constructs.

A collection of entities are grouped into a unit called

:class:`~sqlalchemy.schema.MetaData`. MetaData serves as a logical grouping of

schema elements, and can also be associated with an actual database connection

such that operations involving the contained elements can contact the database

as needed.

Two of the elements here also build upon their "syntactic" counterparts, which

are defined in :class:`~sqlalchemy.sql.expression.`, specifically

:class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.schema.Column`.

Since these objects are part of the SQL expression language, they are usable

as components in SQL expressions.

"""

from __future__ import annotations

from abc import ABC

import collections

from enum import Enum

import operator

import typing

from typing import Any

from typing import Callable

from typing import cast

from typing import Collection

from typing import Dict

from typing import Final

from typing import Iterable

from typing import Iterator

from typing import List

from typing import Literal

from typing import Mapping

from typing import NoReturn

from typing import Optional

from typing import overload

from typing import Protocol

from typing import Sequence as _typing_Sequence

from typing import Set

from typing import Tuple

from typing import Type

from typing import TYPE_CHECKING

from typing import TypedDict

from typing import TypeGuard

from typing import TypeVar

from typing import Union

from . import coercions

from . import ddl

from . import roles

from . import type_api

from . import visitors

from ._annotated_cols import _ColCC_co

from ._annotated_cols import _extract_columns_from_class

from ._annotated_cols import _TC_co

from ._annotated_cols import Named

from ._annotated_cols import TypedColumns

from ._typing import _T

from .base import _DefaultDescriptionTuple

from .base import _NoArg

from .base import _NoneName

from .base import _SentinelColumnCharacterization

from .base import _SentinelDefaultCharacterization

from .base import DedupeColumnCollection

from .base import DialectKWArgs

from .base import Executable

from .base import SchemaEventTarget as SchemaEventTarget

from .base import SchemaVisitable as SchemaVisitable

from .coercions import _document_text_coercion

from .ddl import CheckFirst

from .elements import ClauseElement

from .elements import ColumnClause

from .elements import ColumnElement

from .elements import quoted_name

from .elements import TextClause

from .selectable import TableClause

from .type_api import to_instance

from .visitors import ExternallyTraversible

from .. import event

from .. import exc

from .. import inspection

from .. import util

from ..util import HasMemoized

from ..util.typing import Self

if typing.TYPE_CHECKING:

from ._typing import _AutoIncrementType

from ._typing import _CreateDropBind

from ._typing import _DDLColumnArgument

from ._typing import _DDLColumnReferenceArgument

from ._typing import _InfoType

from ._typing import _TextCoercedExpressionArgument

from ._typing import _TypeEngineArgument

from .base import ColumnSet

from .base import ReadOnlyColumnCollection

from .compiler import DDLCompiler

from .ddl import TableCreateDDL

from .ddl import TableDropDDL

from .elements import BindParameter

from .elements import KeyedColumnElement

from .functions import Function

from .sqltypes import SchemaType

from .type_api import TypeEngine

from .visitors import anon_map

from ..engine import Connection

from ..engine import Engine

from ..engine.interfaces import _CoreMultiExecuteParams

from ..engine.interfaces import CoreExecuteOptionsParameter

from ..engine.interfaces import ExecutionContext

from ..engine.reflection import _ReflectionInfo

from ..sql.selectable import FromClause

_SI = TypeVar("_SI", bound="SchemaItem")

_TAB = TypeVar("_TAB", bound="Table")

_ConstraintNameArgument = Optional[Union[str, _NoneName]]

_ServerDefaultArgument = Union[

"FetchedValue", str, TextClause, ColumnElement[Any]

]

_ServerOnUpdateArgument = _ServerDefaultArgument

class SchemaConst(Enum):

RETAIN_SCHEMA = 1

"""Symbol indicating that a :class:`_schema.Table`, :class:`.Sequence`

or in some cases a :class:`_schema.ForeignKey` object, in situations

where the object is being copied for a :meth:`.Table.to_metadata`

operation, should retain the schema name that it already has.

"""

BLANK_SCHEMA = 2

"""Symbol indicating that a :class:`_schema.Table` or :class:`.Sequence`

should have 'None' for its schema, even if the parent

:class:`_schema.MetaData` has specified a schema.

.. seealso::

:paramref:`_schema.MetaData.schema`

:paramref:`_schema.Table.schema`

:paramref:`.Sequence.schema`

"""

NULL_UNSPECIFIED = 3

"""Symbol indicating the "nullable" keyword was not passed to a Column.

This is used to distinguish between the use case of passing

``nullable=None`` to a :class:`.Column`, which has special meaning

on some backends such as SQL Server.

"""

RETAIN_SCHEMA: Final[Literal[SchemaConst.RETAIN_SCHEMA]] = (

SchemaConst.RETAIN_SCHEMA

)

BLANK_SCHEMA: Final[Literal[SchemaConst.BLANK_SCHEMA]] = (

SchemaConst.BLANK_SCHEMA

)

NULL_UNSPECIFIED: Final[Literal[SchemaConst.NULL_UNSPECIFIED]] = (

SchemaConst.NULL_UNSPECIFIED

)

def _get_table_key(name: str, schema: Optional[str]) -> str:

if schema is None:

return name

else:

return schema + "." + name

# this should really be in sql/util.py but we'd have to

# break an import cycle

def _copy_expression(

expression: ColumnElement[Any],

source_table: Optional[Table],

target_table: Optional[Table],

) -> ColumnElement[Any]:

if source_table is None or target_table is None:

return expression

fixed_source_table = source_table

fixed_target_table = target_table

def replace(

element: ExternallyTraversible, **kw: Any

) -> Optional[ExternallyTraversible]:

if (

isinstance(element, Column)

and element.table is fixed_source_table

and element.key in fixed_source_table.c

):

return fixed_target_table.c[element.key]

else:

return None

return cast(

ColumnElement[Any],

visitors.replacement_traverse(expression, {}, replace),

)

@inspection._self_inspects

class SchemaItem(SchemaVisitable):

"""Base class for items that define a database schema."""

__visit_name__ = "schema_item"

create_drop_stringify_dialect = "default"

def _init_items(self, *args: SchemaItem, **kw: Any) -> None:

"""Initialize the list of child items for this SchemaItem."""

for item in args:

if item is not None:

try:

spwd = item._set_parent_with_dispatch

except AttributeError as err:

raise exc.ArgumentError(

"'SchemaItem' object, such as a 'Column' or a "

f"'Constraint' expected, got {item!r}"

) from err

else:

spwd(self, **kw)

def __repr__(self) -> str:

return util.generic_repr(self, omit_kwarg=["info"])

@util.memoized_property

def info(self) -> _InfoType:

"""Info dictionary associated with the object, allowing user-defined

data to be associated with this :class:`.SchemaItem`.

The dictionary is automatically generated when first accessed.

It can also be specified in the constructor of some objects,

such as :class:`_schema.Table` and :class:`_schema.Column`.

"""

return {}

def _schema_item_copy(self, schema_item: _SI) -> _SI:

if "info" in self.__dict__:

schema_item.info = self.info.copy()

schema_item.dispatch._update(self.dispatch)

return schema_item

_use_schema_map = True

class HasConditionalDDL:

"""define a class that includes the :meth:`.HasConditionalDDL.ddl_if`

method, allowing for conditional rendering of DDL.

Currently applies to constraints and indexes.

.. versionadded:: 2.0

"""

_ddl_if: Optional[ddl.DDLIf] = None

def ddl_if(

self,

dialect: Optional[str] = None,

callable_: Optional[ddl.DDLIfCallable] = None,

state: Optional[Any] = None,

) -> Self:

r"""apply a conditional DDL rule to this schema item.

These rules work in a similar manner to the

:meth:`.ExecutableDDLElement.execute_if` callable, with the added

feature that the criteria may be checked within the DDL compilation

phase for a construct such as :class:`.CreateTable`.

:meth:`.HasConditionalDDL.ddl_if` currently applies towards the

:class:`.Index` construct as well as all :class:`.Constraint`

constructs.

:param dialect: string name of a dialect, or a tuple of string names

to indicate multiple dialect types.

:param callable\_: a callable that is constructed using the same form

as that described in

:paramref:`.ExecutableDDLElement.execute_if.callable_`.

:param state: any arbitrary object that will be passed to the

callable, if present.

.. versionadded:: 2.0

.. seealso::

:ref:`schema_ddl_ddl_if` - background and usage examples

"""

self._ddl_if = ddl.DDLIf(dialect, callable_, state)

return self

class HasSchemaAttr(SchemaItem):

"""schema item that includes a top-level schema name"""

schema: Optional[str]

class Table(

DialectKWArgs,

HasSchemaAttr,

TableClause[_ColCC_co],

inspection.Inspectable["Table"],

):

r"""Represent a table in a database.

e.g.::

from sqlalchemy import Table, MetaData, Integer, String, Column

metadata = MetaData()

mytable = Table(

"mytable",

metadata,

Column("mytable_id", Integer, primary_key=True),

Column("value", String(50)),

)

The :class:`_schema.Table`

object constructs a unique instance of itself based

on its name and optional schema name within the given

:class:`_schema.MetaData` object. Calling the :class:`_schema.Table`

constructor with the same name and same :class:`_schema.MetaData` argument

a second time will return the *same* :class:`_schema.Table`

object - in this way

the :class:`_schema.Table` constructor acts as a registry function.

May also be defined as "typed table" by passing a subclass of

:class:`_schema.TypedColumns` as the 3rd argument::

from sqlalchemy import TypedColumns, select

class user_cols(TypedColumns):

id = Column(Integer, primary_key=True)

name: Column[str]

age: Column[int]

middle_name: Column[str | None]

# optional, used to infer the select types when selecting the table

__row_pos__: tuple[int, str, int, str | None]

user = Table("user", metadata, user_cols)

# the columns are typed: the statement has type Select[int, str]

stmt = sa.select(user.c.id, user.c.name).where(user.c.age > 30)

# Inferred as Select[int, str, int, str | None] thanks to __row_pos__

stmt1 = user.select()

stmt2 = sa.select(user)

The :attr:`sqlalchemy.sql._annotated_cols.HasRowPos.__row_pos__`

annotation is optional, and it's used to infer the types in a

:class:`_sql.Select` when selecting the complete table.

If a :class:`_schema.TypedColumns` does not define it,

the default ``Select[*tuple[Any]]`` will be inferred.

An existing :class:`Table` can be casted as "typed table" using

the :meth:`Table.with_cols`::

class mytable_cols(TypedColumns):

mytable_id: Column[int]

value: Column[str | None]

typed_mytable = mytable.with_cols(mytable_cols)

.. seealso::

:ref:`metadata_describing` Introduction to database metadata

:class:`_schema.TypedColumns` More information about typed column

definition

.. versionchanged:: 2.1.0b2 - :class:`_schema.Table` is now generic to

support "typed tables"

"""

__visit_name__ = "table"

if TYPE_CHECKING:

@util.ro_non_memoized_property

def primary_key(self) -> PrimaryKeyConstraint: ...

@util.ro_non_memoized_property

def foreign_keys(self) -> Set[ForeignKey]: ...

def with_cols(self, type_: type[_TC_co]) -> Table[_TC_co]: ...

_columns: DedupeColumnCollection[Column[Any]] # type: ignore[assignment]

_sentinel_column: Optional[Column[Any]]

constraints: Set[Constraint]

"""A collection of all :class:`_schema.Constraint` objects associated with

this :class:`_schema.Table`.

Includes :class:`_schema.PrimaryKeyConstraint`,

:class:`_schema.ForeignKeyConstraint`, :class:`_schema.UniqueConstraint`,

:class:`_schema.CheckConstraint`. A separate collection

:attr:`_schema.Table.foreign_key_constraints` refers to the collection

of all :class:`_schema.ForeignKeyConstraint` objects, and the

:attr:`_schema.Table.primary_key` attribute refers to the single

:class:`_schema.PrimaryKeyConstraint` associated with the

:class:`_schema.Table`.

.. seealso::

:attr:`_schema.Table.constraints`

:attr:`_schema.Table.primary_key`

:attr:`_schema.Table.foreign_key_constraints`

:attr:`_schema.Table.indexes`

:class:`_reflection.Inspector`

"""

indexes: Set[Index]

"""A collection of all :class:`_schema.Index` objects associated with this

:class:`_schema.Table`.

.. seealso::

:meth:`_reflection.Inspector.get_indexes`

"""

def _gen_cache_key(

self, anon_map: anon_map, bindparams: List[BindParameter[Any]]

) -> Tuple[Any, ...]:

if self._annotations:

return (self,) + self._annotations_cache_key

else:

return (self,)

if not typing.TYPE_CHECKING:

# typing tools seem to be inconsistent in how they handle

# __new__, so suggest this pattern for classes that use

# __new__. apply typing to the __init__ method normally

@util.deprecated_params(

mustexist=(

"1.4",

"Deprecated alias of :paramref:`_schema.Table.must_exist`",

),

)

def __new__(cls, *args: Any, **kw: Any) -> Any:

return cls._new(*args, **kw)

@classmethod

def _new(cls, *args: Any, **kw: Any) -> Any:

if not args and not kw:

# python3k pickle seems to call this

return object.__new__(cls)

try:

name, metadata, *other_args = args

except ValueError:

raise TypeError(

"Table() takes at least two positional-only "

"arguments 'name', and 'metadata'"

) from None

if other_args and isinstance(other_args[0], type):

typed_columns_cls = other_args[0]

if not issubclass(typed_columns_cls, TypedColumns):

raise exc.InvalidRequestError(

"The ``typed_columns_cls`` argument requires a "

"TypedColumns subclass."

)

elif hasattr(typed_columns_cls, "_sa_class_manager"):

# an orm class subclassed with TypedColumns. Reject it

raise exc.InvalidRequestError(

"To get a typed table from an ORM class, use the "

"`as_typed_table()` function instead."

)

extracted_columns = _extract_columns_from_class(typed_columns_cls)

other_args = extracted_columns + other_args[1:]

elif "typed_columns_cls" in kw:

raise TypeError(

"The ``typed_columns_cls`` argument may be passed "

"only positionally"

)

schema = kw.get("schema", None)

if schema is None:

schema = metadata.schema

elif schema is BLANK_SCHEMA:

schema = None

keep_existing = kw.get("keep_existing", False)

extend_existing = kw.get("extend_existing", False)

if keep_existing and extend_existing:

msg = "keep_existing and extend_existing are mutually exclusive."

raise exc.ArgumentError(msg)

must_exist = kw.pop("must_exist", kw.pop("mustexist", False))

key = _get_table_key(name, schema)

if key in metadata.tables:

if not keep_existing and not extend_existing and bool(other_args):

raise exc.InvalidRequestError(

f"Table '{key}' is already defined for this MetaData "

"instance. Specify 'extend_existing=True' "

"to redefine "

"options and columns on an "

"existing Table object."

)

table = metadata.tables[key]

if extend_existing:

table._init_existing(*other_args, **kw)

return table

else:

if must_exist:

raise exc.InvalidRequestError(f"Table '{key}' not defined")

table = object.__new__(cls)

table.dispatch.before_parent_attach(table, metadata)

metadata._add_table(name, schema, table)

try:

table.__init__(name, metadata, *other_args, _no_init=False, **kw) # type: ignore[misc] # noqa: E501

table.dispatch.after_parent_attach(table, metadata)

return table

except Exception:

with util.safe_reraise():

metadata._remove_table(name, schema)

@overload

def __init__(

self: Table[_TC_co],

name: str,

metadata: MetaData,

typed_columns_cls: type[_TC_co],

/,

*args: SchemaItem,

schema: str | Literal[SchemaConst.BLANK_SCHEMA] | None = None,

quote: bool | None = None,

quote_schema: bool | None = None,

keep_existing: bool = False,

extend_existing: bool = False,

implicit_returning: bool = True,

comment: str | None = None,

info: dict[Any, Any] | None = None,

listeners: (

_typing_Sequence[tuple[str, Callable[..., Any]]] | None

) = None,

prefixes: _typing_Sequence[str] | None = None,

**kw: Any,

) -> None: ...

@overload

def __init__(

self: Table[ReadOnlyColumnCollection[str, Column[Any]]],

name: str,

metadata: MetaData,

/,

*args: SchemaItem,

schema: str | Literal[SchemaConst.BLANK_SCHEMA] | None = None,

quote: bool | None = None,

quote_schema: Optional[bool] = None,

autoload_with: Optional[Union[Engine, Connection]] = None,

autoload_replace: bool = True,

keep_existing: bool = False,

extend_existing: bool = False,

resolve_fks: bool = True,

include_columns: Optional[Collection[str]] = None,

implicit_returning: bool = True,

comment: str | None = None,

info: dict[Any, Any] | None = None,

listeners: (

_typing_Sequence[tuple[str, Callable[..., Any]]] | None

) = None,

prefixes: _typing_Sequence[str] | None = None,

_creator_ddl: TableCreateDDL | None = None,

_dropper_ddl: TableDropDDL | None = None,

# used internally in the metadata.reflect() process

_extend_on: Optional[Set[Table]] = None,

# used by __new__ to bypass __init__

_no_init: bool = True,

# dialect-specific keyword args

**kw: Any,

) -> None: ...

def __init__(

self,

name: str,

metadata: MetaData,

/,

*args: Any,

schema: str | Literal[SchemaConst.BLANK_SCHEMA] | None = None,

quote: bool | None = None,

quote_schema: Optional[bool] = None,

autoload_with: Optional[Union[Engine, Connection]] = None,

autoload_replace: bool = True,

keep_existing: bool = False,

extend_existing: bool = False,

resolve_fks: bool = True,

include_columns: Optional[Collection[str]] = None,

implicit_returning: bool = True,

comment: str | None = None,

info: dict[Any, Any] | None = None,

listeners: (

_typing_Sequence[tuple[str, Callable[..., Any]]] | None

) = None,

prefixes: _typing_Sequence[str] | None = None,

_creator_ddl: TableCreateDDL | None = None,

_dropper_ddl: TableDropDDL | None = None,

# used internally in the metadata.reflect() process

_extend_on: Optional[Set[Table]] = None,

# used by __new__ to bypass __init__

_no_init: bool = True,

# dialect-specific keyword args

**kw: Any,

) -> None:

r"""Constructor for :class:`_schema.Table`.

:param name: The name of this table as represented in the database.

The table name, along with the value of the ``schema`` parameter,

forms a key which uniquely identifies this :class:`_schema.Table`

within

the owning :class:`_schema.MetaData` collection.

Additional calls to :class:`_schema.Table` with the same name,

metadata,

and schema name will return the same :class:`_schema.Table` object.

Names which contain no upper case characters

will be treated as case insensitive names, and will not be quoted

unless they are a reserved word or contain special characters.

A name with any number of upper case characters is considered

to be case sensitive, and will be sent as quoted.

To enable unconditional quoting for the table name, specify the flag

``quote=True`` to the constructor, or use the :class:`.quoted_name`

construct to specify the name.

:param metadata: a :class:`_schema.MetaData`

object which will contain this

table. The metadata is used as a point of association of this table

with other tables which are referenced via foreign key. It also

may be used to associate this table with a particular

:class:`.Connection` or :class:`.Engine`.

:param table_columns_cls: a subclass of :class:`_schema.TypedColumns`

that defines the columns that will be "typed" when accessing

them from the :attr:`_schema.Table.c` attribute.

.. versionadded:: 2.1.0b2

:param \*args: Additional positional arguments are used primarily

to add the list of :class:`_schema.Column`

objects contained within this

table. Similar to the style of a CREATE TABLE statement, other

:class:`.SchemaItem` constructs may be added here, including

:class:`.PrimaryKeyConstraint`, and

:class:`_schema.ForeignKeyConstraint`.

Additional columns may be provided also when using a

:paramref:`_schema.Table.table_columns_cls` class; they will

be appended to the "typed" columns and will appear as untyped

when accessing them via the :attr:`_schema.Table.c` collection.

:param autoload_replace: Defaults to ``True``; when using

:paramref:`_schema.Table.autoload_with`

in conjunction with :paramref:`_schema.Table.extend_existing`,

indicates

that :class:`_schema.Column` objects present in the already-existing

:class:`_schema.Table`

object should be replaced with columns of the same

name retrieved from the autoload process. When ``False``, columns

already present under existing names will be omitted from the

reflection process.

Note that this setting does not impact :class:`_schema.Column` objects

specified programmatically within the call to :class:`_schema.Table`

that

also is autoloading; those :class:`_schema.Column` objects will always

replace existing columns of the same name when

:paramref:`_schema.Table.extend_existing` is ``True``.

.. seealso::

:paramref:`_schema.Table.autoload_with`

:paramref:`_schema.Table.extend_existing`

:param autoload_with: An :class:`_engine.Engine` or

:class:`_engine.Connection` object,

or a :class:`_reflection.Inspector` object as returned by

:func:`_sa.inspect`

against one, with which this :class:`_schema.Table`

object will be reflected.

When set to a non-None value, the autoload process will take place

for this table against the given engine or connection.

.. seealso::

:ref:`metadata_reflection_toplevel`

:meth:`_events.DDLEvents.column_reflect`

:ref:`metadata_reflection_dbagnostic_types`

:param extend_existing: When ``True``, indicates that if this

:class:`_schema.Table` is already present in the given

:class:`_schema.MetaData`,

apply further arguments within the constructor to the existing

:class:`_schema.Table`.

If :paramref:`_schema.Table.extend_existing` or

:paramref:`_schema.Table.keep_existing` are not set,

and the given name

of the new :class:`_schema.Table` refers to a :class:`_schema.Table`

that is

already present in the target :class:`_schema.MetaData` collection,

and

this :class:`_schema.Table`

specifies additional columns or other constructs

or flags that modify the table's state, an

error is raised. The purpose of these two mutually-exclusive flags

is to specify what action should be taken when a

:class:`_schema.Table`

is specified that matches an existing :class:`_schema.Table`,

yet specifies

additional constructs.

:paramref:`_schema.Table.extend_existing`

will also work in conjunction

with :paramref:`_schema.Table.autoload_with` to run a new reflection

operation against the database, even if a :class:`_schema.Table`

of the same name is already present in the target

:class:`_schema.MetaData`; newly reflected :class:`_schema.Column`

objects

and other options will be added into the state of the

:class:`_schema.Table`, potentially overwriting existing columns

and options of the same name.

As is always the case with :paramref:`_schema.Table.autoload_with`,

:class:`_schema.Column` objects can be specified in the same

:class:`_schema.Table`

constructor, which will take precedence. Below, the existing

table ``mytable`` will be augmented with :class:`_schema.Column`

objects

both reflected from the database, as well as the given

:class:`_schema.Column`

named "y"::

Table(

"mytable",

metadata,

Column("y", Integer),

extend_existing=True,

autoload_with=engine,

)

.. seealso::

:paramref:`_schema.Table.autoload_with`

:paramref:`_schema.Table.autoload_replace`

:paramref:`_schema.Table.keep_existing`

:param implicit_returning: True by default - indicates that

RETURNING can be used, typically by the ORM, in order to fetch

server-generated values such as primary key values and

server side defaults, on those backends which support RETURNING.

In modern SQLAlchemy there is generally no reason to alter this

setting, except for some backend specific cases

(see :ref:`mssql_triggers` in the SQL Server dialect documentation

for one such example).

:param include_columns: A list of strings indicating a subset of

columns to be loaded via the ``autoload`` operation; table columns who

aren't present in this list will not be represented on the resulting

``Table`` object. Defaults to ``None`` which indicates all columns

should be reflected.

:param resolve_fks: Whether or not to reflect :class:`_schema.Table`

objects

related to this one via :class:`_schema.ForeignKey` objects, when

:paramref:`_schema.Table.autoload_with` is

specified. Defaults to True. Set to False to disable reflection of

related tables as :class:`_schema.ForeignKey`

objects are encountered; may be

used either to save on SQL calls or to avoid issues with related tables

that can't be accessed. Note that if a related table is already present

in the :class:`_schema.MetaData` collection, or becomes present later,

a

:class:`_schema.ForeignKey` object associated with this

:class:`_schema.Table` will

resolve to that table normally.

.. seealso::

:paramref:`.MetaData.reflect.resolve_fks`

:param info: Optional data dictionary which will be populated into the

:attr:`.SchemaItem.info` attribute of this object.

:param keep_existing: When ``True``, indicates that if this Table

is already present in the given :class:`_schema.MetaData`, ignore

further arguments within the constructor to the existing

:class:`_schema.Table`, and return the :class:`_schema.Table`

object as

originally created. This is to allow a function that wishes

to define a new :class:`_schema.Table` on first call, but on

subsequent calls will return the same :class:`_schema.Table`,

without any of the declarations (particularly constraints)

being applied a second time.

If :paramref:`_schema.Table.extend_existing` or

:paramref:`_schema.Table.keep_existing` are not set,

and the given name

of the new :class:`_schema.Table` refers to a :class:`_schema.Table`

that is

already present in the target :class:`_schema.MetaData` collection,

and

this :class:`_schema.Table`

specifies additional columns or other constructs

or flags that modify the table's state, an

error is raised. The purpose of these two mutually-exclusive flags

is to specify what action should be taken when a

:class:`_schema.Table`

is specified that matches an existing :class:`_schema.Table`,

yet specifies

additional constructs.

.. seealso::

:paramref:`_schema.Table.extend_existing`

:param listeners: A list of tuples of the form ``(<eventname>, <fn>)``

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. 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"

# ...

t = Table(

"sometable",

autoload_with=engine,

listeners=[("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.

:param prefixes:

A list of strings to insert after CREATE in the CREATE TABLE

statement. They will be separated by spaces.

:param quote: Force quoting of this table's name on or off, corresponding

to ``True`` or ``False``. When left at its default of ``None``,

the column identifier will be quoted according to whether the name is

case sensitive (identifiers with at least one upper case character are

treated as case sensitive), or if it's a reserved word. This flag

is only needed to force quoting of a reserved word which is not known

by the SQLAlchemy dialect.

.. note:: setting this flag to ``False`` will not provide

case-insensitive behavior for table reflection; table reflection

will always search for a mixed-case name in a case sensitive

fashion. Case insensitive names are specified in SQLAlchemy only

by stating the name with all lower case characters.

:param quote_schema: same as 'quote' but applies to the schema identifier.

:param schema: The schema name for this table, which is required if

the table resides in a schema other than the default selected schema

for the engine's database connection. Defaults to ``None``.

If the owning :class:`_schema.MetaData` of this :class:`_schema.Table`

specifies its

own :paramref:`_schema.MetaData.schema` parameter,

then that schema name will

be applied to this :class:`_schema.Table`

if the schema parameter here is set

to ``None``. To set a blank schema name on a :class:`_schema.Table`

that

would otherwise use the schema set on the owning

:class:`_schema.MetaData`,

specify the special symbol :attr:`.BLANK_SCHEMA`.

The quoting rules for the schema name are the same as those for the

``name`` parameter, in that quoting is applied for reserved words or

case-sensitive names; to enable unconditional quoting for the schema

name, specify the flag ``quote_schema=True`` to the constructor, or use

the :class:`.quoted_name` construct to specify the name.

:param comment: Optional string that will render an SQL comment on table

creation.

:param \**kw: Additional keyword arguments not mentioned above are

dialect specific, and passed in the form ``<dialectname>_<argname>``.

See the documentation regarding an individual dialect at

:ref:`dialect_toplevel` for detail on documented arguments.

""" # noqa: E501

if _no_init:

# don't run __init__ from __new__ by default;

# __new__ has a specific place that __init__ is called

return

if args:

# this is the call done by `__new__` that should have resolved

# TypedColumns to the individual columns

assert not (

isinstance(args[0], type) and issubclass(args[0], TypedColumns)

)

super().__init__(quoted_name(name, quote))

self.metadata = metadata

if schema is None:

self.schema = metadata.schema

elif schema is BLANK_SCHEMA:

self.schema = None

else:

quote_schema = quote_schema

assert isinstance(schema, str)

self.schema = quoted_name(schema, quote_schema)

self._sentinel_column = None

self._creator_ddl = _creator_ddl

self._dropper_ddl = _dropper_ddl

self.indexes = set()

self.constraints = set()

PrimaryKeyConstraint(

_implicit_generated=True

)._set_parent_with_dispatch(self)

self.foreign_keys = set() # type: ignore

self._extra_dependencies: Set[Table] = set()

if self.schema is not None:

self.fullname = "%s.%s" % (self.schema, self.name)

else:

self.fullname = self.name

self.implicit_returning = implicit_returning

_reflect_info = kw.pop("_reflect_info", None)

self.comment = comment

if info is not None:

self.info = info

if listeners is not None:

for evt, fn in listeners:

event.listen(self, evt, fn)

self._prefixes = prefixes if prefixes else []

self._extra_kwargs(**kw)