Fixes: #2937

* docs for event listen kwargs
* docs for mysql to use `listen` for changing the sql_mode`

Change-Id: I7c1678488658edda3c5baaf0f7648108e93a4be1

diff --git a/doc/build/conf.py b/doc/build/conf.py
index 5c2ece7aaa72316a4a53f23e375742aeea80f7da..8e2182848079518f5146485bf39974bf3699eb10 100644 (file)
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -157,7 +157,7 @@ zzzeeksphinx_module_prefixes = {
     "_reflection": "sqlalchemy.engine.reflection",
     "_orm": "sqlalchemy.orm",
     "_query": "sqlalchemy.orm",
-    "_ormevent": "sqlalchemy.orm.event",
+    "_ormevent": "sqlalchemy.orm.events",
     "_ormexc": "sqlalchemy.orm.exc",
     "_roles": "sqlalchemy.sql.roles",
     "_baked": "sqlalchemy.ext.baked",

diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst
index 4ec42008e226f2e9d5bf607f00a97e49fc261475..af4e33ba9a5c3558256c5a9b2f7595daa04c5305 100644 (file)
--- a/doc/build/core/event.rst
+++ b/doc/build/core/event.rst
@@ -39,6 +39,8 @@ To listen with the :func:`.listens_for` decorator looks like::
     def my_on_connect(dbapi_con, connection_record):
         print("New DBAPI connection:", dbapi_con)
 
+.. _event_named_argument_styles:
+
 Named Argument Styles
 ---------------------
 
@@ -112,6 +114,9 @@ and objects::
     # associate listener with my_engine.pool
     listen(my_engine, 'connect', my_on_connect)
 
+
+.. _event_modifiers:
+
 Modifiers
 ---------
 

diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index 2bba2f81a7249980748bccf376d1a90900ce35f0..0c24ebf5e7b2b10c4959fe7331e6fe62489a5ec5 100644 (file)
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -400,13 +400,47 @@ ANSI Quoting Style
 MySQL / MariaDB feature two varieties of identifier "quoting style", one using
 backticks and the other using quotes, e.g. ```some_identifier```  vs.
 ``"some_identifier"``.   All MySQL dialects detect which version
-is in use by checking the value of ``sql_mode`` when a connection is first
+is in use by checking the value of :ref:`sql_mode<mysql_sql_mode>` when a connection is first
 established with a particular :class:`_engine.Engine`.
 This quoting style comes
 into play when rendering table and column names as well as when reflecting
 existing database structures.  The detection is entirely automatic and
 no special configuration is needed to use either quoting style.
 
+
+.. _mysql_sql_mode:
+
+Changing the sql_mode
+---------------------
+
+MySQL supports operating in multiple
+`Server SQL Modes <https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html>`_  for
+both Servers and Clients. To change the ``sql_mode`` for a given application, a
+developer can leverage SQLAlchemy's Events system.
+
+In the following example, the event system is used to set the ``sql_mode`` on
+the ``first_connect`` and ``connect`` events::
+
+    from sqlalchemy import create_engine, event
+
+    eng = create_engine("mysql://scott:tiger@localhost/test", echo='debug')
+
+    # `insert=True` will ensure this is the very first listener to run
+    @event.listens_for(eng, "connect", insert=True)
+    def connect(dbapi_connection, connection_record):
+        cursor = dbapi_connection.cursor()
+        cursor.execute("SET sql_mode = 'STRICT_ALL_TABLES'")
+
+    conn = eng.connect()
+
+In the example illustrated above, the "connect" event will invoke the "SET"
+statement on the connection at the moment a particular DBAPI connection is
+first created for a given Pool, before the connection is made available to the
+connection pool.  Additionally, because the function was registered with
+``insert=True``, it will be prepended to the internal list of registered
+functions.
+
+
 MySQL / MariaDB SQL Extensions
 ------------------------------
 

diff --git a/lib/sqlalchemy/event/api.py b/lib/sqlalchemy/event/api.py
index 5a01c4b02e55662d21cfc8a5b8ef29b353796782..5487c9f1afe380d32ba8a3ba2a327343b9e36865 100644 (file)
--- a/lib/sqlalchemy/event/api.py
+++ b/lib/sqlalchemy/event/api.py
@@ -52,21 +52,42 @@ def listen(target, identifier, fn, *args, **kw):
                 "after_parent_attach",
                 unique_constraint_name)
 
-
-    A given function can also be invoked for only the first invocation
-    of the event using the ``once`` argument::
-
-        def on_config():
-            do_config()
-
-        event.listen(Mapper, "before_configure", on_config, once=True)
-
-    .. warning:: The ``once`` argument does not imply automatic de-registration
-       of the listener function after it has been invoked a first time; a
-       listener entry will remain associated with the target object.
-       Associating an arbitrarily high number of listeners without explicitly
-       removing them will cause memory to grow unbounded even if ``once=True``
-       is specified.
+    :param bool insert: The default behavior for event handlers is to append
+      the decorated user defined function to an internal list of registered
+      event listeners upon discovery. If a user registers a function with
+      ``insert=True``, SQLAlchemy will insert (prepend) the function to the
+      internal list upon discovery. This feature is not typically used or
+      recommended by the SQLAlchemy maintainers, but is provided to ensure
+      certain user defined functions can run before others, such as when
+      :ref:`Changing the sql_mode in MySQL <mysql_sql_mode>`.
+
+    :param bool named: When using named argument passing, the names listed in
+      the function argument specification will be used as keys in the
+      dictionary.
+      See :ref:`event_named_argument_styles`.
+
+    :param bool once: Private/Internal API usage. Deprecated.  This parameter
+      would provide that an event function would run only once per given
+      target. It does not however imply automatic de-registration of the
+      listener function; associating an arbitrarily high number of listeners
+      without explicitly removing them will cause memory to grow unbounded even
+      if ``once=True`` is specified.
+
+    :param bool propagate: The ``propagate`` kwarg is available when working
+      with ORM instrumentation and mapping events.
+      See :class:`_ormevent.MapperEvents` and
+      :meth:`_ormevent.MapperEvents.before_mapper_configured` for examples.
+
+    :param bool retval: This flag applies only to specific event listeners,
+      each of which includes documentation explaining when it should be used.
+      By default, no listener ever requires a return value.
+      However, some listeners do support special behaviors for return values,
+      and include in their documentation that the ``retval=True`` flag is
+      necessary for a return value to be processed.
+
+      Event listener suites that make use of :paramref:`_event.listen.retval`
+      include :class:`_events.ConnectionEvents` and
+      :class:`_ormevent.AttributeEvents`.
 
     .. note::
 
@@ -83,11 +104,6 @@ def listen(target, identifier, fn, *args, **kw):
         events at high scale, use a mutable structure that is handled
         from inside of a single listener.
 
-        .. versionchanged:: 1.0.0 - a ``collections.deque()`` object is now
-           used as the container for the list of events, which explicitly
-           disallows collection mutation while the collection is being
-           iterated.
-
     .. seealso::
 
         :func:`.listens_for`
@@ -105,6 +121,8 @@ def listens_for(target, identifier, *args, **kw):
     The :func:`.listens_for` decorator is part of the primary interface for the
     SQLAlchemy event system, documented at :ref:`event_toplevel`.
 
+    This function generally shares the same kwargs as :func:`.listens`.
+
     e.g.::
 
         from sqlalchemy import event