class_docstr: event interface for execution-replacement functions.
  
  These events allow direct instrumentation and replacement
  of key dialect functions which interact with the DBAPI.
  
  .. note::
  
      :class:`.DialectEvents` hooks should be considered **semi-public**
      and experimental.
      These hooks are not for general use and are only for those situations
      where intricate re-statement of DBAPI mechanics must be injected onto
      an existing dialect.  For general-use statement-interception events,
      please use the :class:`_events.ConnectionEvents` interface.
  
  .. seealso::
  
      :meth:`_events.ConnectionEvents.before_cursor_execute`
  
      :meth:`_events.ConnectionEvents.before_execute`
  
      :meth:`_events.ConnectionEvents.after_cursor_execute`
  
      :meth:`_events.ConnectionEvents.after_execute`
class_docstr_tok: ["event","interface","for","execution-replacement","functions",".","These","events","allow","direct","instrumentation","and","replacement","of","key","dialect","functions","which","interact","with","the","DBAPI",".","..","note",":",":",":","class",":","`",".DialectEvents","`","hooks","should","be","considered","*","*","semi-public","*","*","and","experimental",".","These","hooks","are","not","for","general","use","and","are","only","for","those","situations","where","intricate","re-statement","of","DBAPI","mechanics","must","be","injected","onto","an","existing","dialect",".","For","general-use","statement-interception","events",",","please","use","the",":","class",":","`","_events.ConnectionEvents","`","interface",".","..","seealso",":",":",":","meth",":","`","_events.ConnectionEvents.before_cursor_execute","`",":","meth",":","`","_events.ConnectionEvents.before_execute","`",":","meth",":","`","_events.ConnectionEvents.after_cursor_execute","`",":","meth",":","`","_events.ConnectionEvents.after_execute","`"]
docstr: Receive connection arguments before a connection is made.
  
  This event is useful in that it allows the handler to manipulate the
  cargs and/or cparams collections that control how the DBAPI
  ``connect()`` function will be called. ``cargs`` will always be a
  Python list that can be mutated in-place, and ``cparams`` a Python
  dictionary that may also be mutated::
  
      e = create_engine("postgresql+psycopg2://user@host/dbname")
  
      @event.listens_for(e, 'do_connect')
      def receive_do_connect(dialect, conn_rec, cargs, cparams):
          cparams["password"] = "some_password"
  
  The event hook may also be used to override the call to ``connect()``
  entirely, by returning a non-``None`` DBAPI connection object::
  
      e = create_engine("postgresql+psycopg2://user@host/dbname")
  
      @event.listens_for(e, 'do_connect')
      def receive_do_connect(dialect, conn_rec, cargs, cparams):
          return psycopg2.connect(*cargs, **cparams)
  
  .. seealso::
  
      :ref:`custom_dbapi_args`
docstr_tok: ["Receive","connection","arguments","before","a","connection","is","made",".","This","event","is","useful","in","that","it","allows","the","handler","to","manipulate","the","cargs","and\/or","cparams","collections","that","control","how","the","DBAPI","``","connect","(",")","``","function","will","be","called",".","``","cargs","``","will","always","be","a","Python","list","that","can","be","mutated","in-place",",","and","``","cparams","``","a","Python","dictionary","that","may","also","be","mutated",":",":","e","=","create_engine","(","``","postgresql+psycopg2",":","\/\/user","@","host\/dbname","''",")","@","event.listens_for","(","e",",","'do_connect","'",")","def","receive_do_connect","(","dialect",",","conn_rec",",","cargs",",","cparams",")",":","cparams","[","``","password","''","]","=","``","some_password","''","The","event","hook","may","also","be","used","to","override","the","call","to","``","connect","(",")","``","entirely",",","by","returning","a","non-","``","None","``","DBAPI","connection","object",":",":","e","=","create_engine","(","``","postgresql+psycopg2",":","\/\/user","@","host\/dbname","''",")","@","event.listens_for","(","e",",","'do_connect","'",")","def","receive_do_connect","(","dialect",",","conn_rec",",","cargs",",","cparams",")",":","return","psycopg2.connect","(","*","cargs",",","*","*","cparams",")","..","seealso",":",":",":","ref",":","`","custom_dbapi_args","`"]
code: def do_connect(
      self,
      dialect: Dialect,
      conn_rec: ConnectionPoolEntry,
      cargs: Tuple[Any, ...],
      cparams: Dict[str, Any],
  ) -> Optional[DBAPIConnection]:
      """Receive connection arguments before a connection is made.
  
      This event is useful in that it allows the handler to manipulate the
      cargs and/or cparams collections that control how the DBAPI
      ``connect()`` function will be called. ``cargs`` will always be a
      Python list that can be mutated in-place, and ``cparams`` a Python
      dictionary that may also be mutated::
  
          e = create_engine("postgresql+psycopg2://user@host/dbname")
  
          @event.listens_for(e, 'do_connect')
          def receive_do_connect(dialect, conn_rec, cargs, cparams):
              cparams["password"] = "some_password"
  
      The event hook may also be used to override the call to ``connect()``
      entirely, by returning a non-``None`` DBAPI connection object::
  
          e = create_engine("postgresql+psycopg2://user@host/dbname")
  
          @event.listens_for(e, 'do_connect')
          def receive_do_connect(dialect, conn_rec, cargs, cparams):
              return psycopg2.connect(*cargs, **cparams)
  
      .. seealso::
  
          :ref:`custom_dbapi_args`
  
      """
  
imports: from __future__ import annotations
  import typing
  from typing import Any
  from typing import Dict
  from typing import Optional
  from typing import Tuple
  from typing import Type
  from typing import Union
  from .base import Connection
  from .base import Engine
  from .interfaces import ConnectionEventsTarget
  from .interfaces import DBAPIConnection
  from .interfaces import DBAPICursor
  from .interfaces import Dialect
  from ..None import event
  from ..None import exc
  from ..util.typing import Literal
label_desc: Use image node_id 4 for calling the DialectEvents obj's underlying member method code with example usage: obj.do_connect(dialect, conn_rec, cargs, cparams) without return types