Fixes: #2937

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

Change-Id: I7c1678488658edda3c5baaf0f7648108e93a4be1

2 files changed, 73 insertions, 21 deletions

diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index 2bba2f81a..0c24ebf5e 100644
--- 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 5a01c4b02..5487c9f1a 100644
--- 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