Session.mapper is now *deprecated*.

Call session.add() if you'd like a free-standing object to be
part of your session.  Otherwise, a DIY version of
Session.mapper is now documented at
http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper
The method will remain deprecated throughout 0.6.

M    test/ext/test_declarative.py
M    test/orm/test_scoping.py
M    lib/sqlalchemy/orm/scoping.py
M    CHANGES

diff --git a/CHANGES b/CHANGES
index 4f814d4bcf624fb89df772808c775dda692cbdb8..faee0d3dd281d62d8315284a16ca6970fc493f85 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -12,6 +12,13 @@ CHANGES
       the tests.  [ticket:970]
       
 - orm
+    - Session.mapper is now *deprecated*.   
+      Call session.add() if you'd like a free-standing object to be 
+      part of your session.  Otherwise, a DIY version of
+      Session.mapper is now documented at 
+      http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper
+      The method will remain deprecated throughout 0.6.
+    
     - Fixed bug introduced in 0.5.4 whereby Composite types
       fail when default-holding columns are flushed.
       

diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
index 5559784c76c1f3e1bc0b7a9fc9492f619c055285..4339b68ebc5f4de4c12a88534deee5abd1c21293 100644 (file)
--- a/lib/sqlalchemy/orm/scoping.py
+++ b/lib/sqlalchemy/orm/scoping.py
@@ -5,7 +5,7 @@
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
 import sqlalchemy.exceptions as sa_exc
-from sqlalchemy.util import ScopedRegistry, to_list, get_cls_kwargs
+from sqlalchemy.util import ScopedRegistry, to_list, get_cls_kwargs, deprecated
 from sqlalchemy.orm import (
     EXT_CONTINUE, MapperExtension, class_mapper, object_session
     )
@@ -23,12 +23,7 @@ class ScopedSession(object):
 
       Session = scoped_session(sessionmaker(autoflush=True))
 
-      To map classes so that new instances are saved in the current
-      Session automatically, as well as to provide session-aware
-      class attributes such as "query":
-
-      mapper = Session.mapper
-      mapper(Class, table, ...)
+      ... use session normally.
 
     """
 
@@ -57,8 +52,15 @@ class ScopedSession(object):
             self.registry().close()
         self.registry.clear()
 
+    @deprecated("Session.mapper is deprecated.  "
+        "Please see http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper "
+        "for information on how to replicate its behavior.")
     def mapper(self, *args, **kwargs):
-        """return a mapper() function which associates this ScopedSession with the Mapper."""
+        """return a mapper() function which associates this ScopedSession with the Mapper.
+        
+        DEPRECATED.
+        
+        """
 
         from sqlalchemy.orm import mapper
 

diff --git a/test/ext/test_declarative.py b/test/ext/test_declarative.py
index c49c00cec0d267c8aca0c70016c1b02042a56cf9..1e2fc9b60dc73eb2710e8efae87848a3a2a08397 100644 (file)
--- a/test/ext/test_declarative.py
+++ b/test/ext/test_declarative.py
@@ -398,6 +398,7 @@ class DeclarativeTest(DeclarativeTestBase):
             Address(email='two'),
         ])])
         
+    @testing.uses_deprecated()
     def test_custom_mapper(self):
         class MyExt(sa.orm.MapperExtension):
             def create_instance(self):

diff --git a/test/orm/test_scoping.py b/test/orm/test_scoping.py
index 2117e8dccbf47cc2935d65598601b96c544c7745..9f2f59e19b42db526f5d5920b489b73159b02fb1 100644 (file)
--- a/test/orm/test_scoping.py
+++ b/test/orm/test_scoping.py
@@ -96,6 +96,7 @@ class ScopedMapperTest(_ScopedTest):
             pass
 
     @classmethod
+    @testing.uses_deprecated()
     @testing.resolve_artifact_names
     def setup_mappers(cls):
         Session = scoped_session(sa.orm.create_session)
@@ -122,6 +123,7 @@ class ScopedMapperTest(_ScopedTest):
         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):
@@ -141,6 +143,7 @@ class ScopedMapperTest(_ScopedTest):
         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())
@@ -171,6 +174,7 @@ class ScopedMapperTest(_ScopedTest):
         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)
@@ -183,6 +187,7 @@ class ScopedMapperTest(_ScopedTest):
         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):
@@ -215,6 +220,7 @@ class ScopedMapperTest2(_ScopedTest):
             pass
 
     @classmethod
+    @testing.uses_deprecated()
     @testing.resolve_artifact_names
     def setup_mappers(cls):
         Session = scoped_session(sa.orm.sessionmaker())