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

tests/console/__init__.py

@@ -0,0 +1,5 @@
+"""Test the CLI scripts in the urban-meal-delivery package.
+
+Some tests require a database. Therefore, the corresponding code is excluded
+from coverage reporting with "pragma: no cover" (grep:b1f68d24).
+"""

tests/console/conftest.py

@@ -0,0 +1,10 @@
+"""Fixture for testing the CLI scripts."""
+
+import pytest
+from click import testing as click_testing
+
+
+@pytest.fixture
+def cli() -> click_testing.CliRunner:
+    """Initialize Click's CLI Test Runner."""
+    return click_testing.CliRunner()

tests/console/test_gridify.py

@@ -0,0 +1,41 @@
+"""Integration test for the `urban_meal_delivery.console.gridify` module."""
+
+import pytest
+
+import urban_meal_delivery
+from urban_meal_delivery import db
+from urban_meal_delivery.console import gridify
+
+
+@pytest.mark.db
+def test_four_pixels_with_two_addresses(
+    cli, db_session, monkeypatch, city, make_address,
+):
+    """Two `Address` objects in distinct `Pixel` objects.
+
+    This is roughly the same test case as
+    `tests.db.test_grids.test_four_pixels_with_two_addresses`.
+    The difference is that the result is written to the database.
+    """
+    # Create two `Address` objects in distinct `Pixel`s.
+    city.addresses = [
+        # One `Address` in the lower-left `Pixel`, ...
+        make_address(latitude=48.8357377, longitude=2.2517412),
+        # ... and another one in the upper-right one.
+        make_address(latitude=48.8898312, longitude=2.4357622),
+    ]
+
+    db_session.add(city)
+    db_session.commit()
+
+    side_length = max(city.total_x // 2, city.total_y // 2) + 1
+
+    # Hack the configuration regarding the grids to be created.
+    monkeypatch.setattr(urban_meal_delivery.config, 'GRID_SIDE_LENGTHS', [side_length])
+
+    result = cli.invoke(gridify.gridify)
+
+    assert result.exit_code == 0
+
+    assert db_session.query(db.Grid).count() == 1
+    assert db_session.query(db.Pixel).count() == 2

tests/console/test_main.py

@@ -0,0 +1,103 @@
+"""Test the package's top-level `umd` CLI command."""
+
+import click
+import pytest
+
+from urban_meal_delivery.console import main
+
+
+class TestShowVersion:
+    """Test `console.main.show_version()`.
+
+    The function is used as a callback to a click command option.
+
+    `show_version()` prints the name and version of the installed package to
+    stdout. The output looks like this: "{pkg_name}, version {version}".
+
+    Development (= non-final) versions are indicated by appending a
+    " (development)" to the output.
+    """
+
+    # pylint:disable=no-self-use
+
+    @pytest.fixture
+    def ctx(self) -> click.Context:
+        """Context around the `main.entry_point` Command."""
+        return click.Context(main.entry_point)
+
+    def test_no_version(self, capsys, ctx):
+        """Test the early exit branch without any output."""
+        main.show_version(ctx, _param='discarded', value=False)
+
+        captured = capsys.readouterr()
+
+        assert captured.out == ''
+
+    def test_final_version(self, capsys, ctx, monkeypatch):
+        """For final versions, NO "development" warning is emitted."""
+        version = '1.2.3'
+        monkeypatch.setattr(main.urban_meal_delivery, '__version__', version)
+
+        with pytest.raises(click.exceptions.Exit):
+            main.show_version(ctx, _param='discarded', value=True)
+
+        captured = capsys.readouterr()
+
+        assert captured.out.endswith(f', version {version}\n')
+
+    def test_develop_version(self, capsys, ctx, monkeypatch):
+        """For develop versions, a warning thereof is emitted."""
+        version = '1.2.3.dev0'
+        monkeypatch.setattr(main.urban_meal_delivery, '__version__', version)
+
+        with pytest.raises(click.exceptions.Exit):
+            main.show_version(ctx, _param='discarded', value=True)
+
+        captured = capsys.readouterr()
+
+        assert captured.out.strip().endswith(f', version {version} (development)')
+
+
+class TestCLIWithoutCommand:
+    """Test the `umd` CLI utility, invoked without any specific command.
+
+    The test cases are integration tests.
+    Therefore, they are not considered for coverage reporting.
+    """
+
+    # pylint:disable=no-self-use
+
+    @pytest.mark.no_cover
+    def test_no_options(self, cli):
+        """Exit with 0 status code and no output if run without options."""
+        result = cli.invoke(main.entry_point)
+
+        assert result.exit_code == 0
+
+    # The following test cases validate the --version / -V option.
+
+    version_options = ('--version', '-V')
+
+    @pytest.mark.no_cover
+    @pytest.mark.parametrize('option', version_options)
+    def test_final_version(self, cli, monkeypatch, option):
+        """For final versions, NO "development" warning is emitted."""
+        version = '1.2.3'
+        monkeypatch.setattr(main.urban_meal_delivery, '__version__', version)
+
+        result = cli.invoke(main.entry_point, option)
+
+        assert result.exit_code == 0
+        assert result.output.strip().endswith(f', version {version}')
+
+    @pytest.mark.no_cover
+    @pytest.mark.parametrize('option', version_options)
+    def test_develop_version(self, cli, monkeypatch, option):
+        """For develop versions, a warning thereof is emitted."""
+        version = '1.2.3.dev0'
+        monkeypatch.setattr(main.urban_meal_delivery, '__version__', version)
+
+        result = cli.invoke(main.entry_point, option)
+
+        assert result.exit_code == 0
+        assert result.output.strip().endswith(f', version {version} (development)')