Remove "scope" keyword from scoped_session.__call__()

Removed a very old keyword argument from :class:`.scoped_session`
called ``scope``.  This keyword was never documented and was an
early attempt at allowing for variable scopes.

Change-Id: I9a26498a1a66d1eafb0723e98b527688a60f9d9b
Fixes: #3796

4 files changed, 64 insertions, 11 deletions

diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst
index d8efd74a9..0f7b7b9af 100644
--- a/doc/build/changelog/changelog_12.rst
+++ b/doc/build/changelog/changelog_12.rst
@@ -13,6 +13,18 @@
 .. changelog::
     :version: 1.2.0b1
 
+    .. change:: 3796
+        :tags: bug, orm
+        :tickets: 3796
+
+        Removed a very old keyword argument from :class:`.scoped_session`
+        called ``scope``.  This keyword was never documented and was an
+        early attempt at allowing for variable scopes.
+
+        .. seealso::
+
+            :ref:`change_3796`
+
     .. change:: baked_opts
         :tags: feature, ext
 
diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index 4eec86eb9..a46311f62 100644
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -763,6 +763,28 @@ such as :meth:`.SessionEvents.before_flush`, use the new
 
 :ticket:`3753`
 
+.. _change_3796:
+
+"scope" keyword removed from scoped_session
+-------------------------------------------
+
+A very old and undocumented keyword argument ``scope`` has been removed::
+
+    from sqlalchemy.orm import scoped_session
+    Session = scoped_session(sessionmaker())
+
+    session = Session(scope=None)
+
+The purpose of this keyword was an attempt to allow for variable
+"scopes", where ``None`` indicated "no scope" and would therefore return
+a new :class:`.Session`.   The keyword has never been documented and will
+now raise ``TypeError`` if encountered.   It is not anticipated that this
+keyword is in use, however if users report issues related to this during
+beta tesing, it can be restored with a deprecation.
+
+:ticket:`3796`
+
+
 Key Behavioral Changes - Core
 =============================
 
diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
index 05b881320..055ec7d6a 100644
--- a/lib/sqlalchemy/orm/scoping.py
+++ b/lib/sqlalchemy/orm/scoping.py
@@ -62,18 +62,14 @@ class scoped_session(object):
 
         """
         if kw:
-            scope = kw.pop('scope', False)
-            if scope is not None:
-                if self.registry.has():
-                    raise sa_exc.InvalidRequestError(
-                        "Scoped session is already present; "
-                        "no new arguments may be specified.")
-                else:
-                    sess = self.session_factory(**kw)
-                    self.registry.set(sess)
-                    return sess
+            if self.registry.has():
+                raise sa_exc.InvalidRequestError(
+                    "Scoped session is already present; "
+                    "no new arguments may be specified.")
             else:
-                return self.session_factory(**kw)
+                sess = self.session_factory(**kw)
+                self.registry.set(sess)
+                return sess
         else:
             return self.registry()
 
diff --git a/test/orm/test_scoping.py b/test/orm/test_scoping.py
index 62247a91e..025ad4daa 100644
--- a/test/orm/test_scoping.py
+++ b/test/orm/test_scoping.py
@@ -7,6 +7,7 @@ from sqlalchemy.testing.schema import Table, Column
 from sqlalchemy.orm import mapper, relationship, query
 from sqlalchemy.testing import eq_
 from sqlalchemy.testing import fixtures
+from sqlalchemy.testing.mock import Mock
 
 
 class _ScopedTest(fixtures.MappedTest):
@@ -93,3 +94,25 @@ class ScopedSessionTest(fixtures.MappedTest):
             "At least one scoped session is already present. ",
             Session.configure, bind=testing.db
         )
+
+    def test_call_with_kwargs(self):
+        mock_scope_func = Mock()
+        SessionMaker = sa.orm.sessionmaker()
+        Session = scoped_session(sa.orm.sessionmaker(), mock_scope_func)
+
+        s0 = SessionMaker()
+        assert s0.autocommit == False
+
+        mock_scope_func.return_value = 0
+        s1 = Session()
+        assert s1.autocommit == False
+
+        assert_raises_message(
+            sa.exc.InvalidRequestError,
+            "Scoped session is already present",
+            Session, autocommit=True
+        )
+
+        mock_scope_func.return_value = 1
+        s2 = Session(autocommit=True)
+        assert s2.autocommit == True