XylotrechusZ
�
Ȓ�g�G � �� � d dl mZ d dlmZ d dlmZ ddlmZ ddlmZ er*ddl m
Z
dd l m Z dd
l m Z dd l m
Z
dd lmZ dd
lmZ ddlmZ G d� dej( e � Zy)� )� annotations)�Any)�
TYPE_CHECKING� )�SchemaEventTarget� )�event)�Column)�
Constraint)�
SchemaItem)�Table)�
Connection)�ReflectedColumn)� Inspectorc �� � e Zd ZdZdZeZ d d�Z d d�Z d d�Z d d�Z
d
d�Z d
d�Z dd �Z
dd
�Zy )� DDLEventsa;
Define event listeners for schema objects,
that is, :class:`.SchemaItem` and other :class:`.SchemaEventTarget`
subclasses, including :class:`_schema.MetaData`, :class:`_schema.Table`,
:class:`_schema.Column`, etc.
**Create / Drop Events**
Events emitted when CREATE and DROP commands are emitted to the database.
The event hooks in this category include :meth:`.DDLEvents.before_create`,
:meth:`.DDLEvents.after_create`, :meth:`.DDLEvents.before_drop`, and
:meth:`.DDLEvents.after_drop`.
These events are emitted when using schema-level methods such as
:meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`. Per-object
create/drop methods such as :meth:`.Table.create`, :meth:`.Table.drop`,
:meth:`.Index.create` are also included, as well as dialect-specific
methods such as :meth:`_postgresql.ENUM.create`.
.. versionadded:: 2.0 :class:`.DDLEvents` event hooks now take place
for non-table objects including constraints, indexes, and
dialect-specific schema types.
Event hooks may be attached directly to a :class:`_schema.Table` object or
to a :class:`_schema.MetaData` collection, as well as to any
:class:`.SchemaItem` class or object that can be individually created and
dropped using a distinct SQL command. Such classes include :class:`.Index`,
:class:`.Sequence`, and dialect-specific classes such as
:class:`_postgresql.ENUM`.
Example using the :meth:`.DDLEvents.after_create` event, where a custom
event hook will emit an ``ALTER TABLE`` command on the current connection,
after ``CREATE TABLE`` is emitted::
from sqlalchemy import create_engine
from sqlalchemy import event
from sqlalchemy import Table, Column, Metadata, Integer
m = MetaData()
some_table = Table("some_table", m, Column("data", Integer))
@event.listens_for(some_table, "after_create")
def after_create(target, connection, **kw):
connection.execute(
text("ALTER TABLE %s SET name=foo_%s" % (target.name, target.name))
)
some_engine = create_engine("postgresql://scott:tiger@host/test")
# will emit "CREATE TABLE some_table" as well as the above
# "ALTER TABLE" statement afterwards
m.create_all(some_engine)
Constraint objects such as :class:`.ForeignKeyConstraint`,
:class:`.UniqueConstraint`, :class:`.CheckConstraint` may also be
subscribed to these events, however they will **not** normally produce
events as these objects are usually rendered inline within an
enclosing ``CREATE TABLE`` statement and implicitly dropped from a
``DROP TABLE`` statement.
For the :class:`.Index` construct, the event hook will be emitted
for ``CREATE INDEX``, however SQLAlchemy does not normally emit
``DROP INDEX`` when dropping tables as this is again implicit within the
``DROP TABLE`` statement.
.. versionadded:: 2.0 Support for :class:`.SchemaItem` objects
for create/drop events was expanded from its previous support for
:class:`.MetaData` and :class:`.Table` to also include
:class:`.Constraint` and all subclasses, :class:`.Index`,
:class:`.Sequence` and some type-related constructs such as
:class:`_postgresql.ENUM`.
.. note:: These event hooks are only emitted within the scope of
SQLAlchemy's create/drop methods; they are not necessarily supported
by tools such as `alembic <https://alembic.sqlalchemy.org>`_.
**Attachment Events**
Attachment events are provided to customize
behavior whenever a child schema element is associated
with a parent, such as when a :class:`_schema.Column` is associated
with its :class:`_schema.Table`, when a
:class:`_schema.ForeignKeyConstraint`
is associated with a :class:`_schema.Table`, etc. These events include
:meth:`.DDLEvents.before_parent_attach` and
:meth:`.DDLEvents.after_parent_attach`.
**Reflection Events**
The :meth:`.DDLEvents.column_reflect` event is used to intercept
and modify the in-Python definition of database columns when
:term:`reflection` of database tables proceeds.
**Use with Generic DDL**
DDL events integrate closely with the
:class:`.DDL` class and the :class:`.ExecutableDDLElement` hierarchy
of DDL clause constructs, which are themselves appropriate
as listener callables::
from sqlalchemy import DDL
event.listen(
some_table,
"after_create",
DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
)
**Event Propagation to MetaData Copies**
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.to_metadata`
method::
from sqlalchemy import DDL
metadata = MetaData()
some_table = Table("some_table", metadata, Column("data", Integer))
event.listen(
some_table,
"after_create",
DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
propagate=True,
)
new_metadata = MetaData()
new_table = some_table.to_metadata(new_metadata)
The above :class:`.DDL` object will be associated with the
:meth:`.DDLEvents.after_create` event for both the ``some_table`` and
the ``new_table`` :class:`.Table` objects.
.. seealso::
:ref:`event_toplevel`
:class:`.ExecutableDDLElement`
:class:`.DDL`
:ref:`schema_ddl_sequences`
�SomeSchemaClassOrObjectc � � y)a� Called before CREATE statements are emitted.
:param target: the :class:`.SchemaObject`, such as a
:class:`_schema.MetaData` or :class:`_schema.Table`
but also including all create/drop objects such as
:class:`.Index`, :class:`.Sequence`, etc.,
object which is the target of the event.
.. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
was added.
:param connection: the :class:`_engine.Connection` where the
CREATE statement or statements will be emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.
:func:`.event.listen` accepts the ``propagate=True``
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.to_metadata` is used.
:func:`.event.listen` accepts the ``insert=True``
modifier for this event; when True, the listener function will
be prepended to the internal list of events upon discovery, and execute
before registered listener functions that do not pass this argument.
N� ��self�target�
connection�kws �F/opt/hc_python/lib64/python3.12/site-packages/sqlalchemy/sql/events.py�
before_createzDDLEvents.before_create� � � � c � � y)a� Called after CREATE statements are emitted.
:param target: the :class:`.SchemaObject`, such as a
:class:`_schema.MetaData` or :class:`_schema.Table`
but also including all create/drop objects such as
:class:`.Index`, :class:`.Sequence`, etc.,
object which is the target of the event.
.. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
was added.
:param connection: the :class:`_engine.Connection` where the
CREATE statement or statements have been emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.
:func:`.event.listen` also accepts the ``propagate=True``
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.to_metadata` is used.
Nr r s r � after_createzDDLEvents.after_create� r r c � � y)a� Called before DROP statements are emitted.
:param target: the :class:`.SchemaObject`, such as a
:class:`_schema.MetaData` or :class:`_schema.Table`
but also including all create/drop objects such as
:class:`.Index`, :class:`.Sequence`, etc.,
object which is the target of the event.
.. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
was added.
:param connection: the :class:`_engine.Connection` where the
DROP statement or statements will be emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.
:func:`.event.listen` also accepts the ``propagate=True``
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.to_metadata` is used.
Nr r s r � before_dropzDDLEvents.before_drop� r r c � � y)a� Called after DROP statements are emitted.
:param target: the :class:`.SchemaObject`, such as a
:class:`_schema.MetaData` or :class:`_schema.Table`
but also including all create/drop objects such as
:class:`.Index`, :class:`.Sequence`, etc.,
object which is the target of the event.
.. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
was added.
:param connection: the :class:`_engine.Connection` where the
DROP statement or statements have been emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.
:func:`.event.listen` also accepts the ``propagate=True``
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.to_metadata` is used.
Nr r s r �
after_dropzDDLEvents.after_drop r r c � � y)a Called before a :class:`.SchemaItem` is associated with
a parent :class:`.SchemaItem`.
:param target: the target object
:param parent: the parent to which the target is being attached.
:func:`.event.listen` also accepts the ``propagate=True``
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.to_metadata` is used.
Nr �r r �parents r �before_parent_attachz DDLEvents.before_parent_attach4 r r c � � y)a
Called after a :class:`.SchemaItem` is associated with
a parent :class:`.SchemaItem`.
:param target: the target object
:param parent: the parent to which the target is being attached.
:func:`.event.listen` also accepts the ``propagate=True``
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.to_metadata` is used.
Nr r& s r �after_parent_attachz DDLEvents.after_parent_attachE r r c � � y)zUinternal event hook used for primary key naming convention
updates.
Nr )r �const�cols r �'_sa_event_column_added_to_pk_constraintz1DDLEvents._sa_event_column_added_to_pk_constraintV r r c � � y)a� Called for each unit of 'column info' retrieved when
a :class:`_schema.Table` is being reflected.
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
@event.listens_for(Table, "column_reflect")
def receive_column_reflect(inspector, table, column_info):
# receives for all Table objects that are reflected
...
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(
"my_table",
autoload_with=some_engine,
listeners=[("column_reflect", receive_column_reflect)],
)
The dictionary of column information as returned by the
dialect is passed, and can be modified. The dictionary
is that returned in each element of the list returned
by :meth:`.reflection.Inspector.get_columns`:
* ``name`` - the column's name, is applied to the
:paramref:`_schema.Column.name` parameter
* ``type`` - the type of this column, which should be an instance
of :class:`~sqlalchemy.types.TypeEngine`, is applied to the
:paramref:`_schema.Column.type` parameter
* ``nullable`` - boolean flag if the column is NULL or NOT NULL,
is applied to the :paramref:`_schema.Column.nullable` parameter
* ``default`` - the column's server default value. This is
normally specified as a plain string SQL expression, however the
event can pass a :class:`.FetchedValue`, :class:`.DefaultClause`,
or :func:`_expression.text` object as well. Is applied to the
:paramref:`_schema.Column.server_default` parameter
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
how the :class:`_schema.Column` is constructed:
* ``key`` - the string key that will be used to access this
:class:`_schema.Column` in the ``.c`` collection; will be applied
to the :paramref:`_schema.Column.key` parameter. Is also used
for ORM mapping. See the section
:ref:`mapper_automated_reflection_schemes` for an example.
* ``quote`` - force or un-force quoting on the column name;
is applied to the :paramref:`_schema.Column.quote` parameter.
* ``info`` - a dictionary of arbitrary data to follow along with
the :class:`_schema.Column`, is applied to the
:paramref:`_schema.Column.info` parameter.
:func:`.event.listen` also accepts the ``propagate=True``
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.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
:ref:`metadata_reflection_dbagnostic_types` - in
the :ref:`metadata_reflection_toplevel` documentation
Nr )r � inspector�table� column_infos r �column_reflectzDDLEvents.column_reflect^ r r N)r r r r r r �return�None)r r r' r r4 r5 )r, r r- z Column[Any]r4 r5 )r0 r r1 r
r2 r r4 r5 )�__name__�
__module__� __qualname__�__doc__�_target_class_docr �_dispatch_targetr r r" r$ r( r* r. r3 r r r r r s- � �S�j 2��(��" �'�" �5?�" �GJ�" �
�" �H �'� �5?� �GJ� �
� �> �'� �5?� �GJ� �
� �> �'� �5?� �GJ� �
� �> �'� �1;� �
� �" �'� �1;� �
� �" � � �&1� �
� �l �"�l �+0�l �?N�l �
�l r r N)�
__future__r �typingr r �baser � r �schemar
r r r
� engine.baser �engine.interfacesr �engine.reflectionr �Eventsr r r r �<module>rE sF �� #� � � #� �� �"�"� �(�3�-�p �� � � .�/� p r