Category overhaul (#20)

Reviewed-on: #20
Co-authored-by: Mathias <mathias2784@web.de>

src/db_utils.py

@@ -1,20 +1,16 @@
-import csv
-from pathlib import Path
 from typing import Any
 
-from sqlalchemy.orm import Session
-
-from src.models._common import BaseModelDb
+from sqlalchemy.orm import DeclarativeBase, Session
 
 
-def _query_existing(
-    session: Session, DbModel: type[BaseModelDb], query_parameters: dict[str, Any]
-) -> BaseModelDb | None:
+def _query_existing[DbModelT: DeclarativeBase](
+    session: Session, DbModel: type[DbModelT], query_parameters: dict[str, Any]
+) -> DbModelT | None:
     query = session.query(DbModel).filter_by(**query_parameters)
     return query.first()
 
 
-def _upsert[DbModelT: BaseModelDb](
+def upsert[DbModelT: DeclarativeBase](
     session: Session,
     DbModel: type[DbModelT],
     parameters_existing: dict[str, Any],
@@ -28,7 +24,6 @@ def _upsert[DbModelT: BaseModelDb](
         if do_update:
             for key, value in parameters_new.items():
                 setattr(existing_db_row, key, value)
-        assert isinstance(existing_db_row, DbModel)
         return existing_db_row
 
     new_db_row = DbModel(**parameters_new)
@@ -37,8 +32,3 @@ def _upsert[DbModelT: BaseModelDb](
     if do_commit:
         session.commit()
     return new_db_row
-
-
-def _reader_raw(path: Path):
-    with path.open() as fid:
-        return list(csv.DictReader(fid))

src/domain_utils.py

@@ -0,0 +1,149 @@
+from datetime import date, timedelta
+from decimal import Decimal
+
+from sqlalchemy.orm import Session
+
+from src.models.category import Category, CategoryBudget, CategoryBudgetDb, CategoryDb
+
+ONE_DAY = timedelta(days=1)
+
+
+def find_category_db(session: Session, category: Category | None) -> CategoryDb | None:
+    """Find a CategoryDb in the database given a Pydantic Category object.
+
+    Recursively finds parent categories to build the full hierarchy path.
+    Returns None if any part of the hierarchy doesn't exist.
+    """
+    if category is None:
+        return None
+
+    def find_existing(node: Category) -> CategoryDb | None:
+        if node.parent is None:
+            parent_id = None
+        else:
+            parent_db = find_existing(node.parent)
+            if parent_db is None:
+                return None
+            parent_id = parent_db.id
+
+        return (
+            session.query(CategoryDb)
+            .filter_by(name=node.name, parent_id=parent_id)
+            .filter(CategoryDb.valid_to.is_(None))
+            .one_or_none()
+        )
+
+    return find_existing(category)
+
+
+def set_category_budget(session: Session, category_budget: CategoryBudget):
+    """Set or update a category budget, handling overlaps correctly.
+
+    This function handles three cases:
+    1. No overlap: Add the new budget alongside existing ones
+    2. Partial overlap: Split the existing budget and add appropriate parts + new budget
+    3. Full overlap: Replace the existing budget entirely with the new one
+
+    Args:
+        session: SQLAlchemy session
+        category_budget: The budget to set/update
+
+    Raises:
+        ValueError: If the category doesn't exist in the database
+    """
+    # Find the category in the database
+    category_db = find_category_db(session, category_budget.category)
+    if category_db is None:
+        raise ValueError(
+            f"No matching category in database for category: {category_budget.category.to_str()}"
+        )
+
+    new_start = category_budget.valid_from
+    new_end = category_budget.valid_to
+    new_amount = category_budget.amount_eur
+
+    # Helper to add a budget row
+    def _add_row(amount_eur: Decimal, valid_from: date | None, valid_to: date | None):
+        return CategoryBudgetDb(
+            category_id=category_db.id,
+            amount_eur=amount_eur,
+            valid_from=valid_from,
+            valid_to=valid_to,
+        )
+
+    # Helper to check if two date ranges overlap
+    def _ranges_overlap(
+        start1: date | None, end1: date | None, start2: date | None, end2: date | None
+    ) -> bool:
+        """Check if two date ranges overlap."""
+        range1_unbounded = start1 is None and end1 is None
+        range2_unbounded = start2 is None and end2 is None
+
+        # A fully unbounded budget acts as a default alongside bounded budgets.
+        if range1_unbounded and range2_unbounded:
+            return True
+        if range1_unbounded or range2_unbounded:
+            return False
+
+        # None on one side of a partially bounded range means infinity. Date
+        # endpoints are inclusive, so equal endpoints also overlap.
+        starts_before_end1 = end1 is None or start2 is None or start2 <= end1
+        starts_before_end2 = end2 is None or start1 is None or start1 <= end2
+        return starts_before_end1 and starts_before_end2
+
+    # Helper to find overlapping sub-range
+    def _overlap_range(
+        start1: date | None, end1: date | None, start2: date | None, end2: date | None
+    ) -> tuple[date | None, date | None]:
+        """Return the overlapping sub-range of two ranges."""
+        o_start = max((s for s in (start1, start2) if s is not None), default=None)
+        o_end = min((e for e in (end1, end2) if e is not None), default=None)
+        return (o_start, o_end)
+
+    existing_budgets = (
+        session.query(CategoryBudgetDb).filter_by(category_id=category_db.id).all()
+    )
+
+    def _remove_and_split_budget(budget: CategoryBudgetDb):
+        """Remove the overlapping parts of an existing budget and add back non-overlapping parts."""
+        overlap_start, overlap_end = _overlap_range(
+            new_start, new_end, budget.valid_from, budget.valid_to
+        )
+
+        # Keep the old budget's portion before the new range, if any.
+        if overlap_start is not None and (
+            budget.valid_from is None or budget.valid_from < overlap_start
+        ):
+            session.add(
+                _add_row(
+                    budget.amount_eur,
+                    budget.valid_from,
+                    overlap_start - ONE_DAY,
+                )
+            )
+
+        # Keep the old budget's portion after the new range, if any.
+        if overlap_end is not None and (
+            budget.valid_to is None or overlap_end < budget.valid_to
+        ):
+            session.add(
+                _add_row(
+                    budget.amount_eur,
+                    overlap_end + ONE_DAY,
+                    budget.valid_to,
+                )
+            )
+
+    # Process each existing budget
+    for existing_budget in existing_budgets:
+        if not _ranges_overlap(
+            new_start, new_end, existing_budget.valid_from, existing_budget.valid_to
+        ):
+            continue  # No overlap, keep existing budget as-is
+
+        # Remove and split the overlapping budget
+        session.delete(existing_budget)
+        _remove_and_split_budget(existing_budget)
+
+    # Add the requested budget once, even if it replaced multiple existing rows.
+    session.add(_add_row(new_amount, new_start, new_end))

src/ingest/b4w.py

@@ -1,10 +1,13 @@
+from datetime import UTC, datetime
 from pathlib import Path
 
 from sqlalchemy.orm import Session
 
-from src.ingest._common import _reader_raw, _upsert
+from src.db_utils import upsert
+from src.ingest.common import _reader_raw
 from src.ingest.transactions import consolidate_transactions, map_b4w_to_transaction
-from src.models.b4w import B4wDb, B4wExport, Category, CategoryDb
+from src.models.b4w import B4wDb, B4wExport
+from src.models.category import Category, CategoryDb, upsert_category
 
 
 def reader_b4w(path: Path) -> list[B4wExport]:
@@ -12,23 +15,91 @@ def reader_b4w(path: Path) -> list[B4wExport]:
     return list(map(B4wExport.model_validate, raw))
 
 
-def upsert_category(
-    session: Session, category: Category | None, do_commit=True
-) -> CategoryDb | None:
-    if category is None:
-        return None
-    parameters = {
-        "name": category.name,
-        "parent": upsert_category(session, category.parent),
-    }
-    return _upsert(
-        session,
-        CategoryDb,
-        parameters,
-        parameters,
-        do_update=False,
-        do_commit=do_commit,
+def _utc_datetime(value: datetime | None) -> datetime:
+    if value is None:
+        return datetime.now(UTC)
+    if value.tzinfo is None or value.utcoffset() is None:
+        return value.replace(tzinfo=UTC)
+    return value.astimezone(UTC)
+
+
+def _ensure_after_valid_from(category: CategoryDb, effective_at: datetime) -> None:
+    if category.valid_from is None:
+        return
+    valid_from = _utc_datetime(category.valid_from)
+    if effective_at <= valid_from:
+        raise ValueError("The action time must be later than valid_from")
+
+
+def change_category(
+    session: Session,
+    category_id: int,
+    replacement: Category,
+    effective_at: datetime | None = None,
+    do_commit: bool = True,
+) -> CategoryDb:
+    """Close an active category version and start its replacement version."""
+    current = (
+        session.query(CategoryDb).filter_by(id=category_id, valid_to=None).one_or_none()
     )
+    if current is None:
+        raise ValueError(f"No active category found with id {category_id}")
+
+    action_time = _utc_datetime(effective_at)
+    _ensure_after_valid_from(current, action_time)
+    parent = upsert_category(session, replacement.parent, do_commit=False)
+    parent_id = parent.id if parent else None
+
+    if current.name == replacement.name and current.parent_id == parent_id:
+        return current
+
+    replacement_active = (
+        session.query(CategoryDb)
+        .filter_by(name=replacement.name, parent_id=parent_id, valid_to=None)
+        .one_or_none()
+    )
+
+    current.valid_to = action_time
+    current.last_action = "changed"
+    session.flush()
+
+    if replacement_active is None:
+        replacement_active = CategoryDb(
+            name=replacement.name,
+            parent=parent,
+            valid_from=action_time,
+            valid_to=None,
+            last_action="changed",
+        )
+        session.add(replacement_active)
+        session.flush()
+
+    if do_commit:
+        session.commit()
+    return replacement_active
+
+
+def retire_category(
+    session: Session,
+    category_id: int,
+    effective_at: datetime | None = None,
+    do_commit: bool = True,
+) -> CategoryDb:
+    """Close an active category version without creating a replacement."""
+    category = (
+        session.query(CategoryDb).filter_by(id=category_id, valid_to=None).one_or_none()
+    )
+    if category is None:
+        raise ValueError(f"No active category found with id {category_id}")
+
+    action_time = _utc_datetime(effective_at)
+    _ensure_after_valid_from(category, action_time)
+    category.valid_to = action_time
+    category.last_action = "retired"
+    session.flush()
+    if do_commit:
+        session.commit()
+    return category
 
 
 def upsert_b4w(
@@ -54,7 +125,7 @@ def upsert_b4w(
         "notes": data.notes,
     }
 
-    return _upsert(
+    return upsert(
         session,
         B4wDb,
         parameters_existing,

src/ingest/comdirect.py

@@ -6,18 +6,18 @@ from typing import cast
 from sqlalchemy.orm import Session
 
 from settings import BANK_ACCOUNTS
-from src.ingest._common import _upsert
+from src.db_utils import upsert
 from src.ingest.transactions import (
     consolidate_transactions,
     map_comdirect_giro_to_transaction,
 )
-from src.models._common import Csv2Dict, CsV2DictMulti
 from src.models.comdirect import (
     ComdirectCreditCard,
     ComdirectDepot,
     ComdirectGiro,
     ComdirectGiroDb,
 )
+from src.models.common import Csv2Dict, CsV2DictMulti
 from src.models.settings import Account, Source
 
 PATTERN_ACCOUNT_NAME = r'^"Umsätze ([^"]+)";"Zeitraum: .*$'
@@ -73,6 +73,10 @@ def _reader_raw_comdirect(path: Path) -> CsV2DictMulti:
     account_name: str | None = None
     header: list[str] = []
     result: CsV2DictMulti = {}
+    # Comdirect groups "new" transactions (marked with "neu") under a header
+    # line that carries only their Buchungstag; remember it until the next
+    # transaction row for the same account.
+    pending_book_date: dict[str, str] = {}
     for line in lines:
         if expect_next == EXPECT_LINE.ACCOUNT_NAME:
             matches = re.findall(PATTERN_ACCOUNT_NAME, line)
@@ -91,13 +95,18 @@ def _reader_raw_comdirect(path: Path) -> CsV2DictMulti:
                 expect_next = EXPECT_LINE.DATA
         elif expect_next == EXPECT_LINE.DATA:
             data = re.findall(PATTERN_DATA, line)
-            if data:
-                assert account_name is not None
-                result[account_name].append(
-                    {column: value for column, value in zip(header, data)}
-                )
-            else:
+            if not data:
                 expect_next = EXPECT_LINE.ACCOUNT_NAME
+            elif len(data) == 1:
+                # Group header line (single Buchungstag for the "neu" rows below).
+                assert account_name is not None
+                pending_book_date[account_name] = data[0]
+            else:
+                assert account_name is not None
+                row = {column: value for column, value in zip(header, data)}
+                if data[0] == "neu" and account_name in pending_book_date:
+                    row["Buchungstag"] = pending_book_date.pop(account_name)
+                result[account_name].append(row)
         else:
             expect_next = EXPECT_LINE.ACCOUNT_NAME
     return result
@@ -128,7 +137,7 @@ def upsert_comdirect_giro(
         "text": data.text,
     }
 
-    return _upsert(
+    return upsert(
         session,
         ComdirectGiroDb,
         parameters_existing,

src/ingest/common.py

@@ -0,0 +1,7 @@
+import csv
+from pathlib import Path
+
+
+def _reader_raw(path: Path):
+    with path.open() as fid:
+        return list(csv.DictReader(fid))

src/ingest/transactions.py

@@ -4,9 +4,9 @@ from sqlalchemy import select
 from sqlalchemy.dialects.sqlite import insert as sqlite_insert
 from sqlalchemy.orm import Session
 
-from src.models._common import BaseModelDb
 from src.models.b4w import B4wDb
 from src.models.comdirect import ComdirectGiroDb
+from src.models.common import BaseModelDb
 from src.models.transactions import Transaction, TransactionDb
 
 

src/models/__init__.py

@@ -1,9 +1,47 @@
-from src.models.b4w import B4wExport as B4wExport
-from src.models.b4w import Category as Category
-from src.models.comdirect import ComdirectCreditCard as ComdirectCreditCard
-from src.models.comdirect import ComdirectDepot as ComdirectDepot
-from src.models.comdirect import ComdirectGiro as ComdirectGiro
-from src.models.settings import Account as Account
-from src.models.settings import Source as Source
-from src.models.transactions import Transaction as Transaction
-from src.models.transactions import TransactionDb as TransactionDb
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+_EXPORTS = {
+    "B4wExport": ".b4w",
+    "Category": ".category",
+    "CategoryBudget": ".category",
+    "CategoryBudgetDb": ".category",
+    "CategoryDb": ".category",
+    "ComdirectCreditCard": ".comdirect",
+    "ComdirectDepot": ".comdirect",
+    "ComdirectGiro": ".comdirect",
+    "Account": ".settings",
+    "Source": ".settings",
+    "Transaction": ".transactions",
+    "TransactionDb": ".transactions",
+}
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    value = getattr(import_module(module_name, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted([*globals(), *__all__])
+
+
+if TYPE_CHECKING:
+    from src.models.b4w import B4wExport as B4wExport
+    from src.models.category import Category as Category
+    from src.models.category import CategoryBudget as CategoryBudget
+    from src.models.category import CategoryBudgetDb as CategoryBudgetDb
+    from src.models.category import CategoryDb as CategoryDb
+    from src.models.comdirect import ComdirectCreditCard as ComdirectCreditCard
+    from src.models.comdirect import ComdirectDepot as ComdirectDepot
+    from src.models.comdirect import ComdirectGiro as ComdirectGiro
+    from src.models.settings import Account as Account
+    from src.models.settings import Source as Source
+    from src.models.transactions import Transaction as Transaction
+    from src.models.transactions import TransactionDb as TransactionDb

src/models/b4w.py

@@ -2,19 +2,26 @@ from datetime import date
 from decimal import Decimal
 
 from pydantic import Field, computed_field, field_validator
-from sqlalchemy import Date, ForeignKey, Integer, String, UniqueConstraint
+from sqlalchemy import (
+    Date,
+    ForeignKey,
+    Integer,
+    String,
+)
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from src.constants import IBAN_PATTERN, Currency
-from src.models._common import (
-    BaseModelDb,
+from src.models.category import Category, CategoryDb
+from src.models.common import (
     ExportBaseModel,
     IngestdbBase,
     Sign,
-    _hash,
     date2str,
+    hashify,
 )
 
+__all__ = ["B4wDb", "B4wExport", "Category", "CategoryDb"]
+
 
 class B4wExport(ExportBaseModel):
     id: int = Field(alias="Id1", description="internal B4w ID")
@@ -59,7 +66,7 @@ class B4wExport(ExportBaseModel):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def hash_id(self) -> str:
-        return _hash(self.id)
+        return hashify(self.id)
 
     @property
     def amount_signed(self) -> Decimal:
@@ -87,56 +94,6 @@ class B4wExport(ExportBaseModel):
         return category
 
 
-class Category(ExportBaseModel):
-    name: str = Field(pattern=r"[^:\r\n]+")
-    parent: Category | None = None
-
-    @computed_field  # type: ignore[prop-decorator]
-    @property
-    def hash_id(self) -> str:
-        return _hash(self.name, self.parent)
-
-    @classmethod
-    def from_str(cls, s: str) -> Category | None:
-        if not s:
-            return None
-        components = s.split(":")
-        name = components[-1]
-        rest = ":".join(components[:-1])
-        return cls(name=name, parent=cls.from_str(rest))
-
-    def to_str(self) -> str | None:
-        if not self.parent:
-            return self.name
-        else:
-            return f"{self.parent.to_str()}:{self.name}"
-
-    def __str__(self):
-        return self.to_str()
-
-    def __repr__(self):
-        return f'Category.from_str("{self.__str__()}")'
-
-
-class CategoryDb(BaseModelDb):
-    __tablename__ = "category"
-    __table_args__ = (
-        UniqueConstraint("name", "parent_id", name="uq_category_name_parent"),
-    )
-
-    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String, nullable=False)
-    parent_id: Mapped[int | None] = mapped_column(
-        ForeignKey("category.id"), nullable=True
-    )
-
-    # Relationships
-    parent = relationship(
-        "CategoryDb", remote_side="CategoryDb.id", back_populates="children"
-    )
-    children = relationship("CategoryDb", back_populates="parent")
-
-
 class B4wDb(IngestdbBase):
     __tablename__ = "import_b4w"
 

src/models/category.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, timedelta
+from decimal import Decimal
+from typing import Self
+
+from pydantic import BaseModel, Field, computed_field, model_validator
+from sqlalchemy import (
+    Date,
+    DateTime,
+    ForeignKey,
+    Index,
+    Numeric,
+    String,
+    TypeDecorator,
+    text,
+)
+from sqlalchemy.orm import Mapped, Session, mapped_column, relationship
+
+from src.db_utils import upsert
+from src.models.common import BaseModelDb, ExportBaseModel, hashify
+
+
+class UTCDateTime(TypeDecorator[datetime]):
+    """Store UTC timestamps and return timezone-aware UTC values on every dialect."""
+
+    impl = DateTime
+    cache_ok = True
+
+    def load_dialect_impl(self, dialect):
+        return dialect.type_descriptor(DateTime(timezone=True))
+
+    def process_bind_param(self, value: datetime | None, dialect):
+        if value is None:
+            return None
+        if value.tzinfo is None or value.utcoffset() is None:
+            return value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)
+
+    def process_result_value(self, value: datetime | None, dialect):
+        if value is None:
+            return None
+        if value.tzinfo is None or value.utcoffset() is None:
+            return value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)
+
+
+class Category(ExportBaseModel):
+    name: str = Field(pattern=r"[^:\r\n]+")
+    parent: Category | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def hash_id(self) -> str:
+        return hashify(self.name, self.parent)
+
+    @classmethod
+    def from_str(cls, s: str) -> Category | None:
+        if not s:
+            return None
+        components = s.split(":")
+        name = components[-1]
+        rest = ":".join(components[:-1])
+        return cls(name=name, parent=cls.from_str(rest))
+
+    def to_str(self) -> str | None:
+        if not self.parent:
+            return self.name
+        else:
+            return f"{self.parent.to_str()}:{self.name}"
+
+    def __str__(self):
+        return self.to_str()
+
+    def __repr__(self):
+        return f'Category.from_str("{self.__str__()}")'
+
+
+class CategoryDb(BaseModelDb):
+    __tablename__ = "category"
+    __table_args__ = (
+        Index(
+            "uq_category_active_name_parent",
+            "name",
+            "parent_id",
+            unique=True,
+            sqlite_where=text("valid_to IS NULL AND parent_id IS NOT NULL"),
+            postgresql_where=text("valid_to IS NULL AND parent_id IS NOT NULL"),
+        ),
+        Index(
+            "uq_category_active_root_name",
+            "name",
+            unique=True,
+            sqlite_where=text("valid_to IS NULL AND parent_id IS NULL"),
+            postgresql_where=text("valid_to IS NULL AND parent_id IS NULL"),
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    parent_id: Mapped[int | None] = mapped_column(
+        ForeignKey("category.id"), nullable=True
+    )
+    valid_from: Mapped[datetime | None] = mapped_column(
+        UTCDateTime(),
+        nullable=True,
+        info={
+            "description": "UTC start of validity; NULL means valid since the indefinite past."
+        },
+    )
+    valid_to: Mapped[datetime | None] = mapped_column(
+        UTCDateTime(),
+        nullable=True,
+        info={
+            "description": "UTC end of validity; NULL means the version is currently valid."
+        },
+    )
+    last_action: Mapped[str] = mapped_column(
+        String,
+        nullable=False,
+        default="created",
+        server_default="created",
+        info={
+            "description": "Most recent lifecycle action recorded for this category version."
+        },
+    )
+
+    # Relationships
+    parent = relationship(
+        "CategoryDb", remote_side="CategoryDb.id", back_populates="children"
+    )
+    children = relationship("CategoryDb", back_populates="parent")
+    budgets: Mapped[list[CategoryBudgetDb]] = relationship(back_populates="category")
+
+
+def upsert_category(
+    session: Session, category: Category | None, do_commit: bool = True
+) -> CategoryDb | None:
+    if category is None:
+        return None
+
+    parent = upsert_category(session, category.parent, do_commit=False)
+    parameters = {"name": category.name, "parent": parent}
+    matching_rows = session.query(CategoryDb).filter_by(
+        name=category.name, parent_id=parent.id if parent else None
+    )
+    active = matching_rows.filter(CategoryDb.valid_to.is_(None)).one_or_none()
+    if active is not None:
+        return active
+
+    historical = (
+        matching_rows.filter(CategoryDb.valid_to.is_not(None))
+        .order_by(CategoryDb.valid_to.desc())
+        .first()
+    )
+    valid_from = None
+    last_action = "created"
+    if historical is not None:
+        valid_from = datetime.now(UTC)
+        if historical.valid_to is not None:
+            previous_valid_to = historical.valid_to
+            if (
+                previous_valid_to.tzinfo is None
+                or previous_valid_to.utcoffset() is None
+            ):
+                previous_valid_to = previous_valid_to.replace(tzinfo=UTC)
+            else:
+                previous_valid_to = previous_valid_to.astimezone(UTC)
+            valid_from = max(valid_from, previous_valid_to + timedelta(microseconds=1))
+        last_action = "changed"
+
+    parameters_new = {
+        **parameters,
+        "valid_from": valid_from,
+        "valid_to": None,
+        "last_action": last_action,
+    }
+    return upsert(
+        session,
+        CategoryDb,
+        {**parameters, "valid_to": None},
+        parameters_new,
+        do_update=False,
+        do_commit=do_commit,
+    )
+
+
+class CategoryBudget(BaseModel):
+    category: Category
+    amount_eur: Decimal = Field(gt=0, decimal_places=2)
+    valid_from: date | None = Field(
+        default=None, description="Start of validity. None means unbounded"
+    )
+    valid_to: date | None = Field(
+        default=None, description="End of validity. None means unbounded"
+    )
+
+    @model_validator(mode="after")
+    def validate_date_range(self) -> Self:
+        if (
+            self.valid_from is not None
+            and self.valid_to is not None
+            and self.valid_from > self.valid_to
+        ):
+            raise ValueError(
+                f"`valid_from` ({self.valid_from}) and valid_to ({self.valid_to}) are nor in order"
+            )
+        return self
+
+
+class CategoryBudgetDb(BaseModelDb):
+    """Budget amount for a category, optionally bounded to a time window.
+
+    Satellite table to ``category``: one category may have several budgets
+    (e.g. one per month). ``valid_from``/``valid_to`` are nullable; ``None``
+    means unbounded on that side.
+    """
+
+    __tablename__ = "category_budget"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    category_id: Mapped[int] = mapped_column(
+        ForeignKey("category.id"), nullable=False, index=True
+    )
+    amount_eur: Mapped[Decimal] = mapped_column(Numeric(12, 2), nullable=False)
+    valid_from: Mapped[date | None] = mapped_column(Date, nullable=True, default=None)
+    valid_to: Mapped[date | None] = mapped_column(Date, nullable=True, default=None)
+
+    # relationship
+    category = relationship("CategoryDb", back_populates="budgets")

src/models/comdirect.py

@@ -5,14 +5,14 @@ from pydantic import ConfigDict, Field, computed_field, field_validator
 from sqlalchemy import Date, String
 from sqlalchemy.orm import Mapped, mapped_column
 
-from src.models._common import (
+from src.models.common import (
     ExportBaseModel,
     IngestdbBase,
-    _hash,
     _parse_date_german,
     _parse_decimal_german,
     date2str,
     decimal2str,
+    hashify,
 )
 
 
@@ -72,7 +72,7 @@ class ComdirectGiro(ComdirectBase):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def hash_id(self) -> str:
-        return _hash(self.date_val, self.date_book, self.text)
+        return hashify(self.date_val, self.date_book, self.text)
 
     @field_validator("date_book", mode="before")
     @classmethod

src/models/common.py

@@ -8,7 +8,7 @@ from sqlalchemy import Date, Numeric, String
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 
-def _hash(*args):
+def hashify(*args):
     raw = "".join(str(args))
     return hashlib.sha256(raw.encode()).hexdigest()
 

src/models/transactions.py

@@ -5,7 +5,7 @@ from pydantic import Field, computed_field
 from sqlalchemy import Date, ForeignKey, Index, Integer, String, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
-from src.models._common import ExportBaseModel, IngestdbBase, _hash, date2str
+from src.models.common import ExportBaseModel, IngestdbBase, date2str, hashify
 
 
 class Transaction(ExportBaseModel):
@@ -33,7 +33,7 @@ class Transaction(ExportBaseModel):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def hash_id(self) -> str:
-        return _hash(
+        return hashify(
             self.source,
             self.account_iban,
             self.date_valid,