Add ORM models for the pixel grids

- add Grid, Pixel, and AddressPixelAssociation ORM models
- each Grid belongs to a City an is characterized by the side_length
  of all the square Pixels contained in it
- Pixels aggregate Addresses => many-to-many relationship (that is
  modeled with SQLAlchemy's Association Pattern to implement a couple
  of constraints)

src/urban_meal_delivery/db/__init__.py

@@ -1,11 +1,14 @@
 """Provide the ORM models and a connection to the database."""
 
-from urban_meal_delivery.db.addresses import Address  # noqa:F401
-from urban_meal_delivery.db.cities import City  # noqa:F401
-from urban_meal_delivery.db.connection import make_engine  # noqa:F401
-from urban_meal_delivery.db.connection import make_session_factory  # noqa:F401
-from urban_meal_delivery.db.couriers import Courier  # noqa:F401
-from urban_meal_delivery.db.customers import Customer  # noqa:F401
-from urban_meal_delivery.db.meta import Base  # noqa:F401
-from urban_meal_delivery.db.orders import Order  # noqa:F401
-from urban_meal_delivery.db.restaurants import Restaurant  # noqa:F401
+from urban_meal_delivery.db.addresses import Address
+from urban_meal_delivery.db.addresses_pixels import AddressPixelAssociation
+from urban_meal_delivery.db.cities import City
+from urban_meal_delivery.db.connection import make_engine
+from urban_meal_delivery.db.connection import make_session_factory
+from urban_meal_delivery.db.couriers import Courier
+from urban_meal_delivery.db.customers import Customer
+from urban_meal_delivery.db.grids import Grid
+from urban_meal_delivery.db.meta import Base
+from urban_meal_delivery.db.orders import Order
+from urban_meal_delivery.db.pixels import Pixel
+from urban_meal_delivery.db.restaurants import Restaurant

src/urban_meal_delivery/db/addresses.py

@@ -46,6 +46,8 @@ class Address(meta.Base):
             '-180 <= longitude AND longitude <= 180',
             name='longitude_between_180_degrees',
         ),
+        # Needed by a `ForeignKeyConstraint` in `AddressPixelAssociation`.
+        sa.UniqueConstraint('id', 'city_id'),
         sa.CheckConstraint(
             '30000 <= zip_code AND zip_code <= 99999', name='valid_zip_code',
         ),
@@ -60,12 +62,12 @@ class Address(meta.Base):
         back_populates='pickup_address',
         foreign_keys='[Order._pickup_address_id]',
     )
-
     orders_delivered = orm.relationship(
         'Order',
         back_populates='delivery_address',
         foreign_keys='[Order._delivery_address_id]',
     )
+    pixels = orm.relationship('AddressPixelAssociation', back_populates='address')
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         """Create a new address."""

src/urban_meal_delivery/db/addresses_pixels.py

@@ -0,0 +1,56 @@
+"""Model for the many-to-many relationship between `Address` and `Pixel` objects."""
+
+import sqlalchemy as sa
+from sqlalchemy import orm
+
+from urban_meal_delivery.db import meta
+
+
+class AddressPixelAssociation(meta.Base):
+    """Association pattern between `Address` and `Pixel`.
+
+    This approach is needed here mainly because it implicitly
+    updates the `_city_id` and `_grid_id` columns.
+
+    Further info:
+        https://docs.sqlalchemy.org/en/stable/orm/basic_relationships.html#association-object  # noqa:E501
+    """
+
+    __tablename__ = 'addresses_pixels'
+
+    # Columns
+    _address_id = sa.Column('address_id', sa.Integer, primary_key=True)
+    _city_id = sa.Column('city_id', sa.SmallInteger, nullable=False)
+    _grid_id = sa.Column('grid_id', sa.SmallInteger, nullable=False)
+    _pixel_id = sa.Column('pixel_id', sa.Integer, primary_key=True)
+
+    # Constraints
+    __table_args__ = (
+        # An `Address` can only be on a `Grid` ...
+        sa.ForeignKeyConstraint(
+            ['address_id', 'city_id'],
+            ['addresses.id', 'addresses.city_id'],
+            onupdate='RESTRICT',
+            ondelete='RESTRICT',
+        ),
+        # ... if their `.city` attributes match.
+        sa.ForeignKeyConstraint(
+            ['grid_id', 'city_id'],
+            ['grids.id', 'grids.city_id'],
+            onupdate='RESTRICT',
+            ondelete='RESTRICT',
+        ),
+        # Each `Address` can only be on a `Grid` once.
+        sa.UniqueConstraint('address_id', 'grid_id'),
+        # An association must reference an existing `Grid`-`Pixel` pair.
+        sa.ForeignKeyConstraint(
+            ['pixel_id', 'grid_id'],
+            ['pixels.id', 'pixels.grid_id'],
+            onupdate='RESTRICT',
+            ondelete='RESTRICT',
+        ),
+    )
+
+    # Relationships
+    address = orm.relationship('Address', back_populates='pixels')
+    pixel = orm.relationship('Pixel', back_populates='addresses')

src/urban_meal_delivery/db/cities.py

@@ -45,6 +45,7 @@ class City(meta.Base):
 
     # Relationships
     addresses = orm.relationship('Address', back_populates='city')
+    grids = orm.relationship('Grid', back_populates='city')
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         """Create a new city."""

src/urban_meal_delivery/db/grids.py

@@ -0,0 +1,48 @@
+"""Provide the ORM's `Grid` model."""
+
+import sqlalchemy as sa
+from sqlalchemy import orm
+
+from urban_meal_delivery.db import meta
+
+
+class Grid(meta.Base):
+    """A grid of `Pixel`s to partition a `City`.
+
+    A grid is characterized by the uniform size of the `Pixel`s it contains.
+    That is configures via the `Grid.side_length` attribute.
+    """
+
+    __tablename__ = 'grids'
+
+    # Columns
+    id = sa.Column(  # noqa:WPS125
+        sa.SmallInteger, primary_key=True, autoincrement=True,
+    )
+    _city_id = sa.Column('city_id', sa.SmallInteger, nullable=False)
+    side_length = sa.Column(sa.SmallInteger, nullable=False, unique=True)
+
+    # Constraints
+    __table_args__ = (
+        sa.ForeignKeyConstraint(
+            ['city_id'], ['cities.id'], onupdate='RESTRICT', ondelete='RESTRICT',
+        ),
+        # Needed by a `ForeignKeyConstraint` in `address_pixel_association`.
+        sa.UniqueConstraint('id', 'city_id'),
+    )
+
+    # Relationships
+    city = orm.relationship('City', back_populates='grids')
+    pixels = orm.relationship('Pixel', back_populates='grid')
+
+    def __repr__(self) -> str:
+        """Non-literal text representation."""
+        return '<{cls}: {area}>'.format(
+            cls=self.__class__.__name__, area=self.pixel_area,
+        )
+
+    # Convenience properties
+    @property
+    def pixel_area(self) -> float:
+        """The area of a `Pixel` on the grid in square kilometers."""
+        return (self.side_length ** 2) / 1_000_000  # noqa:WPS432

src/urban_meal_delivery/db/pixels.py

@@ -0,0 +1,59 @@
+"""Provide the ORM's `Pixel` model."""
+
+import sqlalchemy as sa
+from sqlalchemy import orm
+
+from urban_meal_delivery.db import meta
+
+
+class Pixel(meta.Base):
+    """A pixel in a `Grid`.
+
+    Square pixels aggregate `Address` objects within a `City`.
+    Every `Address` belongs to exactly one `Pixel` in a `Grid`.
+
+    Every `Pixel` has a unique "coordinate" within the `Grid`.
+    """
+
+    __tablename__ = 'pixels'
+
+    # Columns
+    id = sa.Column(sa.Integer, primary_key=True, autoincrement=True)  # noqa:WPS125
+    _grid_id = sa.Column('grid_id', sa.SmallInteger, nullable=False, index=True)
+    n_x = sa.Column(sa.SmallInteger, nullable=False, index=True)
+    n_y = sa.Column(sa.SmallInteger, nullable=False, index=True)
+
+    # Constraints
+    __table_args__ = (
+        sa.ForeignKeyConstraint(
+            ['grid_id'], ['grids.id'], onupdate='RESTRICT', ondelete='RESTRICT',
+        ),
+        sa.CheckConstraint('0 <= n_x', name='n_x_is_positive'),
+        sa.CheckConstraint('0 <= n_y', name='n_y_is_positive'),
+        # Needed by a `ForeignKeyConstraint` in `AddressPixelAssociation`.
+        sa.UniqueConstraint('id', 'grid_id'),
+        # Each coordinate within the same `grid` is used at most once.
+        sa.UniqueConstraint('grid_id', 'n_x', 'n_y'),
+    )
+
+    # Relationships
+    grid = orm.relationship('Grid', back_populates='pixels')
+    addresses = orm.relationship('AddressPixelAssociation', back_populates='pixel')
+
+    def __repr__(self) -> str:
+        """Non-literal text representation."""
+        return '<{cls}: ({x}, {y})>'.format(
+            cls=self.__class__.__name__, x=self.n_x, y=self.n_y,
+        )
+
+    # Convenience properties
+
+    @property
+    def side_length(self) -> int:
+        """The length of one side of a pixel in meters."""
+        return self.grid.side_length
+
+    @property
+    def area(self) -> float:
+        """The area of a pixel in square kilometers."""
+        return self.grid.pixel_area