From: Mike Bayer Date: Fri, 11 Jan 2019 20:40:10 +0000 (-0500) Subject: Update comment documentation, make sure tests always run X-Git-Tag: rel_1_0_6~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=58c39c5ac6a3836d1d383c2a3b953013a24dee6e;p=thirdparty%2Fsqlalchemy%2Falembic.git 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 c85a25d5..90f35cd3 100644 --- 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 90b51ba9..5fc71d2b 100644 --- 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 d9d1ce01..8b14e2b0 100644 --- 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 ba0abb6b..754ee2be 100644 --- 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 15ed57e3..2001dd9d 100644 --- 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")