From bcfb12f813983d3215a6e2513cfc0b64534d8efe Mon Sep 17 00:00:00 2001
From: Federico Caselli <cfederico87@gmail.com>
Date: Thu, 3 Sep 2020 22:11:30 +0200
Subject: [PATCH] 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
---
 .../changelog/unreleased_14/table_mustexist.rst      |  5 +++++
 lib/sqlalchemy/sql/schema.py                         | 12 +++++++++---
 test/dialect/postgresql/test_reflection.py           |  2 +-
 test/sql/test_deprecations.py                        | 10 ++++++++++
 test/sql/test_metadata.py                            |  6 ++++++
 5 files changed, 31 insertions(+), 4 deletions(-)
 create mode 100644 doc/build/changelog/unreleased_14/table_mustexist.rst

diff --git a/doc/build/changelog/unreleased_14/table_mustexist.rst b/doc/build/changelog/unreleased_14/table_mustexist.rst
new file mode 100644
index 0000000000..ef8b439251
--- /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 5c16b29ff4..e9654fb1f9 100644
--- 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 ec9328c2fb..45c99bfdc3 100644
--- 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 c83c71ada3..a143d10ea3 100644
--- 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 dc4e342fda..09579711b3 100644
--- 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):
-- 
2.47.3