- document all the 0.8 positional name changes

- ensure remaining name->constraint_name / table_name

2 files changed, 146 insertions, 8 deletions

diff --git a/alembic/operations/ops.py b/alembic/operations/ops.py
index 7f26e65..da50c48 100644
--- a/alembic/operations/ops.py
+++ b/alembic/operations/ops.py
@@ -113,12 +113,16 @@ class DropConstraintOp(MigrateOperation):
                 "original constraint is not present")
 
     @classmethod
-    @util._with_legacy_names([("type", "type_")])
+    @util._with_legacy_names([
+        ("type", "type_"),
+        ("name", "constraint_name"),
+    ])
     def drop_constraint(
-            cls, operations, name, table_name, type_=None, schema=None):
+            cls, operations, constraint_name, table_name,
+            type_=None, schema=None):
         """Drop a constraint of the given name, typically via DROP CONSTRAINT.
 
-        :param name: name of the constraint.
+        :param constraint_name: name of the constraint.
         :param table_name: table name.
         :param ``type_``: optional, required on MySQL.  can be
          'foreignkey', 'primary', 'unique', or 'check'.
@@ -130,13 +134,18 @@ class DropConstraintOp(MigrateOperation):
          .. versionadded:: 0.7.0 'schema' can now accept a
             :class:`~sqlalchemy.sql.elements.quoted_name` construct.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+
         """
 
-        op = cls(name, table_name, type_=type_, schema=schema)
+        op = cls(constraint_name, table_name, type_=type_, schema=schema)
         return operations.invoke(op)
 
     @classmethod
-    def batch_drop_constraint(cls, operations, name, type_=None):
+    def batch_drop_constraint(cls, operations, constraint_name, type_=None):
         """Issue a "drop constraint" instruction using the
         current batch migration context.
 
@@ -147,9 +156,14 @@ class DropConstraintOp(MigrateOperation):
 
             :meth:`.Operations.drop_constraint`
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+
         """
         op = cls(
-            name, operations.impl.table_name,
+            constraint_name, operations.impl.table_name,
             type_=type_, schema=operations.impl.schema
         )
         return operations.invoke(op)
@@ -235,6 +249,12 @@ class CreatePrimaryKeyOp(AddConstraintOp):
          .. versionadded:: 0.7.0 'schema' can now accept a
             :class:`~sqlalchemy.sql.elements.quoted_name` construct.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+           * cols -> columns
+
         """
         op = cls(constraint_name, table_name, columns, schema)
         return operations.invoke(op)
@@ -348,6 +368,13 @@ class CreateUniqueConstraintOp(AddConstraintOp):
          .. versionadded:: 0.7.0 'schema' can now accept a
             :class:`~sqlalchemy.sql.elements.quoted_name` construct.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+           * source -> table_name
+           * local_cols -> columns
+
         """
 
         op = cls(
@@ -370,6 +397,11 @@ class CreateUniqueConstraintOp(AddConstraintOp):
 
             :meth:`.Operations.create_unique_constraint`
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+
         """
         kw['schema'] = operations.impl.schema
         op = cls(
@@ -493,6 +525,13 @@ class CreateForeignKeyOp(AddConstraintOp):
         :param source_schema: Optional schema name of the source table.
         :param referent_schema: Optional schema name of the destination table.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+           * source -> source_table
+           * referent -> referent_table
+
         """
 
         op = cls(
@@ -509,7 +548,10 @@ class CreateForeignKeyOp(AddConstraintOp):
         return operations.invoke(op)
 
     @classmethod
-    @util._with_legacy_names([('name', 'constraint_name')])
+    @util._with_legacy_names([
+        ('name', 'constraint_name'),
+        ('referent', 'referent_table')
+    ])
     def batch_create_foreign_key(
             cls, operations, constraint_name, referent_table,
             local_cols, remote_cols,
@@ -534,6 +576,12 @@ class CreateForeignKeyOp(AddConstraintOp):
 
             :meth:`.Operations.create_foreign_key`
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+           * referent -> referent_table
+
         """
         op = cls(
             constraint_name,
@@ -633,6 +681,12 @@ class CreateCheckConstraintOp(AddConstraintOp):
          .. versionadded:: 0.7.0 'schema' can now accept a
             :class:`~sqlalchemy.sql.elements.quoted_name` construct.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+           * source -> table_name
+
         """
         op = cls(constraint_name, table_name, condition, schema=schema, **kw)
         return operations.invoke(op)
@@ -651,6 +705,11 @@ class CreateCheckConstraintOp(AddConstraintOp):
 
             :meth:`.Operations.create_check_constraint`
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> constraint_name
+
         """
         op = cls(
             constraint_name, operations.impl.table_name,
@@ -755,6 +814,12 @@ class CreateIndexOp(MigrateOperation):
             ``<dialectname>_<argname>``.
             See the documentation regarding an individual dialect at
             :ref:`dialect_toplevel` for detail on documented arguments.
+
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> index_name
+
         """
         op = cls(
             index_name, table_name, columns, schema=schema,
@@ -824,7 +889,9 @@ class DropIndexOp(MigrateOperation):
 
     @classmethod
     @util._with_legacy_names([
-        ('name', 'index_name'), ('tablename', 'table_name')])
+        ('name', 'index_name'),
+        ('tablename', 'table_name')
+    ])
     def drop_index(cls, operations, index_name, table_name=None, schema=None):
         """Issue a "drop index" instruction using the current
         migration context.
@@ -844,6 +911,11 @@ class DropIndexOp(MigrateOperation):
          .. versionadded:: 0.7.0 'schema' can now accept a
             :class:`~sqlalchemy.sql.elements.quoted_name` construct.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> index_name
+
         """
         op = cls(index_name, table_name=table_name, schema=schema)
         return operations.invoke(op)
@@ -858,6 +930,11 @@ class DropIndexOp(MigrateOperation):
 
             :meth:`.Operations.drop_index`
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> index_name
+
         """
 
         op = cls(
@@ -990,6 +1067,11 @@ class CreateTableOp(MigrateOperation):
          .. versionadded:: 0.7.0 - the :class:`~sqlalchemy.schema.Table`
             object is returned.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> table_name
+
         """
         op = cls(table_name, columns, **kw)
         return operations.invoke(op)
@@ -1052,6 +1134,11 @@ class DropTableOp(MigrateOperation):
         :param \**kw: Other keyword arguments are passed to the underlying
          :class:`sqlalchemy.schema.Table` object created for the command.
 
+        .. versionchanged:: 0.8.0 The following positional argument names
+           have been changed:
+
+           * name -> table_name
+
         """
         op = cls(table_name, schema=schema, table_kw=kw)
         operations.invoke(op)
diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst
index 424bf8f..d8184d1 100644
--- a/docs/build/changelog.rst
+++ b/docs/build/changelog.rst
@@ -7,6 +7,57 @@ Changelog
     :version: 0.8.0
 
     .. change::
+      :tags: change, operations
+
+      A range of positional argument names have been changed to be
+      clearer and more consistent across methods within the
+      :class:`.Operations` namespace.   The most prevalent form of name change
+      is that the descriptive names ``constraint_name`` and ``table_name``
+      are now used where previously the name ``name`` would be used.
+      This is in support of the newly modularized and extensible system of
+      operation objects in :mod:`alembic.operations.ops`.
+      An argument translation layer is in place
+      across the ``alembic.op`` namespace that will ensure that named
+      argument calling styles that use the old names will continue to
+      function by transparently translating to the new names,
+      also emitting a warning.   This, along with the fact that these
+      arguments are positional in any case and aren't normally
+      passed with an explicit name, should ensure that the
+      overwhelming majority of applications should be unaffected by this
+      change.   The *only* applications that are impacted are those that:
+
+      1. use the :class:`.Operations` object directly in some way, rather
+         than calling upon the ``alembic.op`` namespace, and
+
+      2. invoke the methods on :class:`.Operations` using named keyword
+         arguments for positional arguments like ``table_name``,
+         ``constraint_name``, etc., which commonly were named ``name``
+         as of 0.7.6.
+
+      3. any application that is using named keyword arguments in place
+         of positional argument for the recently added
+         :class:`.BatchOperations` object may also be affected.
+
+      The naming changes are documented as "versionchanged" for 0.8.0:
+
+      * :meth:`.BatchOperations.create_check_constraint`
+      * :meth:`.BatchOperations.create_foreign_key`
+      * :meth:`.BatchOperations.create_index`
+      * :meth:`.BatchOperations.create_unique_constraint`
+      * :meth:`.BatchOperations.drop_constraint`
+      * :meth:`.BatchOperations.drop_index`
+      * :meth:`.Operations.create_check_constraint`
+      * :meth:`.Operations.create_foreign_key`
+      * :meth:`.Operations.create_primary_key`
+      * :meth:`.Operations.create_index`
+      * :meth:`.Operations.create_table`
+      * :meth:`.Operations.create_unique_constraint`
+      * :meth:`.Operations.drop_constraint`
+      * :meth:`.Operations.drop_index`
+      * :meth:`.Operations.drop_table`
+
+
+    .. change::
       :tags: feature, tests
 
       The default test runner via "python setup.py test" is now py.test.