diff options
Diffstat (limited to 'venv/lib/python3.11/site-packages/sqlalchemy/sql/events.py')
| -rw-r--r-- | venv/lib/python3.11/site-packages/sqlalchemy/sql/events.py | 455 |
1 files changed, 0 insertions, 455 deletions
diff --git a/venv/lib/python3.11/site-packages/sqlalchemy/sql/events.py b/venv/lib/python3.11/site-packages/sqlalchemy/sql/events.py deleted file mode 100644 index 1a6a9a6..0000000 --- a/venv/lib/python3.11/site-packages/sqlalchemy/sql/events.py +++ /dev/null @@ -1,455 +0,0 @@ -# sql/events.py -# Copyright (C) 2005-2024 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 - -from __future__ import annotations - -from typing import Any -from typing import TYPE_CHECKING - -from .base import SchemaEventTarget -from .. import event - -if TYPE_CHECKING: - from .schema import Column - from .schema import Constraint - from .schema import SchemaItem - from .schema import Table - from ..engine.base import Connection - from ..engine.interfaces import ReflectedColumn - from ..engine.reflection import Inspector - - -class DDLEvents(event.Events[SchemaEventTarget]): - """ - 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` - - """ - - _target_class_doc = "SomeSchemaClassOrObject" - _dispatch_target = SchemaEventTarget - - def before_create( - self, target: SchemaEventTarget, connection: Connection, **kw: Any - ) -> None: - r"""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. - - """ - - def after_create( - self, target: SchemaEventTarget, connection: Connection, **kw: Any - ) -> None: - r"""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. - - """ - - def before_drop( - self, target: SchemaEventTarget, connection: Connection, **kw: Any - ) -> None: - r"""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. - - """ - - def after_drop( - self, target: SchemaEventTarget, connection: Connection, **kw: Any - ) -> None: - r"""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. - - """ - - def before_parent_attach( - self, target: SchemaEventTarget, parent: SchemaItem - ) -> None: - """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. - - """ - - def after_parent_attach( - self, target: SchemaEventTarget, parent: SchemaItem - ) -> None: - """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. - - """ - - def _sa_event_column_added_to_pk_constraint( - self, const: Constraint, col: Column[Any] - ) -> None: - """internal event hook used for primary key naming convention - updates. - - """ - - def column_reflect( - self, inspector: Inspector, table: Table, column_info: ReflectedColumn - ) -> None: - """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 - - """ |