process_revision_directives documentation disagrees with type annotation

[jwodder]

The documentation for EnvironmentContext.configure.process_revision_directives states that the callable's third argument is a list of MigrationScripts, yet the type annotations in the code state that the third argument is a list of MigrateOperations, a superclass of MigrationScript.

This causes problems in particular when trying to add type annotations to the code from the "Don't Generate Empty Migrations with Autogenerate" recipe, as use of the upgrade_ops property assumes that the list elements are MigrationScripts.

To Reproduce

Running mypy 1.6.0 (default config) on the following code:

from __future__ import with_statement
import logging
from alembic import context
from alembic.migration import MigrationContext
from alembic.operations.ops import MigrationScript
import sqlalchemy as sa

config = context.config
logger = logging.getLogger("alembic.env")

engine: sa.Engine
metadata: sa.MetaData

def process_revision_directives(
    context: MigrationContext,  # noqa: U100
    revision: tuple[str, str],  # noqa: U100
    directives: list[MigrationScript],
) -> None:
    if getattr(config.cmd_opts, "autogenerate", False):
        script = directives[0]
        if script.upgrade_ops.is_empty():
            directives[:] = []
            logger.info("No changes in schema detected.")

with engine.connect() as connection:
    context.configure(
        connection=connection,
        target_metadata=metadata,
        process_revision_directives=process_revision_directives,
    )
    with context.begin_transaction():
        context.run_migrations()

fails with the error:

sample02.py:29: error: Argument "process_revision_directives" to "configure" has incompatible type "Callable[[MigrationContext, tuple[str, str], list[MigrationScript]], None]"; expected "Callable[[MigrationContext, tuple[str, str], list[MigrateOperation]], None] | None"  [arg-type]

If MigrationScript is changed to MigrateOperation, the error changes to:

sample01.py:21: error: "MigrateOperation" has no attribute "upgrade_ops"  [attr-defined]

Versions.

• OS: macOS 14.0
• Python: 3.11.6
• Alembic: 1.12.0
• SQLAlchemy: 2.0.22

[zzzeek]

hi -

for simple documentation issues we can accept PRs to correct problems. thanks!

[jwodder]

@zzzeek So is the mistake simply that the third argument should be documented as a list of MigrateOperationss? Then how is it safe for the "Don’t Generate Empty Migrations with Autogenerate" recipe to access an attribute that only exists on a subclass?

[zzzeek]

OK. the attribute is in practice a MigrationScript, I will attempt to change the typing to show MigrationScript all the way through and rewrite the doc example to be typed.

[sqla-tester]

Mike Bayer has proposed a fix for this issue in the main branch:

match process_revision_directives typing to API https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/4927

[zzzeek]

for the next release 1.12.1