Avoid D103 linter warnings via script.py.mako

Added a basic docstring to the migration template files so that the
upgrade/downgrade methods pass the D103 linter check which requires a
docstring for public functions.  Pull request courtesy Peter Cock.

Fixes: #1567
Closes: #1568
Pull-request: #1568
Pull-request-sha: fa3bcd5

Change-Id: I14b7863dfef01edca9c94d8dff4109efd274df3c

Author: peterjc

alembic/templates/async/script.py.mako

@@ -19,8 +19,10 @@ depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
 
 
 def upgrade() -> None:
+    """Upgrade schema."""
     ${upgrades if upgrades else "pass"}
 
 
 def downgrade() -> None:
+    """Downgrade schema."""
     ${downgrades if downgrades else "pass"}

alembic/templates/generic/script.py.mako

@@ -19,8 +19,10 @@ depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
 
 
 def upgrade() -> None:
+    """Upgrade schema."""
     ${upgrades if upgrades else "pass"}
 
 
 def downgrade() -> None:
+    """Downgrade schema."""
     ${downgrades if downgrades else "pass"}

alembic/templates/multidb/script.py.mako

@@ -22,10 +22,12 @@ depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
 
 
 def upgrade(engine_name: str) -> None:
+    """Upgrade schema."""
     globals()["upgrade_%s" % engine_name]()
 
 
 def downgrade(engine_name: str) -> None:
+    """Downgrade schema."""
     globals()["downgrade_%s" % engine_name]()
 
 <%
@@ -38,10 +40,12 @@ def downgrade(engine_name: str) -> None:
 % for db_name in re.split(r',\s*', db_names):
 
 def upgrade_${db_name}() -> None:
+    """Upgrade ${db_name} schema."""
     ${context.get("%s_upgrades" % db_name, "pass")}
 
 
 def downgrade_${db_name}() -> None:
+    """Downgrade ${db_name} schema."""
     ${context.get("%s_downgrades" % db_name, "pass")}
 
 % endfor

docs/build/unreleased/1567.rst

@@ -0,0 +1,7 @@
+.. change::
+    :tags: bug, environment
+    :tickets: 1567
+
+    Added a basic docstring to the migration template files so that the
+    upgrade/downgrade methods pass the D103 linter check which requires a
+    docstring for public functions.  Pull request courtesy Peter Cock.

tests/test_script_production.py

@@ -657,16 +657,17 @@ def process_revision_directives(context, rev, generate_revisions):
             result = handle.read()
         assert (
             (
-                """
+                '''
 def upgrade() -> None:
+    """Upgrade schema."""
     # ### commands auto generated by Alembic - please adjust! ###
     op.create_table('test_table',
     sa.Column('id', sa.Integer(), nullable=False),
     sa.Column('name', sa.String(length=50), nullable=False),
     sa.PrimaryKeyConstraint('id')
     )
     # ### end Alembic commands ###
-"""
+'''
             )
             in result
         )