Merge branch 'main' into main

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/python/black
-    rev: 23.3.0
+    rev: 24.1.1
     hooks:
     -   id: black
 

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2009-2023 Michael Bayer.
+Copyright 2009-2024 Michael Bayer.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in
@@ -16,4 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

alembic/__init__.py

@@ -1,4 +1,4 @@
 from . import context
 from . import op
 
-__version__ = "1.13.2"
+__version__ = "1.14.1"

alembic/autogenerate/api.py

@@ -277,7 +277,7 @@ class AutogenContext:
     """Maintains configuration and state that's specific to an
     autogenerate operation."""
 
-    metadata: Optional[MetaData] = None
+    metadata: Union[MetaData, Sequence[MetaData], None] = None
     """The :class:`~sqlalchemy.schema.MetaData` object
     representing the destination.
 
@@ -332,7 +332,7 @@ class AutogenContext:
     def __init__(
         self,
         migration_context: MigrationContext,
-        metadata: Optional[MetaData] = None,
+        metadata: Union[MetaData, Sequence[MetaData], None] = None,
         opts: Optional[Dict[str, Any]] = None,
         autogenerate: bool = True,
     ) -> None:
@@ -596,9 +596,9 @@ def _run_environment(
         migration_script = self.generated_revisions[-1]
         if not getattr(migration_script, "_needs_render", False):
             migration_script.upgrade_ops_list[-1].upgrade_token = upgrade_token
-            migration_script.downgrade_ops_list[
-                -1
-            ].downgrade_token = downgrade_token
+            migration_script.downgrade_ops_list[-1].downgrade_token = (
+                downgrade_token
+            )
             migration_script._needs_render = True
         else:
             migration_script._upgrade_ops.append(

alembic/autogenerate/compare.py

@@ -983,7 +983,7 @@ def _normalize_computed_default(sqltext: str) -> str:
 
     """
 
-    return re.sub(r"[ \(\)'\"`\[\]]", "", sqltext).lower()
+    return re.sub(r"[ \(\)'\"`\[\]\t\r\n]", "", sqltext).lower()
 
 
 def _compare_computed_default(

alembic/autogenerate/render.py

@@ -187,9 +187,11 @@ def _render_create_table_comment(
         prefix=_alembic_autogenerate_prefix(autogen_context),
         tname=op.table_name,
         comment="%r" % op.comment if op.comment is not None else None,
-        existing="%r" % op.existing_comment
-        if op.existing_comment is not None
-        else None,
+        existing=(
+            "%r" % op.existing_comment
+            if op.existing_comment is not None
+            else None
+        ),
         schema="'%s'" % op.schema if op.schema is not None else None,
         indent="    ",
     )
@@ -216,9 +218,11 @@ def _render_drop_table_comment(
     return templ.format(
         prefix=_alembic_autogenerate_prefix(autogen_context),
         tname=op.table_name,
-        existing="%r" % op.existing_comment
-        if op.existing_comment is not None
-        else None,
+        existing=(
+            "%r" % op.existing_comment
+            if op.existing_comment is not None
+            else None
+        ),
         schema="'%s'" % op.schema if op.schema is not None else None,
         indent="    ",
     )
@@ -275,6 +279,9 @@ def _add_table(autogen_context: AutogenContext, op: ops.CreateTableOp) -> str:
         prefixes = ", ".join("'%s'" % p for p in table._prefixes)
         text += ",\nprefixes=[%s]" % prefixes
 
+    if op.if_not_exists is not None:
+        text += ",\nif_not_exists=%r" % bool(op.if_not_exists)
+
     text += "\n)"
     return text
 
@@ -287,6 +294,10 @@ def _drop_table(autogen_context: AutogenContext, op: ops.DropTableOp) -> str:
     }
     if op.schema:
         text += ", schema=%r" % _ident(op.schema)
+
+    if op.if_exists is not None:
+        text += ", if_exists=%r" % bool(op.if_exists)
+
     text += ")"
     return text
 
@@ -320,6 +331,8 @@ def _add_index(autogen_context: AutogenContext, op: ops.CreateIndexOp) -> str:
     assert index.table is not None
 
     opts = _render_dialect_kwargs_items(autogen_context, index)
+    if op.if_not_exists is not None:
+        opts.append("if_not_exists=%r" % bool(op.if_not_exists))
     text = tmpl % {
         "prefix": _alembic_autogenerate_prefix(autogen_context),
         "name": _render_gen_name(autogen_context, index.name),
@@ -328,9 +341,11 @@ def _add_index(autogen_context: AutogenContext, op: ops.CreateIndexOp) -> str:
             _get_index_rendered_expressions(index, autogen_context)
         ),
         "unique": index.unique or False,
-        "schema": (", schema=%r" % _ident(index.table.schema))
-        if index.table.schema
-        else "",
+        "schema": (
+            (", schema=%r" % _ident(index.table.schema))
+            if index.table.schema
+            else ""
+        ),
         "kwargs": ", " + ", ".join(opts) if opts else "",
     }
     return text
@@ -350,6 +365,8 @@ def _drop_index(autogen_context: AutogenContext, op: ops.DropIndexOp) -> str:
             "table_name=%(table_name)r%(schema)s%(kwargs)s)"
         )
     opts = _render_dialect_kwargs_items(autogen_context, index)
+    if op.if_exists is not None:
+        opts.append("if_exists=%r" % bool(op.if_exists))
     text = tmpl % {
         "prefix": _alembic_autogenerate_prefix(autogen_context),
         "name": _render_gen_name(autogen_context, op.index_name),
@@ -592,9 +609,11 @@ def _get_index_rendered_expressions(
     idx: Index, autogen_context: AutogenContext
 ) -> List[str]:
     return [
-        repr(_ident(getattr(exp, "name", None)))
-        if isinstance(exp, sa_schema.Column)
-        else _render_potential_expr(exp, autogen_context, is_index=True)
+        (
+            repr(_ident(getattr(exp, "name", None)))
+            if isinstance(exp, sa_schema.Column)
+            else _render_potential_expr(exp, autogen_context, is_index=True)
+        )
         for exp in idx.expressions
     ]
 
@@ -1075,9 +1094,11 @@ def _render_check_constraint(
         )
     return "%(prefix)sCheckConstraint(%(sqltext)s%(opts)s)" % {
         "prefix": _sqlalchemy_autogenerate_prefix(autogen_context),
-        "opts": ", " + (", ".join("%s=%s" % (k, v) for k, v in opts))
-        if opts
-        else "",
+        "opts": (
+            ", " + (", ".join("%s=%s" % (k, v) for k, v in opts))
+            if opts
+            else ""
+        ),
         "sqltext": _render_potential_expr(
             constraint.sqltext, autogen_context, wrap_in_text=False
         ),

alembic/command.py

@@ -49,7 +49,7 @@ def init(
 
     :param config: a :class:`.Config` object.
 
-    :param directory: string path of the target directory
+    :param directory: string path of the target directory.
 
     :param template: string name of the migration environment template to
      use.
@@ -174,7 +174,7 @@ def revision(
      will be applied to the structure generated by the revision process
      where it can be altered programmatically.   Note that unlike all
      the other parameters, this option is only available via programmatic
-     use of :func:`.command.revision`
+     use of :func:`.command.revision`.
 
     """
 
@@ -315,9 +315,11 @@ def merge(
 
     :param config: a :class:`.Config` instance
 
-    :param message: string message to apply to the revision
+    :param revisions: The revisions to merge.
 
-    :param branch_label: string label name to apply to the new revision
+    :param message: string message to apply to the revision.
+
+    :param branch_label: string label name to apply to the new revision.
 
     :param rev_id: hardcoded revision identifier instead of generating a new
      one.
@@ -370,9 +372,10 @@ def upgrade(
 
     :param config: a :class:`.Config` instance.
 
-    :param revision: string revision target or range for --sql mode
+    :param revision: string revision target or range for --sql mode. May be
+     ``"heads"`` to target the most recent revision(s).
 
-    :param sql: if True, use ``--sql`` mode
+    :param sql: if True, use ``--sql`` mode.
 
     :param tag: an arbitrary "tag" that can be intercepted by custom
      ``env.py`` scripts via the :meth:`.EnvironmentContext.get_tag_argument`
@@ -413,9 +416,10 @@ def downgrade(
 
     :param config: a :class:`.Config` instance.
 
-    :param revision: string revision target or range for --sql mode
+    :param revision: string revision target or range for --sql mode. May
+     be ``"base"`` to target the first revision.
 
-    :param sql: if True, use ``--sql`` mode
+    :param sql: if True, use ``--sql`` mode.
 
     :param tag: an arbitrary "tag" that can be intercepted by custom
      ``env.py`` scripts via the :meth:`.EnvironmentContext.get_tag_argument`
@@ -449,12 +453,13 @@ def downgrade(rev, context):
         script.run_env()
 
 
-def show(config, rev):
+def show(config: Config, rev: str) -> None:
     """Show the revision(s) denoted by the given symbol.
 
     :param config: a :class:`.Config` instance.
 
-    :param revision: string revision target
+    :param rev: string revision target. May be ``"current"`` to show the
+     revision(s) currently applied in the database.
 
     """
 
@@ -484,7 +489,7 @@ def history(
 
     :param config: a :class:`.Config` instance.
 
-    :param rev_range: string revision range
+    :param rev_range: string revision range.
 
     :param verbose: output in verbose mode.
 
@@ -543,7 +548,9 @@ def _display_current_history(rev, context):
         _display_history(config, script, base, head)
 
 
-def heads(config, verbose=False, resolve_dependencies=False):
+def heads(
+    config: Config, verbose: bool = False, resolve_dependencies: bool = False
+) -> None:
     """Show current available heads in the script directory.
 
     :param config: a :class:`.Config` instance.
@@ -568,7 +575,7 @@ def heads(config, verbose=False, resolve_dependencies=False):
         )
 
 
-def branches(config, verbose=False):
+def branches(config: Config, verbose: bool = False) -> None:
     """Show current branch points.
 
     :param config: a :class:`.Config` instance.
@@ -638,7 +645,9 @@ def stamp(
     :param config: a :class:`.Config` instance.
 
     :param revision: target revision or list of revisions.   May be a list
-     to indicate stamping of multiple branch heads.
+     to indicate stamping of multiple branch heads; may be ``"base"``
+     to remove all revisions from the table or ``"heads"`` to stamp the
+     most recent revision(s).
 
      .. note:: this parameter is called "revisions" in the command line
         interface.
@@ -728,7 +737,7 @@ def ensure_version(config: Config, sql: bool = False) -> None:
 
     :param config: a :class:`.Config` instance.
 
-    :param sql: use ``--sql`` mode
+    :param sql: use ``--sql`` mode.
 
      .. versionadded:: 1.7.6
 

alembic/config.py

@@ -221,23 +221,20 @@ def get_template_directory(self) -> str:
     @overload
     def get_section(
         self, name: str, default: None = ...
-    ) -> Optional[Dict[str, str]]:
-        ...
+    ) -> Optional[Dict[str, str]]: ...
 
     # "default" here could also be a TypeVar
     # _MT = TypeVar("_MT", bound=Mapping[str, str]),
     # however mypy wasn't handling that correctly (pyright was)
     @overload
     def get_section(
         self, name: str, default: Dict[str, str]
-    ) -> Dict[str, str]:
-        ...
+    ) -> Dict[str, str]: ...
 
     @overload
     def get_section(
         self, name: str, default: Mapping[str, str]
-    ) -> Union[Dict[str, str], Mapping[str, str]]:
-        ...
+    ) -> Union[Dict[str, str], Mapping[str, str]]: ...
 
     def get_section(
         self, name: str, default: Optional[Mapping[str, str]] = None
@@ -313,14 +310,12 @@ def get_section_option(
             return default
 
     @overload
-    def get_main_option(self, name: str, default: str) -> str:
-        ...
+    def get_main_option(self, name: str, default: str) -> str: ...
 
     @overload
     def get_main_option(
         self, name: str, default: Optional[str] = None
-    ) -> Optional[str]:
-        ...
+    ) -> Optional[str]: ...
 
     def get_main_option(
         self, name: str, default: Optional[str] = None

alembic/ddl/_autogen.py

@@ -287,18 +287,22 @@ def __init__(
             self.target_table,
             tuple(self.target_columns),
         ) + (
-            (None if onupdate.lower() == "no action" else onupdate.lower())
-            if onupdate
-            else None,
-            (None if ondelete.lower() == "no action" else ondelete.lower())
-            if ondelete
-            else None,
+            (
+                (None if onupdate.lower() == "no action" else onupdate.lower())
+                if onupdate
+                else None
+            ),
+            (
+                (None if ondelete.lower() == "no action" else ondelete.lower())
+                if ondelete
+                else None
+            ),
             # convert initially + deferrable into one three-state value
-            "initially_deferrable"
-            if initially and initially.lower() == "deferred"
-            else "deferrable"
-            if deferrable
-            else "not deferrable",
+            (
+                "initially_deferrable"
+                if initially and initially.lower() == "deferred"
+                else "deferrable" if deferrable else "not deferrable"
+            ),
         )
 
     @util.memoized_property