Commits

Mike Bayer committed 009df6a

- 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.

  • Participants
  • Parent commits 043dc4a

Comments (0)

Files changed (6)

doc/build/changelog/changelog_09.rst

     :version: 0.9.4
 
     .. change::
-        :tags: enhancement, oracle
+        :tags: feature, orm
+
+        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.
+
+    .. change::
+        :tags: feature, oracle
         :tickets: 2911
         :pullreq: github:74
 

lib/sqlalchemy/engine/strategies.py

                 event.listen(pool, 'first_connect', on_connect)
                 event.listen(pool, 'connect', on_connect)
 
-            @util.only_once
             def first_connect(dbapi_connection, connection_record):
                 c = base.Connection(engine, connection=dbapi_connection,
                             _has_events=False)
 
                 dialect.initialize(c)
-            event.listen(pool, 'first_connect', first_connect)
+            event.listen(pool, 'first_connect', first_connect, once=True)
 
         return engine
 

lib/sqlalchemy/event/api.py

                 "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)
                 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)

lib/sqlalchemy/event/registry.py

 import weakref
 import collections
 import types
-from .. import exc
+from .. import exc, util
 
 
 _key_to_collection = collections.defaultdict(dict)
                 )
 
     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
         _stored_in_collection(self, owner)
         list_.insert(0, self._listen_fn)
 
+

lib/sqlalchemy/util/langhelpers.py

             once_fn = once.pop()
             return once_fn(*arg, **kw)
 
-    return update_wrapper(go, fn)
+    return go
 
 
 _SQLA_RE = re.compile(r'sqlalchemy/([a-z_]+/){0,2}[a-z_]+\.py')

test/base/test_events.py

         eq_(f1.mock.mock_calls, [call("x")])
         eq_(f2.mock.mock_calls, [call("x"), call("y")])
 
+    def test_once(self):
+        Target = self._fixture()
+
+        m1 = Mock()
+        m2 = Mock()
+        m3 = Mock()
+        m4 = Mock()
+
+        event.listen(Target, "event_one", m1)
+        event.listen(Target, "event_one", m2, once=True)
+        event.listen(Target, "event_one", m3, once=True)
+
+        t1 = Target()
+        t1.dispatch.event_one("x")
+        t1.dispatch.event_one("y")
+
+        event.listen(Target, "event_one", m4, once=True)
+        t1.dispatch.event_one("z")
+        t1.dispatch.event_one("q")
+
+        eq_(m1.mock_calls, [call("x"), call("y"), call("z"), call("q")])
+        eq_(m2.mock_calls, [call("x")])
+        eq_(m3.mock_calls, [call("x")])
+        eq_(m4.mock_calls, [call("z")])
+
     def test_propagate(self):
         Target = self._fixture()