Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/sqlalchemy/sql/events.py: 71%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# sql/events.py
2# Copyright (C) 2005-2024 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
8from __future__ import annotations
10from typing import Any
11from typing import TYPE_CHECKING
13from .base import SchemaEventTarget
14from .. import event
16if TYPE_CHECKING:
17 from .schema import Column
18 from .schema import Constraint
19 from .schema import SchemaItem
20 from .schema import Table
21 from ..engine.base import Connection
22 from ..engine.interfaces import ReflectedColumn
23 from ..engine.reflection import Inspector
26class DDLEvents(event.Events[SchemaEventTarget]):
27 """
28 Define event listeners for schema objects,
29 that is, :class:`.SchemaItem` and other :class:`.SchemaEventTarget`
30 subclasses, including :class:`_schema.MetaData`, :class:`_schema.Table`,
31 :class:`_schema.Column`, etc.
33 **Create / Drop Events**
35 Events emitted when CREATE and DROP commands are emitted to the database.
36 The event hooks in this category include :meth:`.DDLEvents.before_create`,
37 :meth:`.DDLEvents.after_create`, :meth:`.DDLEvents.before_drop`, and
38 :meth:`.DDLEvents.after_drop`.
40 These events are emitted when using schema-level methods such as
41 :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`. Per-object
42 create/drop methods such as :meth:`.Table.create`, :meth:`.Table.drop`,
43 :meth:`.Index.create` are also included, as well as dialect-specific
44 methods such as :meth:`_postgresql.ENUM.create`.
46 .. versionadded:: 2.0 :class:`.DDLEvents` event hooks now take place
47 for non-table objects including constraints, indexes, and
48 dialect-specific schema types.
50 Event hooks may be attached directly to a :class:`_schema.Table` object or
51 to a :class:`_schema.MetaData` collection, as well as to any
52 :class:`.SchemaItem` class or object that can be individually created and
53 dropped using a distinct SQL command. Such classes include :class:`.Index`,
54 :class:`.Sequence`, and dialect-specific classes such as
55 :class:`_postgresql.ENUM`.
57 Example using the :meth:`.DDLEvents.after_create` event, where a custom
58 event hook will emit an ``ALTER TABLE`` command on the current connection,
59 after ``CREATE TABLE`` is emitted::
61 from sqlalchemy import create_engine
62 from sqlalchemy import event
63 from sqlalchemy import Table, Column, Metadata, Integer
65 m = MetaData()
66 some_table = Table('some_table', m, Column('data', Integer))
68 @event.listens_for(some_table, "after_create")
69 def after_create(target, connection, **kw):
70 connection.execute(text(
71 "ALTER TABLE %s SET name=foo_%s" % (target.name, target.name)
72 ))
75 some_engine = create_engine("postgresql://scott:tiger@host/test")
77 # will emit "CREATE TABLE some_table" as well as the above
78 # "ALTER TABLE" statement afterwards
79 m.create_all(some_engine)
81 Constraint objects such as :class:`.ForeignKeyConstraint`,
82 :class:`.UniqueConstraint`, :class:`.CheckConstraint` may also be
83 subscribed to these events, however they will **not** normally produce
84 events as these objects are usually rendered inline within an
85 enclosing ``CREATE TABLE`` statement and implicitly dropped from a
86 ``DROP TABLE`` statement.
88 For the :class:`.Index` construct, the event hook will be emitted
89 for ``CREATE INDEX``, however SQLAlchemy does not normally emit
90 ``DROP INDEX`` when dropping tables as this is again implicit within the
91 ``DROP TABLE`` statement.
93 .. versionadded:: 2.0 Support for :class:`.SchemaItem` objects
94 for create/drop events was expanded from its previous support for
95 :class:`.MetaData` and :class:`.Table` to also include
96 :class:`.Constraint` and all subclasses, :class:`.Index`,
97 :class:`.Sequence` and some type-related constructs such as
98 :class:`_postgresql.ENUM`.
100 .. note:: These event hooks are only emitted within the scope of
101 SQLAlchemy's create/drop methods; they are not necessarily supported
102 by tools such as `alembic <https://alembic.sqlalchemy.org>`_.
105 **Attachment Events**
107 Attachment events are provided to customize
108 behavior whenever a child schema element is associated
109 with a parent, such as when a :class:`_schema.Column` is associated
110 with its :class:`_schema.Table`, when a
111 :class:`_schema.ForeignKeyConstraint`
112 is associated with a :class:`_schema.Table`, etc. These events include
113 :meth:`.DDLEvents.before_parent_attach` and
114 :meth:`.DDLEvents.after_parent_attach`.
116 **Reflection Events**
118 The :meth:`.DDLEvents.column_reflect` event is used to intercept
119 and modify the in-Python definition of database columns when
120 :term:`reflection` of database tables proceeds.
122 **Use with Generic DDL**
124 DDL events integrate closely with the
125 :class:`.DDL` class and the :class:`.ExecutableDDLElement` hierarchy
126 of DDL clause constructs, which are themselves appropriate
127 as listener callables::
129 from sqlalchemy import DDL
130 event.listen(
131 some_table,
132 "after_create",
133 DDL("ALTER TABLE %(table)s SET name=foo_%(table)s")
134 )
136 **Event Propagation to MetaData Copies**
138 For all :class:`.DDLEvent` events, the ``propagate=True`` keyword argument
139 will ensure that a given event handler is propagated to copies of the
140 object, which are made when using the :meth:`_schema.Table.to_metadata`
141 method::
143 from sqlalchemy import DDL
145 metadata = MetaData()
146 some_table = Table("some_table", metadata, Column("data", Integer))
148 event.listen(
149 some_table,
150 "after_create",
151 DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
152 propagate=True
153 )
155 new_metadata = MetaData()
156 new_table = some_table.to_metadata(new_metadata)
158 The above :class:`.DDL` object will be associated with the
159 :meth:`.DDLEvents.after_create` event for both the ``some_table`` and
160 the ``new_table`` :class:`.Table` objects.
162 .. seealso::
164 :ref:`event_toplevel`
166 :class:`.ExecutableDDLElement`
168 :class:`.DDL`
170 :ref:`schema_ddl_sequences`
172 """
174 _target_class_doc = "SomeSchemaClassOrObject"
175 _dispatch_target = SchemaEventTarget
177 def before_create(
178 self, target: SchemaEventTarget, connection: Connection, **kw: Any
179 ) -> None:
180 r"""Called before CREATE statements are emitted.
182 :param target: the :class:`.SchemaObject`, such as a
183 :class:`_schema.MetaData` or :class:`_schema.Table`
184 but also including all create/drop objects such as
185 :class:`.Index`, :class:`.Sequence`, etc.,
186 object which is the target of the event.
188 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
189 was added.
191 :param connection: the :class:`_engine.Connection` where the
192 CREATE statement or statements will be emitted.
193 :param \**kw: additional keyword arguments relevant
194 to the event. The contents of this dictionary
195 may vary across releases, and include the
196 list of tables being generated for a metadata-level
197 event, the checkfirst flag, and other
198 elements used by internal events.
200 :func:`.event.listen` accepts the ``propagate=True``
201 modifier for this event; when True, the listener function will
202 be established for any copies made of the target object,
203 i.e. those copies that are generated when
204 :meth:`_schema.Table.to_metadata` is used.
206 :func:`.event.listen` accepts the ``insert=True``
207 modifier for this event; when True, the listener function will
208 be prepended to the internal list of events upon discovery, and execute
209 before registered listener functions that do not pass this argument.
211 """
213 def after_create(
214 self, target: SchemaEventTarget, connection: Connection, **kw: Any
215 ) -> None:
216 r"""Called after CREATE statements are emitted.
218 :param target: the :class:`.SchemaObject`, such as a
219 :class:`_schema.MetaData` or :class:`_schema.Table`
220 but also including all create/drop objects such as
221 :class:`.Index`, :class:`.Sequence`, etc.,
222 object which is the target of the event.
224 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
225 was added.
227 :param connection: the :class:`_engine.Connection` where the
228 CREATE statement or statements have been emitted.
229 :param \**kw: additional keyword arguments relevant
230 to the event. The contents of this dictionary
231 may vary across releases, and include the
232 list of tables being generated for a metadata-level
233 event, the checkfirst flag, and other
234 elements used by internal events.
236 :func:`.event.listen` also accepts the ``propagate=True``
237 modifier for this event; when True, the listener function will
238 be established for any copies made of the target object,
239 i.e. those copies that are generated when
240 :meth:`_schema.Table.to_metadata` is used.
242 """
244 def before_drop(
245 self, target: SchemaEventTarget, connection: Connection, **kw: Any
246 ) -> None:
247 r"""Called before DROP statements are emitted.
249 :param target: the :class:`.SchemaObject`, such as a
250 :class:`_schema.MetaData` or :class:`_schema.Table`
251 but also including all create/drop objects such as
252 :class:`.Index`, :class:`.Sequence`, etc.,
253 object which is the target of the event.
255 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
256 was added.
258 :param connection: the :class:`_engine.Connection` where the
259 DROP statement or statements will be emitted.
260 :param \**kw: additional keyword arguments relevant
261 to the event. The contents of this dictionary
262 may vary across releases, and include the
263 list of tables being generated for a metadata-level
264 event, the checkfirst flag, and other
265 elements used by internal events.
267 :func:`.event.listen` also accepts the ``propagate=True``
268 modifier for this event; when True, the listener function will
269 be established for any copies made of the target object,
270 i.e. those copies that are generated when
271 :meth:`_schema.Table.to_metadata` is used.
273 """
275 def after_drop(
276 self, target: SchemaEventTarget, connection: Connection, **kw: Any
277 ) -> None:
278 r"""Called after DROP statements are emitted.
280 :param target: the :class:`.SchemaObject`, such as a
281 :class:`_schema.MetaData` or :class:`_schema.Table`
282 but also including all create/drop objects such as
283 :class:`.Index`, :class:`.Sequence`, etc.,
284 object which is the target of the event.
286 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects
287 was added.
289 :param connection: the :class:`_engine.Connection` where the
290 DROP statement or statements have been emitted.
291 :param \**kw: additional keyword arguments relevant
292 to the event. The contents of this dictionary
293 may vary across releases, and include the
294 list of tables being generated for a metadata-level
295 event, the checkfirst flag, and other
296 elements used by internal events.
298 :func:`.event.listen` also accepts the ``propagate=True``
299 modifier for this event; when True, the listener function will
300 be established for any copies made of the target object,
301 i.e. those copies that are generated when
302 :meth:`_schema.Table.to_metadata` is used.
304 """
306 def before_parent_attach(
307 self, target: SchemaEventTarget, parent: SchemaItem
308 ) -> None:
309 """Called before a :class:`.SchemaItem` is associated with
310 a parent :class:`.SchemaItem`.
312 :param target: the target object
313 :param parent: the parent to which the target is being attached.
315 :func:`.event.listen` also accepts the ``propagate=True``
316 modifier for this event; when True, the listener function will
317 be established for any copies made of the target object,
318 i.e. those copies that are generated when
319 :meth:`_schema.Table.to_metadata` is used.
321 """
323 def after_parent_attach(
324 self, target: SchemaEventTarget, parent: SchemaItem
325 ) -> None:
326 """Called after a :class:`.SchemaItem` is associated with
327 a parent :class:`.SchemaItem`.
329 :param target: the target object
330 :param parent: the parent to which the target is being attached.
332 :func:`.event.listen` also accepts the ``propagate=True``
333 modifier for this event; when True, the listener function will
334 be established for any copies made of the target object,
335 i.e. those copies that are generated when
336 :meth:`_schema.Table.to_metadata` is used.
338 """
340 def _sa_event_column_added_to_pk_constraint(
341 self, const: Constraint, col: Column[Any]
342 ) -> None:
343 """internal event hook used for primary key naming convention
344 updates.
346 """
348 def column_reflect(
349 self, inspector: Inspector, table: Table, column_info: ReflectedColumn
350 ) -> None:
351 """Called for each unit of 'column info' retrieved when
352 a :class:`_schema.Table` is being reflected.
354 This event is most easily used by applying it to a specific
355 :class:`_schema.MetaData` instance, where it will take effect for
356 all :class:`_schema.Table` objects within that
357 :class:`_schema.MetaData` that undergo reflection::
359 metadata = MetaData()
361 @event.listens_for(metadata, 'column_reflect')
362 def receive_column_reflect(inspector, table, column_info):
363 # receives for all Table objects that are reflected
364 # under this MetaData
367 # will use the above event hook
368 my_table = Table("my_table", metadata, autoload_with=some_engine)
371 .. versionadded:: 1.4.0b2 The :meth:`_events.DDLEvents.column_reflect`
372 hook may now be applied to a :class:`_schema.MetaData` object as
373 well as the :class:`_schema.MetaData` class itself where it will
374 take place for all :class:`_schema.Table` objects associated with
375 the targeted :class:`_schema.MetaData`.
377 It may also be applied to the :class:`_schema.Table` class across
378 the board::
380 from sqlalchemy import Table
382 @event.listens_for(Table, 'column_reflect')
383 def receive_column_reflect(inspector, table, column_info):
384 # receives for all Table objects that are reflected
386 It can also be applied to a specific :class:`_schema.Table` at the
387 point that one is being reflected using the
388 :paramref:`_schema.Table.listeners` parameter::
390 t1 = Table(
391 "my_table",
392 autoload_with=some_engine,
393 listeners=[
394 ('column_reflect', receive_column_reflect)
395 ]
396 )
398 The dictionary of column information as returned by the
399 dialect is passed, and can be modified. The dictionary
400 is that returned in each element of the list returned
401 by :meth:`.reflection.Inspector.get_columns`:
403 * ``name`` - the column's name, is applied to the
404 :paramref:`_schema.Column.name` parameter
406 * ``type`` - the type of this column, which should be an instance
407 of :class:`~sqlalchemy.types.TypeEngine`, is applied to the
408 :paramref:`_schema.Column.type` parameter
410 * ``nullable`` - boolean flag if the column is NULL or NOT NULL,
411 is applied to the :paramref:`_schema.Column.nullable` parameter
413 * ``default`` - the column's server default value. This is
414 normally specified as a plain string SQL expression, however the
415 event can pass a :class:`.FetchedValue`, :class:`.DefaultClause`,
416 or :func:`_expression.text` object as well. Is applied to the
417 :paramref:`_schema.Column.server_default` parameter
419 The event is called before any action is taken against
420 this dictionary, and the contents can be modified; the following
421 additional keys may be added to the dictionary to further modify
422 how the :class:`_schema.Column` is constructed:
425 * ``key`` - the string key that will be used to access this
426 :class:`_schema.Column` in the ``.c`` collection; will be applied
427 to the :paramref:`_schema.Column.key` parameter. Is also used
428 for ORM mapping. See the section
429 :ref:`mapper_automated_reflection_schemes` for an example.
431 * ``quote`` - force or un-force quoting on the column name;
432 is applied to the :paramref:`_schema.Column.quote` parameter.
434 * ``info`` - a dictionary of arbitrary data to follow along with
435 the :class:`_schema.Column`, is applied to the
436 :paramref:`_schema.Column.info` parameter.
438 :func:`.event.listen` also accepts the ``propagate=True``
439 modifier for this event; when True, the listener function will
440 be established for any copies made of the target object,
441 i.e. those copies that are generated when
442 :meth:`_schema.Table.to_metadata` is used.
444 .. seealso::
446 :ref:`mapper_automated_reflection_schemes` -
447 in the ORM mapping documentation
449 :ref:`automap_intercepting_columns` -
450 in the :ref:`automap_toplevel` documentation
452 :ref:`metadata_reflection_dbagnostic_types` - in
453 the :ref:`metadata_reflection_toplevel` documentation
455 """