- Added a new keyword argument ``once=True`` to :func:`.event.listen`

and :func:`.event.listens_for`.  This is a convenience feature which
will wrap the given listener such that it is only invoked once.

2 files changed, 31 insertions, 2 deletions

diff --git a/lib/sqlalchemy/event/api.py b/lib/sqlalchemy/event/api.py
index 20e74d90e..b27ce7993 100644
--- a/lib/sqlalchemy/event/api.py
+++ b/lib/sqlalchemy/event/api.py
@@ -44,6 +44,18 @@ 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)
+
+    .. versionadded:: 0.9.3 Added ``once=True`` to :func:`.event.listen`
+       and :func:`.event.listens_for`.
+
     """
 
     _event_key(target, identifier, fn).listen(*args, **kw)
@@ -63,6 +75,18 @@ def listens_for(target, identifier, *args, **kw):
                 table.name,
                 list(const.columns)[0].name
             )
+
+    A given function can also be invoked for only the first invocation
+    of the event using the ``once`` argument::
+
+        @event.listens_for(Mapper, "before_configure", once=True)
+        def on_config():
+            do_config()
+
+
+    .. versionadded:: 0.9.3 Added ``once=True`` to :func:`.event.listen`
+       and :func:`.event.listens_for`.
+
     """
     def decorate(fn):
         listen(target, identifier, fn, *args, **kw)
diff --git a/lib/sqlalchemy/event/registry.py b/lib/sqlalchemy/event/registry.py
index 7710ff2d2..6f3eb3e85 100644
--- a/lib/sqlalchemy/event/registry.py
+++ b/lib/sqlalchemy/event/registry.py
@@ -19,7 +19,7 @@ from __future__ import absolute_import
 import weakref
 import collections
 import types
-from .. import exc
+from .. import exc, util
 
 
 _key_to_collection = collections.defaultdict(dict)
@@ -173,7 +173,11 @@ class _EventKey(object):
                 )
 
     def listen(self, *args, **kw):
-        self.dispatch_target.dispatch._listen(self, *args, **kw)
+        once = kw.pop("once", False)
+        if once:
+            self.with_wrapper(util.only_once(self._listen_fn)).listen(*args, **kw)
+        else:
+            self.dispatch_target.dispatch._listen(self, *args, **kw)
 
     def remove(self):
         key = self._key
@@ -234,3 +238,4 @@ class _EventKey(object):
         _stored_in_collection(self, owner)
         list_.insert(0, self._listen_fn)
 
+