Add CLI script to gridify all cities

- reorganize `urban_meal_delivery.console` into a sub-package
- move `tests.db.conftest` fixtures into `tests.conftest`
  => some integration tests regarding CLI scripts need a database
- add `urban_meal_delivery.console.decorators.db_revision` decorator
  to ensure the database is at a certain state before a CLI script runs
- refactor the `urban_meal_delivery.db.grids.Grid.gridify()` constructor:
  - bug fix: even empty `Pixel`s end up in the database temporarily
    => create `Pixel` objects only if an `Address` is to be assigned
       to it
  - streamline code and docstring
  - add further test cases

src/urban_meal_delivery/console/__init__.py

@@ -0,0 +1,9 @@
+"""Provide CLI scripts for the project."""
+
+from urban_meal_delivery.console import gridify
+from urban_meal_delivery.console import main
+
+
+cli = main.entry_point
+
+cli.add_command(gridify.gridify)

src/urban_meal_delivery/console/decorators.py

@@ -0,0 +1,37 @@
+"""Utils for the CLI scripts."""
+
+import functools
+import os
+import subprocess  # noqa:S404
+import sys
+from typing import Any, Callable
+
+import click
+
+
+def db_revision(rev: str) -> Callable:  # pragma: no cover -> easy to check visually
+    """A decorator ensuring the database is at a given revision."""
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def ensure(*args: Any, **kwargs: Any) -> Any:  # noqa:WPS430
+            """Do not execute the `func` if the revision does not match."""
+            if not os.getenv('TESTING'):
+                result = subprocess.run(  # noqa:S603,S607
+                    ['alembic', 'current'],
+                    capture_output=True,
+                    check=False,
+                    encoding='utf8',
+                )
+
+                if not result.stdout.startswith(rev):
+                    click.echo(
+                        click.style(f'Database is not at revision {rev}', fg='red'),
+                    )
+                    sys.exit(1)
+
+            return func(*args, **kwargs)
+
+        return ensure
+
+    return decorator

src/urban_meal_delivery/console/gridify.py

@@ -0,0 +1,48 @@
+"""CLI script to create pixel grids."""
+
+import click
+
+from urban_meal_delivery import config
+from urban_meal_delivery import db
+from urban_meal_delivery.console import decorators
+
+
+@click.command()
+@decorators.db_revision('888e352d7526')
+def gridify() -> None:  # pragma: no cover  note:b1f68d24
+    """Create grids for all cities.
+
+    This command creates grids with pixels of various
+    side lengths (specified in `urban_meal_delivery.config`).
+
+    Pixels are only generated if they contain at least one
+    (pickup or delivery) address.
+
+    All data are persisted to the database.
+    """
+    cities = db.session.query(db.City).all()
+    click.echo(f'{len(cities)} cities retrieved from the database')
+
+    for city in cities:
+        click.echo(f'\nCreating grids for {city.name}')
+
+        for side_length in config.GRID_SIDE_LENGTHS:
+            click.echo(f'Creating grid with a side length of {side_length} meters')
+
+            grid = db.Grid.gridify(city=city, side_length=side_length)
+            db.session.add(grid)
+
+            click.echo(f' -> created {len(grid.pixels)} pixels')
+
+        # The number of assigned addresses is the same across different `side_length`s.
+        db.session.flush()  # necessary for the query to work
+        n_assigned = (
+            db.session.query(db.AddressPixelAssociation)
+            .filter(db.AddressPixelAssociation.grid_id == grid.id)
+            .count()
+        )
+        click.echo(
+            f'=> assigned {n_assigned} out of {len(city.addresses)} addresses in {city.name}',  # noqa:E501
+        )
+
+    db.session.commit()

src/urban_meal_delivery/console/main.py

@@ -0,0 +1,37 @@
+"""The entry point for all CLI scripts in the project."""
+
+from typing import Any
+
+import click
+from click import core as cli_core
+
+import urban_meal_delivery
+
+
+def show_version(ctx: cli_core.Context, _param: Any, value: bool) -> None:
+    """Show the package's version."""
+    # If --version / -V is NOT passed in,
+    # continue with the command.
+    if not value or ctx.resilient_parsing:
+        return
+
+    # Mimic the colors of `poetry version`.
+    pkg_name = click.style(urban_meal_delivery.__pkg_name__, fg='green')  # noqa:WPS609
+    version = click.style(urban_meal_delivery.__version__, fg='blue')  # noqa:WPS609
+    # Include a warning for development versions.
+    warning = click.style(' (development)', fg='red') if '.dev' in version else ''
+    click.echo(f'{pkg_name}, version {version}{warning}')
+    ctx.exit()
+
+
+@click.group()
+@click.option(
+    '--version',
+    '-V',
+    is_flag=True,
+    callback=show_version,
+    is_eager=True,
+    expose_value=False,
+)
+def entry_point() -> None:
+    """The urban-meal-delivery research project."""