match process_revision_directives typing to API

Improved typing in the
:paramref:`.EnvironmentContext.configure.process_revision_directives`
callable to better indicate that the passed-in type is
:class:`.MigrationScript`, not the :class:`.MigrationOperation` base class,
and added typing to the example at :ref:`cookbook_no_empty_migrations` to
illustrate.

Change-Id: Ibfb7a57a081818c290cf0964d12a72b85c2c1983
Fixes: #1325

Author: zzzeek

Diff for: alembic/autogenerate/api.py

@@ -5,6 +5,7 @@
 from typing import Callable
 from typing import Dict
 from typing import Iterator
+from typing import List
 from typing import Optional
 from typing import Sequence
 from typing import Set
@@ -508,6 +509,8 @@ class RevisionContext:
     """Maintains configuration and state that's specific to a revision
     file generation operation."""
 
+    generated_revisions: List[MigrationScript]
+
     def __init__(
         self,
         config: Config,

Diff for: alembic/context.pyi

@@ -30,7 +30,7 @@ if TYPE_CHECKING:
 
     from .autogenerate.api import AutogenContext
     from .config import Config
-    from .operations.ops import MigrateOperation
+    from .operations.ops import MigrationScript
     from .runtime.migration import _ProxyTransaction
     from .runtime.migration import MigrationContext
     from .runtime.migration import MigrationInfo
@@ -143,7 +143,7 @@ def configure(
     include_schemas: bool = False,
     process_revision_directives: Optional[
         Callable[
-            [MigrationContext, Tuple[str, str], List[MigrateOperation]], None
+            [MigrationContext, Tuple[str, str], List[MigrationScript]], None
         ]
     ] = None,
     compare_type: Union[

Diff for: alembic/operations/__init__.py

@@ -3,11 +3,13 @@
 from .base import BatchOperations
 from .base import Operations
 from .ops import MigrateOperation
+from .ops import MigrationScript
 
 
 __all__ = [
     "AbstractOperations",
     "Operations",
     "BatchOperations",
     "MigrateOperation",
+    "MigrationScript",
 ]

Diff for: alembic/runtime/environment.py

@@ -36,13 +36,13 @@
     from ..autogenerate.api import AutogenContext
     from ..config import Config
     from ..ddl import DefaultImpl
-    from ..operations.ops import MigrateOperation
+    from ..operations.ops import MigrationScript
     from ..script.base import ScriptDirectory
 
 _RevNumber = Optional[Union[str, Tuple[str, ...]]]
 
 ProcessRevisionDirectiveFn = Callable[
-    [MigrationContext, Tuple[str, str], List["MigrateOperation"]], None
+    [MigrationContext, Tuple[str, str], List["MigrationScript"]], None
 ]
 
 RenderItemFn = Callable[

Diff for: docs/build/cookbook.rst

@@ -900,14 +900,26 @@ hook in :meth:`.MigrationContext.configure` which removes the
 single :class:`.MigrationScript` directive if it is empty of
 any operations::
 
+    # for typing purposes
+    from alembic.environment import MigrationContext
+
+    # this typing-only import requires alembic 1.12.1 or above
+    from alembic.operations import MigrationScript
+
 
     def run_migrations_online():
 
         # ...
 
-        def process_revision_directives(context, revision, directives):
+        def process_revision_directives(
+            context: MigrationContext,
+            revision: tuple[str, str],
+            directives: list[MigrationScript],
+        ):
+            assert config.cmd_opts is not None
             if config.cmd_opts.autogenerate:
                 script = directives[0]
+                assert script.upgrade_ops is not None
                 if script.upgrade_ops.is_empty():
                     directives[:] = []
 

Diff for: docs/build/unreleased/1325.rst

@@ -0,0 +1,10 @@
+.. change::
+    :tags: bug, typing
+    :tickets: 1325
+
+    Improved typing in the
+    :paramref:`.EnvironmentContext.configure.process_revision_directives`
+    callable to better indicate that the passed-in type is
+    :class:`.MigrationScript`, not the :class:`.MigrationOperation` base class,
+    and added typing to the example at :ref:`cookbook_no_empty_migrations` to
+    illustrate.