HEX

File: //usr/local/lib/python3.10/dist-packages/sqlalchemy/pool/__pycache__/events.cpython-310.pyc

���g]3�@s�ddlmZddlZddlmZddlmZddlmZddlmZddlmZdd lm Z dd
lm
Z
ddlmZdd
lm
Z
ddlmZejrUddlmZddlmZGdd�de
je �ZdS)�)�annotationsN)�Any)�Optional)�Type)�Union�)�ConnectionPoolEntry)�Pool)�PoolProxiedConnection)�PoolResetState�)�event)�util)�Engine)�DBAPIConnectionc@s�eZdZdZdZeZe�d�e d6d
d���Z
e d7dd��Zd8dd�Zd8dd�Z
d9dd�Zd:d d!�Ze�d"ddgd#d$��d;d'd(��Zd<d+d,�Zd<d-d.�Zd8d/d0�Zd8d1d2�Zd=d3d4�Zd5S)>�
PoolEventsa�Available events for :class:`_pool.Pool`.

The methods here define the name of an event as well
as the names of members that are passed to listener
functions.

e.g.::

from sqlalchemy import event

def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
"handle an on checkout event"

event.listen(Pool, "checkout", my_on_checkout)

In addition to accepting the :class:`_pool.Pool` class and
:class:`_pool.Pool` instances, :class:`_events.PoolEvents` also accepts
:class:`_engine.Engine` objects and the :class:`_engine.Engine` class as
targets, which will be resolved to the ``.pool`` attribute of the
given engine or the :class:`_pool.Pool` class::

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")

# will associate with engine.pool
event.listen(engine, "checkout", my_on_checkout)

�SomeEngineOrPoolzsqlalchemy.engine�target�-Union[Pool, Type[Pool], Engine, Type[Engine]]�
identifier�str�return�!Optional[Union[Pool, Type[Pool]]]cCsrtjstjjj}t|t�rt||�rt St|t �sJ�|St||�r%|j
St|t �r,|St|d�r7|��dSdS)N�_no_async_engine_events)
�typing�
TYPE_CHECKINGr� preloaded�enginer�
isinstance�type�
issubclassr �pool�hasattrr)�clsrrr�r$�A/usr/local/lib/python3.10/dist-packages/sqlalchemy/pool/events.py�_accept_with=s

zPoolEvents._accept_with� event_key�event._EventKey[Pool]�kwr�NonecKs(|j}|�d|j�|jdi|��dS)N�asyncior$)�dispatch_target�
setdefault�_is_asyncio�base_listen)r#r'r)rr$r$r%�_listenVszPoolEvents._listen�dbapi_connectionr�connection_recordrcC�dS)aCalled at the moment a particular DBAPI connection is first
created for a given :class:`_pool.Pool`.

This event allows one to capture the point directly after which
the DBAPI module-level ``.connect()`` method has been used in order
to produce a new DBAPI connection.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

Nr$��selfr1r2r$r$r%�connectb�zPoolEvents.connectcCr3)a)Called exactly once for the first time a DBAPI connection is
checked out from a particular :class:`_pool.Pool`.

The rationale for :meth:`_events.PoolEvents.first_connect`
is to determine
information about a particular series of database connections based
on the settings used for all connections. Since a particular
:class:`_pool.Pool`
refers to a single "creator" function (which in terms
of a :class:`_engine.Engine`
refers to the URL and connection options used),
it is typically valid to make observations about a single connection
that can be safely assumed to be valid about all subsequent
connections, such as the database version, the server and client
encoding settings, collation settings, and many others.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

Nr$r4r$r$r%�
first_connectvr7zPoolEvents.first_connect�connection_proxyr
cCr3)a�Called when a connection is retrieved from the Pool.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

:param connection_proxy: the :class:`.PoolProxiedConnection` object
which will proxy the public interface of the DBAPI connection for the
lifespan of the checkout.

If you raise a :class:`~sqlalchemy.exc.DisconnectionError`, the current
connection will be disposed and a fresh connection retrieved.
Processing of all checkout listeners will abort and restart
using the new connection.

.. seealso:: :meth:`_events.ConnectionEvents.engine_connect`
- a similar event
which occurs upon creation of a new :class:`_engine.Connection`.

Nr$)r5r1r2r9r$r$r%�checkout�r7zPoolEvents.checkout�Optional[DBAPIConnection]cCr3)a�Called when a connection returns to the pool.

Note that the connection may be closed, and may be None if the
connection has been invalidated. ``checkin`` will not be called
for detached connections. (They do not return to the pool.)

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

Nr$r4r$r$r%�checkin�r7zPoolEvents.checkinz2.0cCs||fS)Nr$)r1r2�reset_stater$r$r%�<lambda>�s�zPoolEvents.<lambda>r=rcCr3)a�Called before the "reset" action occurs for a pooled connection.

This event represents
when the ``rollback()`` method is called on the DBAPI connection
before it is returned to the pool or discarded.
A custom "reset" strategy may be implemented using this event hook,
which may also be combined with disabling the default "reset"
behavior using the :paramref:`_pool.Pool.reset_on_return` parameter.

The primary difference between the :meth:`_events.PoolEvents.reset` and
:meth:`_events.PoolEvents.checkin` events are that
:meth:`_events.PoolEvents.reset` is called not just for pooled
connections that are being returned to the pool, but also for
connections that were detached using the
:meth:`_engine.Connection.detach` method as well as asyncio connections
that are being discarded due to garbage collection taking place on
connections before the connection was checked in.

Note that the event **is not** invoked for connections that were
invalidated using :meth:`_engine.Connection.invalidate`. These
events may be intercepted using the :meth:`.PoolEvents.soft_invalidate`
and :meth:`.PoolEvents.invalidate` event hooks, and all "connection
close" events may be intercepted using :meth:`.PoolEvents.close`.

The :meth:`_events.PoolEvents.reset` event is usually followed by the
:meth:`_events.PoolEvents.checkin` event, except in those
cases where the connection is discarded immediately after reset.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

:param reset_state: :class:`.PoolResetState` instance which provides
information about the circumstances under which the connection
is being reset.

.. versionadded:: 2.0

.. seealso::

:ref:`pool_reset_on_return`

:meth:`_events.ConnectionEvents.rollback`

:meth:`_events.ConnectionEvents.commit`

Nr$)r5r1r2r=r$r$r%�reset�r7zPoolEvents.reset� exception�Optional[BaseException]cCr3)a!Called when a DBAPI connection is to be "invalidated".

This event is called any time the
:meth:`.ConnectionPoolEntry.invalidate` method is invoked, either from
API usage or via "auto-invalidation", without the ``soft`` flag.

The event occurs before a final attempt to call ``.close()`` on the
connection occurs.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

:param exception: the exception object corresponding to the reason
for this invalidation, if any. May be ``None``.

.. seealso::

:ref:`pool_connection_invalidation`

Nr$�r5r1r2r@r$r$r%�
invalidater7zPoolEvents.invalidatecCr3)aNCalled when a DBAPI connection is to be "soft invalidated".

This event is called any time the
:meth:`.ConnectionPoolEntry.invalidate`
method is invoked with the ``soft`` flag.

Soft invalidation refers to when the connection record that tracks
this connection will force a reconnect after the current connection
is checked in. It does not actively close the dbapi_connection
at the point at which it is called.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

:param exception: the exception object corresponding to the reason
for this invalidation, if any. May be ``None``.

Nr$rBr$r$r%�soft_invalidate!r7zPoolEvents.soft_invalidatecCr3)a�Called when a DBAPI connection is closed.

The event is emitted before the close occurs.

The close of a connection can fail; typically this is because
the connection is already closed. If the close operation fails,
the connection is discarded.

The :meth:`.close` event corresponds to a connection that's still
associated with the pool. To intercept close events for detached
connections use :meth:`.close_detached`.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

Nr$r4r$r$r%�close=r7zPoolEvents.closecCr3)a�Called when a DBAPI connection is "detached" from a pool.

This event is emitted after the detach occurs. The connection
is no longer associated with the given connection record.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

:param connection_record: the :class:`.ConnectionPoolEntry` managing
the DBAPI connection.

Nr$r4r$r$r%�detachVr7zPoolEvents.detachcCr3)a�Called when a detached DBAPI connection is closed.

The event is emitted before the close occurs.

The close of a connection can fail; typically this is because
the connection is already closed. If the close operation fails,
the connection is discarded.

:param dbapi_connection: a DBAPI connection.
The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.

Nr$)r5r1r$r$r%�close_detachedhr7zPoolEvents.close_detachedN)rrrrrr)r'r(r)rrr*)r1rr2rrr*)r1rr2rr9r
rr*)r1r;r2rrr*)r1rr2rr=rrr*)r1rr2rr@rArr*)r1rrr*)�__name__�
__module__�__qualname__�__doc__�_target_class_docr �_dispatch_targetr�preload_module�classmethodr&r0r6r8r:r<r
�_legacy_signaturer?rCrDrErFrGr$r$r$r%rs0

�
8

r)�
__future__rrrrrr�baserr r
r�r
rrrr�engine.interfacesr�Eventsrr$r$r$r%�<module>s