let migrations have descriptions (piccolo-orm#166)

* let migrations have descriptions

* added docs

Author: dantownsend

docs/src/piccolo/migrations/create.rst

@@ -17,7 +17,7 @@ migration filename is a timestamp, which also serves as the migration ID.
 .. code-block:: bash
 
     piccolo_migrations/
-        2018-09-04T19:44:09.py
+        2021-08-06T16-22-51-415781.py
 
 The contents of an empty migration file looks like this:
 
@@ -26,11 +26,13 @@ The contents of an empty migration file looks like this:
     from piccolo.apps.migrations.auto import MigrationManager
 
 
-    ID = '2018-09-04T19:44:09'
+    ID = '2021-08-06T16:22:51:415781'
+    VERSION = "0.29.0" # The version of Piccolo used to create it
+    DESCRIPTION = "Optional description"
 
 
     async def forwards():
-        manager = MigrationManager(migration_id=ID)
+        manager = MigrationManager(migration_id=ID, app_name="my_app", description=DESCRIPTION)
 
         def run():
             print(f"running {ID}")
@@ -52,7 +54,9 @@ This is a **bad example**:
 
     from ..tables import Band
 
-    ID = '2018-09-04T19:44:09'
+    ID = '2021-08-06T16:22:51:415781'
+    VERSION = "0.29.0" # The version of Piccolo used to create it
+    DESCRIPTION = "Optional description"
 
 
     async def forwards():
@@ -69,6 +73,8 @@ someone runs your migrations in the future, they will get different results.
 Make your migrations completely independent of other code, so they're
 self contained and repeatable.
 
+-------------------------------------------------------------------------------
+
 Auto migrations
 ---------------
 
@@ -102,3 +108,19 @@ Auto migrations can accommodate most schema changes. There may be some rare edge
 cases where a single migration is trying to do too much in one go, and fails.
 To avoid these situations, create auto migrations frequently, and keep them
 fairly small.
+
+-------------------------------------------------------------------------------
+
+Migration descriptions
+----------------------
+
+To make the migrations more memorable, you can give them a description. Inside
+the migration file, you can set a ``DESCRIPTION`` global variable manually, or
+can specify it when creating the migration:
+
+.. code-block:: bash
+
+    piccolo migrations new my_app --auto --desc="Adding name column"
+
+The Piccolo CLI will then use this description where appropriate when dealing
+with migrations.

piccolo/apps/migrations/auto/migration_manager.py

@@ -126,6 +126,7 @@ class MigrationManager:
 
     migration_id: str = ""
     app_name: str = ""
+    description: str = ""
     add_tables: t.List[DiffableTable] = field(default_factory=list)
     drop_tables: t.List[DiffableTable] = field(default_factory=list)
     rename_tables: t.List[RenameTable] = field(default_factory=list)

piccolo/apps/migrations/commands/check.py

@@ -10,6 +10,7 @@
 class MigrationStatus:
     app_name: str
     migration_id: str
+    description: str
     has_ran: bool
 
 
@@ -47,9 +48,15 @@ async def get_migration_statuses(self) -> t.List[MigrationStatus]:
                     )
                     .run()
                 )
+                description = getattr(
+                    migration_modules[_id], "DESCRIPTION", "-"
+                )
                 migration_statuses.append(
                     MigrationStatus(
-                        app_name=app_name, migration_id=_id, has_ran=has_ran
+                        app_name=app_name,
+                        migration_id=_id,
+                        description=description,
+                        has_ran=has_ran,
                     )
                 )
 
@@ -76,10 +83,13 @@ async def run(self):
         Prints out the migrations which have and haven't ran.
         """
         print("Listing migrations ...")
+        desc_length = 40
+        id_length = 26
 
         print(
             f'{get_fixed_length_string("APP NAME")} | '
-            f'{get_fixed_length_string("MIGRATION_ID")} | RAN'
+            f'{get_fixed_length_string("MIGRATION_ID", id_length)} | '
+            f'{get_fixed_length_string("DESCRIPTION", desc_length)} | RAN'
         )
 
         migration_statuses = await self.get_migration_statuses()
@@ -89,10 +99,18 @@ async def run(self):
                 migration_status.app_name
             )
             fixed_length_id = get_fixed_length_string(
-                migration_status.migration_id
+                migration_status.migration_id, length=id_length
+            )
+            fixed_length_description = get_fixed_length_string(
+                migration_status.description, desc_length
             )
             has_ran = migration_status.has_ran
-            print(f"{fixed_length_app_name} | {fixed_length_id} | {has_ran}")
+            print(
+                f"{fixed_length_app_name} | "
+                f"{fixed_length_id} | "
+                f"{fixed_length_description} | "
+                f"{has_ran}"
+            )
 
 
 async def check(app_name: str = "all"):

piccolo/apps/migrations/commands/new.py

@@ -89,7 +89,7 @@ class NoChanges(Exception):
 
 
 async def _create_new_migration(
-    app_config: AppConfig, auto=False
+    app_config: AppConfig, auto: bool = False, description: str = ""
 ) -> NewMigrationMeta:
     """
     Creates a new migration file on disk.
@@ -122,10 +122,11 @@ async def _create_new_migration(
             extra_imports=extra_imports,
             extra_definitions=extra_definitions,
             app_name=app_config.app_name,
+            description=description,
         )
     else:
         file_contents = render_template(
-            migration_id=meta.migration_id, auto=False
+            migration_id=meta.migration_id, auto=False, description=description
         )
 
     # Beautify the file contents a bit.
@@ -178,14 +179,17 @@ async def get_alter_statements(
 ###############################################################################
 
 
-async def new(app_name: str, auto: bool = False):
+async def new(app_name: str, auto: bool = False, desc: str = ""):
     """
     Creates a new migration file in the migrations folder.
 
     :param app_name:
         The app to create a migration for.
     :param auto:
         Auto create the migration contents.
+    :param desc:
+        A description of what the migration does, for example 'adding name
+        column'.
 
     """
     print("Creating new migration ...")
@@ -198,7 +202,9 @@ async def new(app_name: str, auto: bool = False):
 
     _create_migrations_folder(app_config.migrations_folder_path)
     try:
-        await _create_new_migration(app_config=app_config, auto=auto)
+        await _create_new_migration(
+            app_config=app_config, auto=auto, description=desc
+        )
     except NoChanges:
         print("No changes detected - exiting.")
         sys.exit(0)

piccolo/apps/migrations/commands/templates/migration.py.jinja

@@ -11,10 +11,11 @@ from piccolo.apps.migrations.auto import MigrationManager
 
 ID = '{{ migration_id }}'
 VERSION = '{{ version }}'
+DESCRIPTION = '{{ description }}'
 
 
 async def forwards():
-    manager = MigrationManager(migration_id=ID, app_name="{{ app_name }}")
+    manager = MigrationManager(migration_id=ID, app_name="{{ app_name }}", description=DESCRIPTION)
     {% if auto %}
     {% for alter_statement in alter_statements %}
     {{ alter_statement }}

piccolo/conf/apps.py

@@ -16,6 +16,10 @@
 
 
 class MigrationModule(ModuleType):
+    ID: str
+    VERSION: str
+    DESCRIPTION: str
+
     @staticmethod
     async def forwards() -> None:
         pass

piccolo/utils/printing.py

@@ -2,6 +2,10 @@ def get_fixed_length_string(string: str, length=20) -> str:
     """
     Add spacing to the end of the string so it's a fixed length.
     """
-    spacing = "".join([" " for i in range(length - len(string))])
-    fixed_length_string = f"{string}{spacing}"
+    if len(string) > length:
+        fixed_length_string = string[: length - 3] + "..."
+    else:
+        spacing = "".join([" " for i in range(length - len(string))])
+        fixed_length_string = f"{string}{spacing}"
+
     return fixed_length_string

tests/utils/test_printing.py

@@ -4,6 +4,18 @@
 
 
 class TestGetFixedLengthString(TestCase):
-    def test_get_fixed_length_string(self):
+    def test_extra_padding(self):
+        """
+        Make sure the additional padding is added.
+        """
         result = get_fixed_length_string(string="hello", length=10)
         self.assertEqual(result, "hello     ")
+
+    def test_truncation(self):
+        """
+        Make sure the string is truncated to the fixed length if it's too long.
+        """
+        result = get_fixed_length_string(
+            string="this is a very, very long string", length=20
+        )
+        self.assertEqual(result, "this is a very, v...")