restore drop_index.table_name, drop_constraint.type_ as positional

These two API changes were identified as having legacy
use patterns and should be revisited using a deprecation warning
for removal in either 1.12 or 1.13.

Add documentation re: Alembic not using semver, fix
incorrect calling signature example in batch documentation.

Change-Id: I33dc5a8d058bcce77591bb037ae964e626a3387f
Fixes: #1243
Fixes: #1245

10 files changed, 106 insertions, 11 deletions

diff --git a/alembic/op.pyi b/alembic/op.pyi
index 10e6f59..931f1bb 100644
--- a/alembic/op.pyi
+++ b/alembic/op.pyi
@@ -933,8 +933,8 @@ def drop_column(
 def drop_constraint(
     constraint_name: str,
     table_name: str,
-    *,
     type_: Optional[str] = None,
+    *,
     schema: Optional[str] = None,
 ) -> None:
     r"""Drop a constraint of the given name, typically via DROP CONSTRAINT.
@@ -952,8 +952,8 @@ def drop_constraint(
 
 def drop_index(
     index_name: str,
-    *,
     table_name: Optional[str] = None,
+    *,
     schema: Optional[str] = None,
     **kw: Any,
 ) -> None:
diff --git a/alembic/operations/base.py b/alembic/operations/base.py
index 4e59e5b..853e795 100644
--- a/alembic/operations/base.py
+++ b/alembic/operations/base.py
@@ -1335,8 +1335,8 @@ class Operations(AbstractOperations):
             self,
             constraint_name: str,
             table_name: str,
-            *,
             type_: Optional[str] = None,
+            *,
             schema: Optional[str] = None,
         ) -> None:
             r"""Drop a constraint of the given name, typically via DROP CONSTRAINT.
@@ -1356,8 +1356,8 @@ class Operations(AbstractOperations):
         def drop_index(
             self,
             index_name: str,
-            *,
             table_name: Optional[str] = None,
+            *,
             schema: Optional[str] = None,
             **kw: Any,
         ) -> None:
@@ -1787,7 +1787,7 @@ class BatchOperations(AbstractOperations):
             ...
 
         def drop_constraint(
-            self, constraint_name: str, *, type_: Optional[str] = None
+            self, constraint_name: str, type_: Optional[str] = None
         ) -> None:
             """Issue a "drop constraint" instruction using the
             current batch migration context.
diff --git a/alembic/operations/ops.py b/alembic/operations/ops.py
index 5334a01..3c37fee 100644
--- a/alembic/operations/ops.py
+++ b/alembic/operations/ops.py
@@ -132,8 +132,8 @@ class DropConstraintOp(MigrateOperation):
         self,
         constraint_name: Optional[sqla_compat._ConstraintNameDefined],
         table_name: str,
-        *,
         type_: Optional[str] = None,
+        *,
         schema: Optional[str] = None,
         _reverse: Optional[AddConstraintOp] = None,
     ) -> None:
@@ -196,8 +196,8 @@ class DropConstraintOp(MigrateOperation):
         operations: Operations,
         constraint_name: str,
         table_name: str,
-        *,
         type_: Optional[str] = None,
+        *,
         schema: Optional[str] = None,
     ) -> None:
         r"""Drop a constraint of the given name, typically via DROP CONSTRAINT.
@@ -221,7 +221,6 @@ class DropConstraintOp(MigrateOperation):
         cls,
         operations: BatchOperations,
         constraint_name: str,
-        *,
         type_: Optional[str] = None,
     ) -> None:
         """Issue a "drop constraint" instruction using the
@@ -1016,8 +1015,8 @@ class DropIndexOp(MigrateOperation):
     def __init__(
         self,
         index_name: Union[quoted_name, str, conv],
-        *,
         table_name: Optional[str] = None,
+        *,
         schema: Optional[str] = None,
         _reverse: Optional[CreateIndexOp] = None,
         **kw: Any,
@@ -1065,8 +1064,8 @@ class DropIndexOp(MigrateOperation):
         cls,
         operations: Operations,
         index_name: str,
-        *,
         table_name: Optional[str] = None,
+        *,
         schema: Optional[str] = None,
         **kw: Any,
     ) -> None:
diff --git a/docs/build/batch.rst b/docs/build/batch.rst
index 6c2e9d4..b1a1022 100644
--- a/docs/build/batch.rst
+++ b/docs/build/batch.rst
@@ -230,7 +230,7 @@ constraint named ``ck1``.  In order to drop this column, we have to drop
 the check constraint also::
 
     with self.op.batch_alter_table("some_table") as batch_op:
-        batch_op.drop_constraint("ck1", "check")
+        batch_op.drop_constraint("ck1", type_="check")
         batch_op.drop_column('q')
 
 .. versionchanged:: 1.7  Named CHECK constraints participate in batch mode
diff --git a/docs/build/front.rst b/docs/build/front.rst
index f4eb660..5ca73e5 100644
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -89,6 +89,34 @@ Alembic supports Python versions **3.7 and above**
 .. versionchanged::  1.7  Alembic now supports Python 3.6 and newer; support
    for Python 2.7 has been dropped.
 
+.. _versioning_scheme:
+
+Versioning Scheme
+-----------------
+
+Alembic's versioning scheme is based on that of
+`SQLAlchemy's versioning scheme <https://www.sqlalchemy.org/download.html#versions>`_.
+In particular, it should be noted that while Alembic uses a three-number
+versioning scheme, it **does not use SemVer**. In SQLAlchemy and Alembic's
+scheme, **the middle digit is considered to be a "Significant Minor Release",
+which may include removal of previously deprecated APIs with some risk of
+non-backwards compatibility in a very small number of cases**.
+
+This means that version "1.8.0", "1.9.0", "1.10.0", "1.11.0", etc. are
+**Significant Minor Releases**, which will include new API features and may
+remove or modify existing ones.
+
+Therefore, when `pinning <https://pip.pypa.io/en/stable/topics/repeatable-installs/>`_
+Alembic releases, pin to the "major" and "minor" digits to avoid API changes.
+
+A true "Major" release such as a change to "2.0" would include complete
+redesigns/re-architectures of foundational features; currently no such series
+of changes are planned, although changes such as replacing the entire
+"autogenerate" scheme with a new approach would qualify for that level of
+change.
+
+
+
 Community
 =========
 
diff --git a/docs/build/unreleased/1243.rst b/docs/build/unreleased/1243.rst
new file mode 100644
index 0000000..26c8e35
--- /dev/null
+++ b/docs/build/unreleased/1243.rst
@@ -0,0 +1,21 @@
+.. change::
+    :tags: bug, autogenerate, regression
+    :tickets: 1243 1245
+
+    As Alembic 1.11.0 is considered a major release (Alembic does not use
+    semver, nor does its parent project SQLAlchemy; this has been
+    :ref:`clarified <versioning_scheme>` in the documentation), change
+    :ticket:`1130` modified calling signatures for most operations to consider
+    all optional keyword parameters to be keyword-only arguments, to match what
+    was always documented and generated by autogenerate. However, two of these
+    changes were identified as possibly problematic without a more formal
+    deprecation warning being emitted which were the ``table_name`` parameter
+    to :meth:`.Operations.drop_index`, which was generated positionally by
+    autogenerate prior to version 0.6.3 released in 2014, and ``type_`` in
+    :meth:`.Operations.drop_constraint` and
+    :meth:`.BatchOperations.drop_constraint`, which was documented positionally
+    in one example in the batch documentation. These two signatures have been
+    restored to allow those particular parameters to be passed positionally. A
+    future change will include formal deprecation paths (with warnings) for
+    these arguments where they will again become keyword-only in a future
+    "Significant Minor" release.
diff --git a/tests/test_batch.py b/tests/test_batch.py
index 66d59fd..5920cdf 100644
--- a/tests/test_batch.py
+++ b/tests/test_batch.py
@@ -1783,6 +1783,19 @@ class BatchRoundTripTest(TestBase):
         ck_consts = inspect(self.conn).get_check_constraints("ck_table")
         eq_(ck_consts, [])
 
+    @config.requirements.check_constraint_reflection
+    def test_drop_ck_constraint_legacy_type(self):
+        self._ck_constraint_fixture()
+
+        with self.op.batch_alter_table(
+            "ck_table", recreate="always"
+        ) as batch_op:
+            # matches the docs that were written for this originally
+            batch_op.drop_constraint("ck", "check")
+
+        ck_consts = inspect(self.conn).get_check_constraints("ck_table")
+        eq_(ck_consts, [])
+
     @config.requirements.unnamed_constraints
     def test_drop_foreign_key(self):
         bar = Table(
diff --git a/tests/test_mssql.py b/tests/test_mssql.py
index b785e2f..693ab57 100644
--- a/tests/test_mssql.py
+++ b/tests/test_mssql.py
@@ -161,6 +161,12 @@ class OpTest(TestBase):
         op.drop_index("my_idx", table_name="my_table")
         context.assert_contains("DROP INDEX my_idx ON my_table")
 
+    def test_drop_index_w_tablename_legacy(self):
+        """#1243"""
+        context = op_fixture("mssql")
+        op.drop_index("my_idx", "my_table")
+        context.assert_contains("DROP INDEX my_idx ON my_table")
+
     def test_drop_column_w_default(self):
         context = op_fixture("mssql")
         op.drop_column("t1", "c1", mssql_drop_default=True)
diff --git a/tests/test_mysql.py b/tests/test_mysql.py
index fd3b185..c3ac966 100644
--- a/tests/test_mysql.py
+++ b/tests/test_mysql.py
@@ -399,6 +399,12 @@ class MySQLOpTest(TestBase):
         op.drop_constraint("f1", "t1", type_="foreignkey")
         context.assert_("ALTER TABLE t1 DROP FOREIGN KEY f1")
 
+    def test_drop_fk_legacy(self):
+        """#1245"""
+        context = op_fixture("mysql")
+        op.drop_constraint("f1", "t1", "foreignkey")
+        context.assert_("ALTER TABLE t1 DROP FOREIGN KEY f1")
+
     def test_drop_fk_quoted(self):
         context = op_fixture("mysql")
         op.drop_constraint("MyFk", "MyTable", type_="foreignkey")
diff --git a/tests/test_op.py b/tests/test_op.py
index 35adeaf..6aca753 100644
--- a/tests/test_op.py
+++ b/tests/test_op.py
@@ -806,6 +806,17 @@ class OpTest(TestBase):
         op.drop_constraint("foo_bar_bat", "t1")
         context.assert_("ALTER TABLE t1 DROP CONSTRAINT foo_bar_bat")
 
+    def test_drop_constraint_type(self):
+        context = op_fixture()
+        op.drop_constraint("foo_bar_bat", "t1", type_="foreignkey")
+        context.assert_("ALTER TABLE t1 DROP CONSTRAINT foo_bar_bat")
+
+    def test_drop_constraint_legacy_type(self):
+        """#1245"""
+        context = op_fixture()
+        op.drop_constraint("foo_bar_bat", "t1", "foreignkey")
+        context.assert_("ALTER TABLE t1 DROP CONSTRAINT foo_bar_bat")
+
     def test_drop_constraint_schema(self):
         context = op_fixture()
         op.drop_constraint("foo_bar_bat", "t1", schema="foo")
@@ -856,6 +867,17 @@ class OpTest(TestBase):
         op.drop_index("ik_test")
         context.assert_("DROP INDEX ik_test")
 
+    def test_drop_index_w_tablename(self):
+        context = op_fixture()
+        op.drop_index("ik_test", table_name="the_table")
+        context.assert_("DROP INDEX ik_test")
+
+    def test_drop_index_w_tablename_legacy(self):
+        """#1243"""
+        context = op_fixture()
+        op.drop_index("ik_test", "the_table")
+        context.assert_("DROP INDEX ik_test")
+
     def test_drop_index_schema(self):
         context = op_fixture()
         op.drop_index("ik_test", schema="foo")