Update comment documentation, make sure tests always run

Corrected the links and text in the changelog note as well as
ensured new comment-oriented methods and parameters include a
versionadded token.    Added a more specific check so that
any run of the tests will make sure SQLAlchemy issue 4436
is resolved as 1.2.16 resolves it but 1.3.0b1, which currently
comes out for "python setup.py test", does not.

Change-Id: Ibd94bf7940b279e85b0ec1ddceb309df0c18f0b1

diff --git a/alembic/operations/ops.py b/alembic/operations/ops.py
index c85a25d5ff2b03736eadd8252d4288cd8dba8cdb..90f35cd37f95d11e3fbe9a4436a03a2d8cf2cbd2 100644 (file)
--- a/alembic/operations/ops.py
+++ b/alembic/operations/ops.py
@@ -1374,15 +1374,23 @@ class CreateTableCommentOp(AlterTableOp):
         existing_comment=None,
         schema=None,
     ):
-        """Invokes the `:func:`alembic.operations.toimpl.create_table_comment`
-        impl to initiate a new COMMENT ON `table` operation.
+        """Emit a COMMENT ON operation to set the comment for a table.
+
+        .. versionadded:: 1.0.6
 
         :param table_name: string name of the target table.
         :param comment: string value of the comment being registered against
          the specified table.
-        :param existing_comment: An optional string value of a comment
-         already registered
-         on the specified table.
+        :param existing_comment: String value of a comment
+         already registered on the specified table, used within autogenerate
+         so that the operation is reversible, but not required for direct
+         use.
+
+        .. seealso::
+
+            :meth:`.Operations.drop_table_comment`
+
+            :paramref:`.Operations.alter_column.comment`
 
         """
 
@@ -1424,7 +1432,7 @@ class CreateTableCommentOp(AlterTableOp):
 
 @Operations.register_operation("drop_table_comment")
 class DropTableCommentOp(AlterTableOp):
-    """Represent a COMMENT ON `table` operation.
+    """Represent an operation to remove the comment from a table.
     """
 
     def __init__(self, table_name, schema=None, existing_comment=None):
@@ -1436,13 +1444,20 @@ class DropTableCommentOp(AlterTableOp):
     def drop_table_comment(
         cls, operations, table_name, existing_comment=None, schema=None
     ):
-        """Invokes the `:func:`alembic.operations.toimpl.drop_table_comment` to
+        """Issue a "drop table comment" operation to
         remove an existing comment set on a table.
 
+        .. versionadded:: 1.0.6
+
         :param table_name: string name of the target table.
         :param existing_comment: An optional string value of a comment already
-         registered
-         on the specified table.
+         registered on the specified table.
+
+        .. seealso::
+
+            :meth:`.Operations.create_table_comment`
+
+            :paramref:`.Operations.alter_column.comment`
 
         """
 
@@ -1682,6 +1697,11 @@ class AlterColumnOp(AlterTableOp):
          or :class:`~sqlalchemy.schema.DefaultClause` to indicate
          an alteration to the column's default value.
          Set to ``None`` to have the default removed.
+        :param comment: optional string text of a new comment to add to the
+         column.
+
+         .. versionadded:: 1.0.6
+
         :param new_column_name: Optional; specify a string name here to
          indicate the new name within a column rename operation.
         :param type_: Optional; a :class:`~sqlalchemy.types.TypeEngine`
@@ -1712,6 +1732,12 @@ class AlterColumnOp(AlterTableOp):
         :param existing_autoincrement: Optional; the existing autoincrement
          of the column.  Used for MySQL's system of altering a column
          that specifies ``AUTO_INCREMENT``.
+        :param existing_comment: string text of the existing comment on the
+         column to be maintained.  Required on MySQL if the existing comment
+         on the column is not being changed.
+
+         .. versionadded:: 1.0.6
+
         :param schema: Optional schema name to operate within.  To control
          quoting of the schema outside of the default behavior, use
          the SQLAlchemy construct

diff --git a/alembic/testing/requirements.py b/alembic/testing/requirements.py
index 90b51ba998214c8ae2bb2a49209e9eccbeb546f1..5fc71d2b2a6add8a8cb358666f609b01370c4308 100644 (file)
--- a/alembic/testing/requirements.py
+++ b/alembic/testing/requirements.py
@@ -137,10 +137,20 @@ class SuiteRequirements(Requirements):
         )
 
     @property
-    def sqlalchemy_1216(self):
+    def sqlalchemy_issue_4436(self):
+        def check(config):
+            vers = sqla_compat._vers
+
+            if vers == (1, 3, 0, 'b1'):
+                return True
+            elif vers > (1, 2, 16):
+                return False
+            else:
+                return True
+
         return exclusions.skip_if(
-            lambda config: not util.sqla_1216,
-            "SQLAlchemy 1.2.16 or greater required",
+            check,
+            "SQLAlchemy 1.2.16, 1.3.0b2 or greater required",
         )
 
     @property

diff --git a/docs/build/unreleased/422.rst b/docs/build/unreleased/422.rst
index d9d1ce01c9045ac403ec860a1b878263196ef9c7..8b14e2b0bb7b70e7ca9856605007f4a74c057d87 100644 (file)
--- a/docs/build/unreleased/422.rst
+++ b/docs/build/unreleased/422.rst
@@ -3,6 +3,12 @@
     :tickets: 422
 
     Added Table and Column level comments for supported backends.
-    `create_table`, `add_column` and `alter_column` now all optionally
-    take  `comment="X"` kwarg.  Support for autogenerate for Table
-    and Column objects has also been added.
\ No newline at end of file
+    New methods :meth:`.Operations.create_table_comment` and
+    :meth:`.Operations.drop_table_comment` are added.  A new arguments
+    :paramref:`.Operations.alter_column.comment` and
+    :paramref:`.Operations.alter_column.existing_comment` are added to
+    :meth:`.Operations.alter_column`.   Autogenerate support is also added
+    to ensure comment add/drops from tables and columns are generated as well
+    as that :meth:`.Operations.create_table`, :meth:`.Operations.add_column`
+    both include the comment field from the source :class:`.Table`
+    or :class:`.Column` object.
\ No newline at end of file

diff --git a/tests/test_mysql.py b/tests/test_mysql.py
index ba0abb6b14e89166d31f3308f9ec1e3bfc05b1a2..754ee2befabed6b98ac2a555609c69feeb1f4f61 100644 (file)
--- a/tests/test_mysql.py
+++ b/tests/test_mysql.py
@@ -316,7 +316,7 @@ class MySQLOpTest(TestBase):
         context.assert_("ALTER TABLE foo.t2 COMMENT 't2 table'")
 
     @config.requirements.comments_api
-    @config.requirements.sqlalchemy_1216
+    @config.requirements.sqlalchemy_issue_4436
     def test_drop_table_comment(self):
         # this is handled by SQLAlchemy's compilers
         context = op_fixture("mysql")

diff --git a/tests/test_oracle.py b/tests/test_oracle.py
index 15ed57e36b2bf025bc42b8f2e4be3420358cdf39..2001dd9d73c295af6cb8ea192ebb76602dc080f0 100644 (file)
--- a/tests/test_oracle.py
+++ b/tests/test_oracle.py
@@ -114,7 +114,7 @@ class OpTest(TestBase):
         )
 
     @config.requirements.comments_api
-    @config.requirements.sqlalchemy_1216
+    @config.requirements.sqlalchemy_issue_4436
     def test_drop_table_comment(self):
         # this is handled by SQLAlchemy's compilers
         context = op_fixture("oracle")