Raname ``mustexit`` to ``must_exist``

:class:`_schema.Table` parameter ``mustexist`` has been renamed
to :paramref:`_schema.Table.must_exist` and will now warn when used.

Change-Id: I0b0ca6021f9f7cfbe2040bbc1125a2236ac79f53

diff --git a/doc/build/changelog/unreleased_14/table_mustexist.rst b/doc/build/changelog/unreleased_14/table_mustexist.rst
new file mode 100644 (file)
index 0000000..ef8b439
--- /dev/null
+++ b/doc/build/changelog/unreleased_14/table_mustexist.rst
@@ -0,0 +1,5 @@
+.. change::
+    :tags: change, sql
+
+    :class:`_schema.Table` parameter ``mustexist`` has been renamed
+    to :paramref:`_schema.Table.must_exist` and will now warn when used.

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 5c16b29ff47e7188fa7e53ff16859e5de0a78ee2..e9654fb1f9c2e746ea5d4c6f484d924183511274 100644 (file)
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -412,7 +412,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
                     ('column_reflect', listen_for_reflect)
                 ])
 
-    :param mustexist: When ``True``, indicates that this Table must already
+    :param must_exist: When ``True``, indicates that this Table must already
         be present in the given :class:`_schema.MetaData` collection, else
         an exception is raised.
 
@@ -484,6 +484,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         else:
             return (self,)
 
+    @util.deprecated_params(
+        mustexist=(
+            "1.4",
+            "Deprecated alias of :paramref:`_schema.Table.must_exist`",
+        )
+    )
     def __new__(cls, *args, **kw):
         if not args:
             # python3k pickle seems to call this
@@ -506,7 +512,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
             msg = "keep_existing and extend_existing are mutually exclusive."
             raise exc.ArgumentError(msg)
 
-        mustexist = kw.pop("mustexist", False)
+        must_exist = kw.pop("must_exist", kw.pop("mustexist", False))
         key = _get_table_key(name, schema)
         if key in metadata.tables:
             if not keep_existing and not extend_existing and bool(args):
@@ -522,7 +528,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
                 table._init_existing(*args, **kw)
             return table
         else:
-            if mustexist:
+            if must_exist:
                 raise exc.InvalidRequestError("Table '%s' not defined" % (key))
             table = object.__new__(cls)
             table.dispatch.before_parent_attach(table, metadata)

diff --git a/test/dialect/postgresql/test_reflection.py b/test/dialect/postgresql/test_reflection.py
index ec9328c2fb1ea45a9fd2809329cfdbf9dd8bbb5c..45c99bfdc30c246e7a122935672845ae87cacd58 100644 (file)
--- a/test/dialect/postgresql/test_reflection.py
+++ b/test/dialect/postgresql/test_reflection.py
@@ -569,7 +569,7 @@ class ReflectionTest(fixtures.TestBase):
         addresses = Table(
             "email_addresses", meta2, autoload=True, schema="test_schema"
         )
-        users = Table("users", meta2, mustexist=True, schema="test_schema")
+        users = Table("users", meta2, must_exist=True, schema="test_schema")
         j = join(users, addresses)
         self.assert_(
             (users.c.user_id == addresses.c.remote_user_id).compare(j.onclause)

diff --git a/test/sql/test_deprecations.py b/test/sql/test_deprecations.py
index c83c71ada36894f38df5b668f436647f579a67f1..a143d10ea38b3a856d33700e3cc7ba299ca9b83b 100644 (file)
--- a/test/sql/test_deprecations.py
+++ b/test/sql/test_deprecations.py
@@ -1770,3 +1770,13 @@ class DMLTest(fixtures.TestBase, AssertsCompiledSQL):
         self.assert_compile(
             stmt, "UPDATE foo SET bar=%s LIMIT 10", dialect="mysql"
         )
+
+
+class TableDeprecationTest(fixtures.TestBase):
+    def test_mustexists(self):
+        with testing.expect_deprecated("Deprecated alias of .*must_exist"):
+
+            with testing.expect_raises_message(
+                exc.InvalidRequestError, "Table 'foo' not defined"
+            ):
+                Table("foo", MetaData(), mustexist=True)

diff --git a/test/sql/test_metadata.py b/test/sql/test_metadata.py
index dc4e342fda82a40290e54ba76b9d8861e5dd5889..09579711b3cbeb22158cfcd73c504331f00e4a32 100644 (file)
--- a/test/sql/test_metadata.py
+++ b/test/sql/test_metadata.py
@@ -1788,6 +1788,12 @@ class TableTest(fixtures.TestBase, AssertsCompiledSQL):
         assert not t2.c.x.nullable
         assert not t1.c.x.nullable
 
+    def test_must_exist(self):
+        with testing.expect_raises_message(
+            exc.InvalidRequestError, "Table 'foo' not defined"
+        ):
+            Table("foo", MetaData(), must_exist=True)
+
 
 class PKAutoIncrementTest(fixtures.TestBase):
     def test_multi_integer_no_autoinc(self):