codekingpro/portable-devtools

1�

2��jRI�
���SS
KJ
r
 SSKJr SSKJr SSKJr SSKJr \(a*SSK	J3r4 SS	K	Jr SS5K	Jr SSK	J
r
 SSKJr SS
KJr SSKJr "SS\R(\5rg)�)
�annotations)
�Any)
�
TYPE_CHECKING�
)
�SchemaEventTarget�)
�event)
�Column)
�6Constraint)
�7SchemaItem)
�Table)
�8Connection)
�ReflectedColumn)
�	Inspectorc
���\r
SrS
rSrSr\rSSjrSSjr	SSjr9SSjrSSjrSS	jr
SS10jrSSjrSrg
)�	DDLEvents�a�11Define event listeners for schema objects,12that is, :class:`.SchemaItem` and other :class:`.SchemaEventTarget`13subclasses, including :class:`_schema.MetaData`, :class:`_schema.Table`,14:class:`_schema.Column`, etc.15 16**Create / Drop Events**17 18Events emitted when CREATE and DROP commands are emitted to the database.19The event hooks in this category include :meth:`.DDLEvents.before_create`,20:meth:`.DDLEvents.after_create`, :meth:`.DDLEvents.before_drop`, and21:meth:`.DDLEvents.after_drop`.22 23These events are emitted when using schema-level methods such as24:meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`. Per-object25create/drop methods such as :meth:`.Table.create`, :meth:`.Table.drop`,26:meth:`.Index.create` are also included, as well as dialect-specific27methods such as :meth:`_postgresql.ENUM.create`.28 29.. versionadded:: 2.0 :class:`.DDLEvents` event hooks now take place30   for non-table objects including constraints, indexes, and31   dialect-specific schema types.32 33Event hooks may be attached directly to a :class:`_schema.Table` object or34to a :class:`_schema.MetaData` collection, as well as to any35:class:`.SchemaItem` class or object that can be individually created and36dropped using a distinct SQL command. Such classes include :class:`.Index`,37:class:`.Sequence`, and dialect-specific classes such as38:class:`_postgresql.ENUM`.39 40Example using the :meth:`.DDLEvents.after_create` event, where a custom41event hook will emit an ``ALTER TABLE`` command on the current connection,42after ``CREATE TABLE`` is emitted::43 44    from sqlalchemy import create_engine45    from sqlalchemy import event46    from sqlalchemy import Table, Column, Metadata, Integer47 48    m = MetaData()49    some_table = Table("some_table", m, Column("data", Integer))50 51 52    @event.listens_for(some_table, "after_create")53    def after_create(target, connection, **kw):54        connection.execute(55            text("ALTER TABLE %s SET name=foo_%s" % (target.name, target.name))56        )57 58 59    some_engine = create_engine("postgresql://scott:tiger@host/test")60 61    # will emit "CREATE TABLE some_table" as well as the above62    # "ALTER TABLE" statement afterwards63    m.create_all(some_engine)64 65Constraint objects such as :class:`.ForeignKeyConstraint`,66:class:`.UniqueConstraint`, :class:`.CheckConstraint` may also be67subscribed to these events, however they will **not** normally produce68events as these objects are usually rendered inline within an69enclosing ``CREATE TABLE`` statement and implicitly dropped from a70``DROP TABLE`` statement.71 72For the :class:`.Index` construct, the event hook will be emitted73for ``CREATE INDEX``, however SQLAlchemy does not normally emit74``DROP INDEX`` when dropping tables as this is again implicit within the75``DROP TABLE`` statement.76 77.. versionadded:: 2.0 Support for :class:`.SchemaItem` objects78   for create/drop events was expanded from its previous support for79   :class:`.MetaData` and :class:`.Table` to also include80   :class:`.Constraint` and all subclasses, :class:`.Index`,81   :class:`.Sequence` and some type-related constructs such as82   :class:`_postgresql.ENUM`.83 84.. note:: These event hooks are only emitted within the scope of85   SQLAlchemy's create/drop methods; they are not necessarily supported86   by tools such as `alembic <https://alembic.sqlalchemy.org>`_.87 88 89**Attachment Events**90 91Attachment events are provided to customize92behavior whenever a child schema element is associated93with a parent, such as when a :class:`_schema.Column` is associated94with its :class:`_schema.Table`, when a95:class:`_schema.ForeignKeyConstraint`96is associated with a :class:`_schema.Table`, etc.  These events include97:meth:`.DDLEvents.before_parent_attach` and98:meth:`.DDLEvents.after_parent_attach`.99 100**Reflection Events**101 102The :meth:`.DDLEvents.column_reflect` event is used to intercept103and modify the in-Python definition of database columns when104:term:`reflection` of database tables proceeds.105 106**Use with Generic DDL**107 108DDL events integrate closely with the109:class:`.DDL` class and the :class:`.ExecutableDDLElement` hierarchy110of DDL clause constructs, which are themselves appropriate111as listener callables::112 113    from sqlalchemy import DDL114 115    event.listen(116        some_table,117        "after_create",118        DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),119    )120 121**Event Propagation to MetaData Copies**122 123For all :class:`.DDLEvent` events, the ``propagate=True`` keyword argument124will ensure that a given event handler is propagated to copies of the125object, which are made when using the :meth:`_schema.Table.to_metadata`126method::127 128    from sqlalchemy import DDL129 130    metadata = MetaData()131    some_table = Table("some_table", metadata, Column("data", Integer))132 133    event.listen(134        some_table,135        "after_create",136        DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),137        propagate=True,138    )139 140    new_metadata = MetaData()141    new_table = some_table.to_metadata(new_metadata)142 143The above :class:`.DDL` object will be associated with the144:meth:`.DDLEvents.after_create` event for both the ``some_table`` and145the ``new_table`` :class:`.Table` objects.146 147.. seealso::148 149    :ref:`event_toplevel`150 151    :class:`.ExecutableDDLElement`152 153    :class:`.DDL`154 155    :ref:`schema_ddl_sequences`156 157�SomeSchemaClassOrObjectc

��g
)a�Called before CREATE statements are emitted.158 159:param target: the :class:`.SchemaObject`, such as a160 :class:`_schema.MetaData` or :class:`_schema.Table`161 but also including all create/drop objects such as162 :class:`.Index`, :class:`.Sequence`, etc.,163 object which is the target of the event.164 165 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects166    was added.167 168:param connection: the :class:`_engine.Connection` where the169 CREATE statement or statements will be emitted.170:param \**kw: additional keyword arguments relevant171 to the event.  The contents of this dictionary172 may vary across releases, and include the173 list of tables being generated for a metadata-level174 event, the checkfirst flag, and other175 elements used by internal events.176 177:func:`.event.listen` accepts the ``propagate=True``178modifier for this event; when True, the listener function will179be established for any copies made of the target object,180i.e. those copies that are generated when181:meth:`_schema.Table.to_metadata` is used.182 183:func:`.event.listen` accepts the ``insert=True``184modifier for this event; when True, the listener function will185be prepended to the internal list of events upon discovery, and execute186before registered listener functions that do not pass this argument.187 188N���self�target�189connection�kws    �[D:\code\apps\devtools\python\user_packages\Python313\site-packages\sqlalchemy/sql/events.py�
before_create�DDLEvents.before_create����c

��g
)a�Called after CREATE statements are emitted.190 191:param target: the :class:`.SchemaObject`, such as a192 :class:`_schema.MetaData` or :class:`_schema.Table`193 but also including all create/drop objects such as194 :class:`.Index`, :class:`.Sequence`, etc.,195 object which is the target of the event.196 197 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects198    was added.199 200:param connection: the :class:`_engine.Connection` where the201 CREATE statement or statements have been emitted.202:param \**kw: additional keyword arguments relevant203 to the event.  The contents of this dictionary204 may vary across releases, and include the205 list of tables being generated for a metadata-level206 event, the checkfirst flag, and other207 elements used by internal events.208 209:func:`.event.listen` also accepts the ``propagate=True``210modifier for this event; when True, the listener function will211be established for any copies made of the target object,212i.e. those copies that are generated when213:meth:`_schema.Table.to_metadata` is used.214 215Nrrs    r�after_create�DDLEvents.after_create�rr c

��g
)a�Called before DROP statements are emitted.216 217:param target: the :class:`.SchemaObject`, such as a218 :class:`_schema.MetaData` or :class:`_schema.Table`219 but also including all create/drop objects such as220 :class:`.Index`, :class:`.Sequence`, etc.,221 object which is the target of the event.222 223 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects224    was added.225 226:param connection: the :class:`_engine.Connection` where the227 DROP statement or statements will be emitted.228:param \**kw: additional keyword arguments relevant229 to the event.  The contents of this dictionary230 may vary across releases, and include the231 list of tables being generated for a metadata-level232 event, the checkfirst flag, and other233 elements used by internal events.234 235:func:`.event.listen` also accepts the ``propagate=True``236modifier for this event; when True, the listener function will237be established for any copies made of the target object,238i.e. those copies that are generated when239:meth:`_schema.Table.to_metadata` is used.240 241Nrrs    r�before_drop�DDLEvents.before_drop�rr c

��g
)a�Called after DROP statements are emitted.242 243:param target: the :class:`.SchemaObject`, such as a244 :class:`_schema.MetaData` or :class:`_schema.Table`245 but also including all create/drop objects such as246 :class:`.Index`, :class:`.Sequence`, etc.,247 object which is the target of the event.248 249 .. versionadded:: 2.0 Support for all :class:`.SchemaItem` objects250    was added.251 252:param connection: the :class:`_engine.Connection` where the253 DROP statement or statements have been emitted.254:param \**kw: additional keyword arguments relevant255 to the event.  The contents of this dictionary256 may vary across releases, and include the257 list of tables being generated for a metadata-level258 event, the checkfirst flag, and other259 elements used by internal events.260 261:func:`.event.listen` also accepts the ``propagate=True``262modifier for this event; when True, the listener function will263be established for any copies made of the target object,264i.e. those copies that are generated when265:meth:`_schema.Table.to_metadata` is used.266 267Nrrs    r�268after_drop�DDLEvents.after_drop
rr c

��g
)a�
Called before a :class:`.SchemaItem` is associated with269a parent :class:`.SchemaItem`.270 271:param target: the target object272:param parent: the parent to which the target is being attached.273 274:func:`.event.listen` also accepts the ``propagate=True``275modifier for this event; when True, the listener function will276be established for any copies made of the target object,277i.e. those copies that are generated when278:meth:`_schema.Table.to_metadata` is used.279 280Nr�rr�parents   r�before_parent_attach�DDLEvents.before_parent_attach4
rr c

��g
)a�
Called after a :class:`.SchemaItem` is associated with281a parent :class:`.SchemaItem`.282 283:param target: the target object284:param parent: the parent to which the target is being attached.285 286:func:`.event.listen` also accepts the ``propagate=True``287modifier for this event; when True, the listener function will288be established for any copies made of the target object,289i.e. those copies that are generated when290:meth:`_schema.Table.to_metadata` is used.291 292Nrr+s   r�after_parent_attach�DDLEvents.after_parent_attachE
rr c

��g
)zEinternal event hook used for primary key naming convention293updates.294 295Nr)r�const�cols   r�'_sa_event_column_added_to_pk_constraint�1DDLEvents._sa_event_column_added_to_pk_constraintV
rr c

��g
)a�Called for each unit of 'column info' retrieved when296a :class:`_schema.Table` is being reflected.297 298This event is most easily used by applying it to a specific299:class:`_schema.MetaData` instance, where it will take effect for300all :class:`_schema.Table` objects within that301:class:`_schema.MetaData` that undergo reflection::302 303    metadata = MetaData()304 305 306    @event.listens_for(metadata, "column_reflect")307    def receive_column_reflect(inspector, table, column_info):308        # receives for all Table objects that are reflected309        # under this MetaData310        ...311 312 313    # will use the above event hook314    my_table = Table("my_table", metadata, autoload_with=some_engine)315 316.. versionadded:: 1.4.0b2 The :meth:`_events.DDLEvents.column_reflect`317   hook may now be applied to a :class:`_schema.MetaData` object as318   well as the :class:`_schema.MetaData` class itself where it will319   take place for all :class:`_schema.Table` objects associated with320   the targeted :class:`_schema.MetaData`.321 322It may also be applied to the :class:`_schema.Table` class across323the board::324 325    from sqlalchemy import Table326 327 328    @event.listens_for(Table, "column_reflect")329    def receive_column_reflect(inspector, table, column_info):330        # receives for all Table objects that are reflected331        ...332 333It can also be applied to a specific :class:`_schema.Table` at the334point that one is being reflected using the335:paramref:`_schema.Table.listeners` parameter::336 337    t1 = Table(338        "my_table",339        autoload_with=some_engine,340        listeners=[("column_reflect", receive_column_reflect)],341    )342 343The dictionary of column information as returned by the344dialect is passed, and can be modified.  The dictionary345is that returned in each element of the list returned346by :meth:`.reflection.Inspector.get_columns`:347 348    * ``name`` - the column's name, is applied to the349      :paramref:`_schema.Column.name` parameter350 351    * ``type`` - the type of this column, which should be an instance352      of :class:`~sqlalchemy.types.TypeEngine`, is applied to the353      :paramref:`_schema.Column.type` parameter354 355    * ``nullable`` - boolean flag if the column is NULL or NOT NULL,356      is applied to the :paramref:`_schema.Column.nullable` parameter357 358    * ``default`` - the column's server default value.  This is359      normally specified as a plain string SQL expression, however the360      event can pass a :class:`.FetchedValue`, :class:`.DefaultClause`,361      or :func:`_expression.text` object as well.  Is applied to the362      :paramref:`_schema.Column.server_default` parameter363 364The event is called before any action is taken against365this dictionary, and the contents can be modified; the following366additional keys may be added to the dictionary to further modify367how the :class:`_schema.Column` is constructed:368 369 370    * ``key`` - the string key that will be used to access this371      :class:`_schema.Column` in the ``.c`` collection; will be applied372      to the :paramref:`_schema.Column.key` parameter. Is also used373      for ORM mapping.  See the section374      :ref:`mapper_automated_reflection_schemes` for an example.375 376    * ``quote`` - force or un-force quoting on the column name;377      is applied to the :paramref:`_schema.Column.quote` parameter.378 379    * ``info`` - a dictionary of arbitrary data to follow along with380      the :class:`_schema.Column`, is applied to the381      :paramref:`_schema.Column.info` parameter.382 383:func:`.event.listen` also accepts the ``propagate=True``384modifier for this event; when True, the listener function will385be established for any copies made of the target object,386i.e. those copies that are generated when387:meth:`_schema.Table.to_metadata` is used.388 389.. seealso::390 391    :ref:`mapper_automated_reflection_schemes` -392    in the ORM mapping documentation393 394    :ref:`automap_intercepting_columns` -395    in the :ref:`automap_toplevel` documentation396 397    :ref:`metadata_reflection_dbagnostic_types` - in398    the :ref:`metadata_reflection_toplevel` documentation399 400Nr)r�	inspector�table�column_infos    r�column_reflect�DDLEvents.column_reflect^
rr rN)rrrrrr�return�None)rrr,rr=r>)r3rr4zColumn[Any]r=r>)r8rr9r
r:rr=r>)�__name__�401__module__�__qualname__�__firstlineno__�__doc__�_target_class_docr�_dispatch_targetrr"r%r(r-r0r5r;�__static_attributes__rr rrrs-
��S�j2��(��"�'�"�5?�"�GJ�"�	
�"�H
�'��5?��GJ��	
��>�'��5?��GJ��	
��>�'��5?��GJ��	
��>�'��1;��	
��"�'��1;��	
��"���&1��	
��l
�"�l
�+0�l
�?N�l
�	
�l
r rN)�402__future__r�typingrr�baser�r	�schemar403rrr
�engine.baser�engine.interfacesr�engine.reflectionr�Eventsrrr r�<module>rP
sF�


�
#�� �#����"�"��(�3�-�p
����.�/�p
r