Fixes: #2937

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

Change-Id: I7c1678488658edda3c5baaf0f7648108e93a4be1

1 files changed, 38 insertions, 20 deletions

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