- move deprecated interfaces down to bottom of TOC, update verbiage

- more docs for engine, pool, DDL events
- update DDL sequences documentation to use events
- update DDL() docstring to refer to execute_if()
- document parameters for DDLElement.execute_if()
- add retval=True flag to Engine.on_before_execute(), on_before_cursor_execute().
wrap the function if retval=False, check for appropriate usage of the flag, add
tests.
- remove ScopedSession.mapper and tests entirely
- remove ExtensionCarrier and tests
- change remaining tests that use MapperExtension to use MapperEvents

6 files changed, 73 insertions, 287 deletions

diff --git a/test/engine/test_execute.py b/test/engine/test_execute.py
index 86764f170..5e6656431 100644
--- a/test/engine/test_execute.py
+++ b/test/engine/test_execute.py
@@ -377,12 +377,12 @@ class EngineEventsTest(TestBase):
             self._assert_stmts(cursor, cursor_stmts)
 
     def test_options(self):
-        track = []
+        canary = []
         def on_execute(conn, *args, **kw):
-            track.append('execute')
+            canary.append('execute')
             
         def on_cursor_execute(conn, *args, **kw):
-            track.append('cursor_execute')
+            canary.append('cursor_execute')
             
         engine = engines.testing_engine()
         event.listen(on_execute, 'on_before_execute', engine)
@@ -393,14 +393,45 @@ class EngineEventsTest(TestBase):
         c2.execute(select([1]))
         c3 = c2.execution_options(bar='bat')
         eq_(c3._execution_options, {'foo':'bar', 'bar':'bat'})
-        eq_(track, ['execute', 'cursor_execute'])
+        eq_(canary, ['execute', 'cursor_execute'])
 
+    def test_retval_flag(self):
+        canary = []
+        def tracker(name):
+            def go(conn, *args, **kw):
+                canary.append(name)
+            return go
 
+        def on_execute(conn, clauseelement, multiparams, params):
+            canary.append('execute')
+            return clauseelement, multiparams, params
+            
+        def on_cursor_execute(conn, cursor, statement, 
+                        parameters, context, executemany):
+            canary.append('cursor_execute')
+            return statement, parameters
+            
+        engine = engines.testing_engine()
+        
+        assert_raises(
+            tsa.exc.ArgumentError,
+            event.listen, tracker("on_begin"), "on_begin", engine, retval=True
+        )
+        
+        event.listen(on_execute, "on_before_execute", engine, retval=True)
+        event.listen(on_cursor_execute, "on_before_cursor_execute", engine, retval=True)
+        engine.execute("select 1")
+        eq_(
+            canary, ['execute', 'cursor_execute']
+        )
+        
+        
+        
     def test_transactional(self):
-        track = []
+        canary = []
         def tracker(name):
             def go(conn, *args, **kw):
-                track.append(name)
+                canary.append(name)
             return go
             
         engine = engines.testing_engine()
@@ -418,7 +449,7 @@ class EngineEventsTest(TestBase):
         conn.execute(select([1]))
         trans.commit()
 
-        eq_(track, [
+        eq_(canary, [
             'begin', 'execute', 'cursor_execute', 'rollback',
             'begin', 'execute', 'cursor_execute', 'commit',
             ])
@@ -426,10 +457,10 @@ class EngineEventsTest(TestBase):
     @testing.requires.savepoints
     @testing.requires.two_phase_transactions
     def test_transactional_advanced(self):
-        track = []
+        canary = []
         def tracker(name):
             def go(conn, exec_, *args, **kw):
-                track.append(name)
+                canary.append(name)
                 return exec_(*args, **kw)
             return go
             
@@ -456,7 +487,7 @@ class EngineEventsTest(TestBase):
         trans.prepare()
         trans.commit()
 
-        eq_(track, ['begin', 'savepoint', 
+        eq_(canary, ['begin', 'savepoint', 
                     'rollback_savepoint', 'savepoint', 'release_savepoint',
                     'rollback', 'begin_twophase', 
                        'prepare_twophase', 'commit_twophase']
@@ -569,12 +600,12 @@ class ProxyConnectionTest(TestBase):
     
     @testing.uses_deprecated(r'.*Use event.listen')
     def test_options(self):
-        track = []
+        canary = []
         class TrackProxy(ConnectionProxy):
             def __getattribute__(self, key):
                 fn = object.__getattribute__(self, key)
                 def go(*arg, **kw):
-                    track.append(fn.__name__)
+                    canary.append(fn.__name__)
                     return fn(*arg, **kw)
                 return go
         engine = engines.testing_engine(options={'proxy':TrackProxy()})
@@ -584,17 +615,17 @@ class ProxyConnectionTest(TestBase):
         c2.execute(select([1]))
         c3 = c2.execution_options(bar='bat')
         eq_(c3._execution_options, {'foo':'bar', 'bar':'bat'})
-        eq_(track, ['execute', 'cursor_execute'])
+        eq_(canary, ['execute', 'cursor_execute'])
         
         
     @testing.uses_deprecated(r'.*Use event.listen')
     def test_transactional(self):
-        track = []
+        canary = []
         class TrackProxy(ConnectionProxy):
             def __getattribute__(self, key):
                 fn = object.__getattribute__(self, key)
                 def go(*arg, **kw):
-                    track.append(fn.__name__)
+                    canary.append(fn.__name__)
                     return fn(*arg, **kw)
                 return go
 
@@ -607,7 +638,7 @@ class ProxyConnectionTest(TestBase):
         conn.execute(select([1]))
         trans.commit()
         
-        eq_(track, [
+        eq_(canary, [
             'begin', 'execute', 'cursor_execute', 'rollback',
             'begin', 'execute', 'cursor_execute', 'commit',
             ])
@@ -616,12 +647,12 @@ class ProxyConnectionTest(TestBase):
     @testing.requires.savepoints
     @testing.requires.two_phase_transactions
     def test_transactional_advanced(self):
-        track = []
+        canary = []
         class TrackProxy(ConnectionProxy):
             def __getattribute__(self, key):
                 fn = object.__getattribute__(self, key)
                 def go(*arg, **kw):
-                    track.append(fn.__name__)
+                    canary.append(fn.__name__)
                     return fn(*arg, **kw)
                 return go
 
@@ -642,8 +673,8 @@ class ProxyConnectionTest(TestBase):
         trans.prepare()
         trans.commit()
 
-        track = [t for t in track if t not in ('cursor_execute', 'execute')]
-        eq_(track, ['begin', 'savepoint', 
+        canary = [t for t in canary if t not in ('cursor_execute', 'execute')]
+        eq_(canary, ['begin', 'savepoint', 
                     'rollback_savepoint', 'savepoint', 'release_savepoint',
                     'rollback', 'begin_twophase', 
                        'prepare_twophase', 'commit_twophase']
diff --git a/test/orm/test_defaults.py b/test/orm/test_defaults.py
index 9be8e6e56..389fdbc5c 100644
--- a/test/orm/test_defaults.py
+++ b/test/orm/test_defaults.py
@@ -1,7 +1,7 @@
 
 import sqlalchemy as sa
 from sqlalchemy.test import testing
-from sqlalchemy import Integer, String, ForeignKey
+from sqlalchemy import Integer, String, ForeignKey, event
 from sqlalchemy.test.schema import Table, Column
 from sqlalchemy.orm import mapper, relationship, create_session
 from test.orm import _base
@@ -46,9 +46,9 @@ class TriggerDefaultsTest(_base.MappedTest):
                                 bind.engine.name not in ('oracle', 'mssql', 'sqlite')
                 ),
             ):
-            ins.execute_at('after-create', dt)
-            
-        sa.DDL("DROP TRIGGER dt_ins").execute_at('before-drop', dt)
+            event.listen(ins, 'on_after_create', dt)
+        
+        event.listen(sa.DDL("DROP TRIGGER dt_ins"), 'on_before_drop', dt)
 
         for up in (
             sa.DDL("CREATE TRIGGER dt_up AFTER UPDATE ON dt "
@@ -71,9 +71,9 @@ class TriggerDefaultsTest(_base.MappedTest):
                                 bind.engine.name not in ('oracle', 'mssql', 'sqlite')
                     ),
             ):
-            up.execute_at('after-create', dt)
+            event.listen(up, 'on_after_create', dt)
 
-        sa.DDL("DROP TRIGGER dt_up").execute_at('before-drop', dt)
+        event.listen(sa.DDL("DROP TRIGGER dt_up"), 'on_before_drop', dt)
 
 
     @classmethod
diff --git a/test/orm/test_mapper.py b/test/orm/test_mapper.py
index 9c73a7225..93cacb9f6 100644
--- a/test/orm/test_mapper.py
+++ b/test/orm/test_mapper.py
@@ -179,53 +179,9 @@ class MapperTest(_fixtures.FixtureTest):
                               : addresses.c.user_id})
         
     @testing.resolve_artifact_names
-    def test_bad_constructor(self):
-        """If the construction of a mapped class fails, the instance does not get placed in the session"""
-        
-        class Foo(object):
-            def __init__(self, one, two, _sa_session=None):
-                pass
-
-        mapper(Foo, users, extension=sa.orm.scoped_session(
-            create_session).extension)
-
-        sess = create_session()
-        assert_raises(TypeError, Foo, 'one', _sa_session=sess)
-        eq_(len(list(sess)), 0)
-        assert_raises(TypeError, Foo, 'one')
-        Foo('one', 'two', _sa_session=sess)
-        eq_(len(list(sess)), 1)
-
-    @testing.resolve_artifact_names
-    def test_constructor_exc_1(self):
-        """Exceptions raised in the mapped class are not masked by sa decorations"""
-        
-        ex = AssertionError('oops')
-        sess = create_session()
-
-        class Foo(object):
-            def __init__(self, **kw):
-                raise ex
-        mapper(Foo, users)
-
-        try:
-            Foo()
-            assert False
-        except Exception, e:
-            assert e is ex
-
-        sa.orm.clear_mappers()
-        mapper(Foo, users, extension=sa.orm.scoped_session(
-            create_session).extension)
-        def bad_expunge(foo):
-            raise Exception("this exception should be stated as a warning")
-
-        sess.expunge = bad_expunge
-        assert_raises(sa.exc.SAWarning, Foo, _sa_session=sess)
-
-    @testing.resolve_artifact_names
-    def test_constructor_exc_2(self):
-        """TypeError is raised for illegal constructor args, whether or not explicit __init__ is present [ticket:908]."""
+    def test_constructor_exc(self):
+        """TypeError is raised for illegal constructor args, 
+        whether or not explicit __init__ is present [ticket:908]."""
 
         class Foo(object):
             def __init__(self):
diff --git a/test/orm/test_scoping.py b/test/orm/test_scoping.py
index 1682e0f7e..fa1777c85 100644
--- a/test/orm/test_scoping.py
+++ b/test/orm/test_scoping.py
@@ -92,179 +92,5 @@ class ScopedSessionTest(_base.MappedTest):
             Session.configure, bind=testing.db
         )
         
-class ScopedMapperTest(_ScopedTest):
-
-    @classmethod
-    def define_tables(cls, metadata):
-        Table('table1', metadata,
-            Column('id', Integer, primary_key=True, test_needs_autoincrement=True),
-            Column('data', String(30)))
-        Table('table2', metadata,
-            Column('id', Integer, primary_key=True, test_needs_autoincrement=True),
-            Column('someid', None, ForeignKey('table1.id')))
-
-    @classmethod
-    def setup_classes(cls):
-        class SomeObject(_base.ComparableEntity):
-            pass
-        class SomeOtherObject(_base.ComparableEntity):
-            pass
-
-    @classmethod
-    @testing.uses_deprecated()
-    @testing.resolve_artifact_names
-    def setup_mappers(cls):
-        Session = scoped_session(sa.orm.create_session)
-        Session.mapper(SomeObject, table1, properties={
-            'options':relationship(SomeOtherObject)
-        })
-        Session.mapper(SomeOtherObject, table2)
-
-        cls.scoping['Session'] = Session
-
-    @classmethod
-    @testing.resolve_artifact_names
-    def insert_data(cls):
-        s = SomeObject()
-        s.id = 1
-        s.data = 'hello'
-        sso = SomeOtherObject()
-        s.options.append(sso)
-        Session.flush()
-        Session.expunge_all()
-
-    @testing.resolve_artifact_names
-    def test_query(self):
-        sso = SomeOtherObject.query().first()
-        assert SomeObject.query.filter_by(id=1).one().options[0].id == sso.id
-
-    @testing.uses_deprecated()
-    @testing.resolve_artifact_names
-    def test_query_compiles(self):
-        class Foo(object):
-            pass
-        Session.mapper(Foo, table2)
-        assert hasattr(Foo, 'query')
-
-        ext = sa.orm.MapperExtension()
-
-        class Bar(object):
-            pass
-        Session.mapper(Bar, table2, extension=[ext])
-        assert hasattr(Bar, 'query')
-
-        class Baz(object):
-            pass
-        Session.mapper(Baz, table2, extension=ext)
-        assert hasattr(Baz, 'query')
-
-    @testing.uses_deprecated()
-    @testing.resolve_artifact_names
-    def test_default_constructor_state_not_shared(self):
-        scope = scoped_session(sa.orm.sessionmaker())
-
-        class A(object):
-            pass
-        class B(object):
-            def __init__(self):
-                pass
-
-        scope.mapper(A, table1)
-        scope.mapper(B, table2)
-
-        A(foo='bar')
-        assert_raises(TypeError, B, foo='bar')
-
-        scope = scoped_session(sa.orm.sessionmaker())
-
-        class C(object):
-            def __init__(self):
-                pass
-        class D(object):
-            pass
-
-        scope.mapper(C, table1)
-        scope.mapper(D, table2)
-
-        assert_raises(TypeError, C, foo='bar')
-        D(foo='bar')
-
-    @testing.uses_deprecated()
-    @testing.resolve_artifact_names
-    def test_validating_constructor(self):
-        s2 = SomeObject(someid=12)
-        s3 = SomeOtherObject(someid=123, bogus=345)
-
-        class ValidatedOtherObject(object): pass
-        Session.mapper(ValidatedOtherObject, table2, validate=True)
-
-        v1 = ValidatedOtherObject(someid=12)
-        assert_raises(sa.exc.ArgumentError, ValidatedOtherObject,
-                          someid=12, bogus=345)
-
-    @testing.uses_deprecated()
-    @testing.resolve_artifact_names
-    def test_dont_clobber_methods(self):
-        class MyClass(object):
-            def expunge(self):
-                return "an expunge !"
-
-        Session.mapper(MyClass, table2)
-
-        assert MyClass().expunge() == "an expunge !"
-
-
-class ScopedMapperTest2(_ScopedTest):
-
-    @classmethod
-    def define_tables(cls, metadata):
-        Table('table1', metadata,
-            Column('id', Integer, primary_key=True, test_needs_autoincrement=True),
-            Column('data', String(30)),
-            Column('type', String(30)))
-        Table('table2', metadata,
-            Column('id', Integer, primary_key=True, test_needs_autoincrement=True),
-            Column('someid', None, ForeignKey('table1.id')),
-            Column('somedata', String(30)))
-
-    @classmethod
-    def setup_classes(cls):
-        class BaseClass(_base.ComparableEntity):
-            pass
-        class SubClass(BaseClass):
-            pass
-
-    @classmethod
-    @testing.uses_deprecated()
-    @testing.resolve_artifact_names
-    def setup_mappers(cls):
-        Session = scoped_session(sa.orm.sessionmaker())
-
-        Session.mapper(BaseClass, table1,
-                       polymorphic_identity='base',
-                       polymorphic_on=table1.c.type)
-        Session.mapper(SubClass, table2,
-                       polymorphic_identity='sub',
-                       inherits=BaseClass)
-
-        cls.scoping['Session'] = Session
-
-    @testing.resolve_artifact_names
-    def test_inheritance(self):
-        def expunge_list(l):
-            for x in l:
-                Session.expunge(x)
-            return l
-
-        b = BaseClass(data='b1')
-        s =  SubClass(data='s1', somedata='somedata')
-        Session.commit()
-        Session.expunge_all()
-
-        eq_(expunge_list([BaseClass(data='b1'),
-                          SubClass(data='s1', somedata='somedata')]),
-            BaseClass.query.all())
-        eq_(expunge_list([SubClass(data='s1', somedata='somedata')]),
-            SubClass.query.all())
 
 
diff --git a/test/orm/test_unitofwork.py b/test/orm/test_unitofwork.py
index d93f11f92..e437cd024 100644
--- a/test/orm/test_unitofwork.py
+++ b/test/orm/test_unitofwork.py
@@ -8,7 +8,7 @@ from sqlalchemy.orm import mapper as orm_mapper
 
 import sqlalchemy as sa
 from sqlalchemy.test import engines, testing, pickleable
-from sqlalchemy import Integer, String, ForeignKey, literal_column
+from sqlalchemy import Integer, String, ForeignKey, literal_column, event
 from sqlalchemy.test.schema import Table
 from sqlalchemy.test.schema import Column
 from sqlalchemy.orm import mapper, relationship, create_session, \
@@ -1590,14 +1590,19 @@ class SaveTest(_fixtures.FixtureTest):
         """The 'batch=False' flag on mapper()"""
 
         names = []
-        class TestExtension(sa.orm.MapperExtension):
+        class Events(object):
             def before_insert(self, mapper, connection, instance):
                 self.current_instance = instance
                 names.append(instance.name)
             def after_insert(self, mapper, connection, instance):
                 assert instance is self.current_instance
 
-        mapper(User, users, extension=TestExtension(), batch=False)
+        mapper(User, users, batch=False)
+        
+        evt = Events()
+        event.listen(evt.before_insert, "on_before_insert", User)
+        event.listen(evt.after_insert, "on_after_insert", User)
+        
         u1 = User(name='user1')
         u2 = User(name='user2')
 
@@ -1618,7 +1623,11 @@ class SaveTest(_fixtures.FixtureTest):
         
         sa.orm.clear_mappers()
 
-        m = mapper(User, users, extension=TestExtension())
+        m = mapper(User, users)
+        evt = Events()
+        event.listen(evt.before_insert, "on_before_insert", User)
+        event.listen(evt.after_insert, "on_after_insert", User)
+
         u1 = User(name='user1')
         u2 = User(name='user2')
         session.add_all((u1, u2))
diff --git a/test/orm/test_utils.py b/test/orm/test_utils.py
index 8635ad212..43a15056c 100644
--- a/test/orm/test_utils.py
+++ b/test/orm/test_utils.py
@@ -14,42 +14,6 @@ from test.orm import _fixtures
 from sqlalchemy.test.testing import eq_
 
 
-class ExtensionCarrierTest(TestBase):
-    def test_basic(self):
-        carrier = util.ExtensionCarrier()
-
-        assert 'translate_row' not in carrier
-        assert carrier.translate_row() is interfaces.EXT_CONTINUE
-        assert 'translate_row' not in carrier
-
-        assert_raises(AttributeError, lambda: carrier.snickysnack)
-
-        class Partial(object):
-            def __init__(self, marker):
-                self.marker = marker
-            def translate_row(self, row):
-                return self.marker
-
-        carrier.append(Partial('end'))
-        assert 'translate_row' in carrier
-        assert carrier.translate_row(None) == 'end'
-
-        carrier.push(Partial('front'))
-        assert carrier.translate_row(None) == 'front'
-
-        assert 'populate_instance' not in carrier
-        carrier.append(interfaces.MapperExtension)
-        
-        # Py3K
-        #assert 'populate_instance' not in carrier
-        # Py2K
-        assert 'populate_instance' in carrier
-        # end Py2K
-        
-        assert carrier.interface
-        for m in carrier.interface:
-            assert getattr(interfaces.MapperExtension, m)
-
 class AliasedClassTest(TestBase):
     def point_map(self, cls):
         table = Table('point', MetaData(),