dbzero-modelkit 0.1.1.1.0__py3-none-any.whl

dbzero_modelkit/__init__.py

@@ -0,0 +1,28 @@
+"""Reusable dbzero-backed data model utilities."""
+
+from dbzero_modelkit.active import ActiveBase, ActiveIndex
+from dbzero_modelkit.calendars import (
+    Calendar,
+    MonthCalendar,
+    get_date_from_month_index,
+    get_month_index,
+)
+from dbzero_modelkit.language import LanguageCode, ML_String
+from dbzero_modelkit.month_store import MonthStore
+from dbzero_modelkit.object_lock import ObjectLock
+from dbzero_modelkit.queues import FQ_Item, FiFoQueue
+
+__all__ = [
+    "ActiveBase",
+    "ActiveIndex",
+    "Calendar",
+    "FQ_Item",
+    "FiFoQueue",
+    "LanguageCode",
+    "ML_String",
+    "MonthCalendar",
+    "MonthStore",
+    "ObjectLock",
+    "get_date_from_month_index",
+    "get_month_index",
+]

dbzero_modelkit/active.py

@@ -0,0 +1,235 @@
+"""Active-window model primitives backed by dbzero indexes."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from typing import Iterable, Optional
+
+import dbzero as db0
+
+from dbzero_modelkit.rpc_integration import rpc as db0_rpc
+from dbzero_modelkit.time_utils import normalize_end, normalize_start
+
+
+@db0.memo(no_default_tags=True)
+class ActiveBase:
+    """Base object for models that are active only within a period of time."""
+
+    def __init__(
+        self,
+        active_from: datetime | date | None = None,
+        expires_on: datetime | date | None = None,
+    ) -> None:
+        self.active_from = active_from
+        self.expires_on = expires_on
+
+    @property
+    def active(self) -> bool:
+        """Return whether this object is active at the current date and time."""
+        return self.is_active()
+
+    @db0.immutable
+    def is_active(self, as_of: datetime | date | None = None) -> bool:
+        """Return whether as_of is within the active period."""
+        if not as_of:
+            as_of = datetime.now()
+
+        if isinstance(as_of, date) and not isinstance(as_of, datetime):
+            as_of = datetime.combine(as_of, datetime.min.time())
+
+        active_from_dt = normalize_start(self.active_from) if self.active_from is not None else None
+        expires_on_dt = normalize_end(self.expires_on) if self.expires_on is not None else None
+
+        if active_from_dt is None and expires_on_dt is None:
+            return True
+
+        if active_from_dt and as_of < active_from_dt:
+            return False
+
+        if expires_on_dt and as_of > expires_on_dt:
+            return False
+
+        return True
+
+    @db0.immutable
+    def expired(self, date_and_time: datetime) -> bool:
+        """Return whether the object is expired at date_and_time."""
+        return not self.is_active(date_and_time)
+
+    @db0.immutable
+    def overlaps(self, other: "ActiveBase") -> bool:
+        """Return whether this active period overlaps another one."""
+        start_self = normalize_start(self.active_from)
+        end_self = normalize_end(self.expires_on)
+        start_other = normalize_start(other.active_from)
+        end_other = normalize_end(other.expires_on)
+        return start_self <= end_other and start_other <= end_self
+
+    @db0.immutable
+    def is_adjacent(self, other: "ActiveBase", max_gap: timedelta = timedelta(0)) -> bool:
+        """Return whether this period is adjacent to another one within max_gap."""
+        if self.overlaps(other):
+            return False
+
+        start_self = normalize_start(self.active_from)
+        end_self = normalize_end(self.expires_on)
+        start_other = normalize_start(other.active_from)
+        end_other = normalize_end(other.expires_on)
+
+        if end_self < start_other:
+            return start_other - end_self <= max_gap
+
+        if end_other < start_self:
+            return start_self - end_other <= max_gap
+
+        return False
+
+    @db0.immutable
+    def can_merge(self, other: "ActiveBase", max_gap: timedelta = timedelta(0)) -> bool:
+        """Return True when periods overlap or are adjacent within max_gap."""
+        return self.overlaps(other) or self.is_adjacent(other, max_gap=max_gap)
+
+    @db0.immutable
+    def merge(
+        self,
+        other: "ActiveBase",
+        max_gap: timedelta = timedelta(0),
+    ) -> Optional[tuple[datetime | date | None, datetime | date | None]]:
+        """Return merged active bounds or None when periods cannot be merged."""
+        if not self.can_merge(other, max_gap=max_gap):
+            return None
+
+        if self.active_from is None or other.active_from is None:
+            merged_active_from = None
+        elif normalize_start(self.active_from) <= normalize_start(other.active_from):
+            merged_active_from = self.active_from
+        else:
+            merged_active_from = other.active_from
+
+        if self.expires_on is None or other.expires_on is None:
+            merged_expires_on = None
+        elif normalize_end(self.expires_on) >= normalize_end(other.expires_on):
+            merged_expires_on = self.expires_on
+        else:
+            merged_expires_on = other.expires_on
+
+        return merged_active_from, merged_expires_on
+
+
+@db0.memo(no_default_tags=True)
+class ActiveIndex:
+    """Container indexing ActiveBase-compatible objects by active period."""
+
+    def __init__(self) -> None:
+        self.__ix_active_from = db0.index()
+        self.__ix_expires_on = db0.index()
+
+    @db0_rpc.remote
+    def add(self, obj: ActiveBase) -> None:
+        """Add an ActiveBase-compatible object to both active-window indexes."""
+        self.__ix_active_from.add(obj.active_from, obj)
+        self.__ix_expires_on.add(obj.expires_on, obj)
+
+    @db0_rpc.remote
+    def remove(self, obj: ActiveBase) -> None:
+        """Remove an ActiveBase-compatible object from both active-window indexes."""
+        self.__ix_active_from.remove(obj.active_from, obj)
+        self.__ix_expires_on.remove(obj.expires_on, obj)
+
+    def _update_db0_index_attr(
+        self,
+        db0_index: db0.index,
+        obj: ActiveBase,
+        property_name: str,
+        value: datetime | date | None,
+    ) -> None:
+        """Update one indexed active-window attribute and reindex the object."""
+        if not db0_index.sort(db0.find(obj), desc=True, null_first=True):
+            raise RuntimeError("Given ActiveBase object doesn't exist in any index.")
+        self.remove(obj)
+        setattr(obj, property_name, value)
+        self.add(obj)
+
+    @db0_rpc.remote
+    def update(self, obj: ActiveBase, **kwargs: datetime | date | None) -> None:
+        """Change active-window attributes and update the corresponding indexes."""
+        if "active_from" in kwargs:
+            self._update_db0_index_attr(
+                db0_index=self.__ix_active_from,
+                obj=obj,
+                property_name="active_from",
+                value=kwargs["active_from"],
+            )
+
+        if "expires_on" in kwargs:
+            self._update_db0_index_attr(
+                db0_index=self.__ix_expires_on,
+                obj=obj,
+                property_name="expires_on",
+                value=kwargs["expires_on"],
+            )
+
+    @db0.immutable
+    def find(self, **kwargs: bool) -> Iterable:
+        """Return all indexed objects sorted by a selected active-window index."""
+        index_to_find, desc = self.__get_index_and_desc_from_kwargs(**kwargs)
+        return index_to_find.sort(index_to_find.select(), desc=desc)
+
+    @db0.immutable
+    def find_active(
+        self,
+        as_of: datetime | date | None = None,
+        sort: bool = True,
+        **kwargs: bool,
+    ) -> Iterable:
+        """Find objects active at as_of."""
+        if not as_of:
+            as_of = datetime.now()
+        index_to_find, desc = self.__get_index_and_desc_from_kwargs(**kwargs)
+        query = (
+            self.active_from_index.select(low=None, high=as_of, null_first=True),
+            self.expires_on_index.select(low=as_of, high=None, null_first=False),
+        )
+        if sort:
+            return index_to_find.sort(db0.find(query), desc=desc)
+
+        return db0.find(query)
+
+    @db0.immutable
+    def find_active_between(
+        self,
+        from_date: datetime | date,
+        to_date: Optional[datetime | date] = None,
+        sort: bool = True,
+        **kwargs: bool,
+    ) -> Iterable:
+        """Find objects active within the given date range."""
+        index_to_find, desc = self.__get_index_and_desc_from_kwargs(**kwargs)
+        query = (
+            self.active_from_index.select(low=None, high=to_date, null_first=True),
+            self.expires_on_index.select(low=from_date, high=None, null_first=False),
+        )
+        if sort:
+            return index_to_find.sort(db0.find(query), desc=desc)
+        return db0.find(query)
+
+    @property
+    def active_from_index(self):
+        """Return the active_from dbzero index."""
+        return self.__ix_active_from
+
+    @property
+    def expires_on_index(self):
+        """Return the expires_on dbzero index."""
+        return self.__ix_expires_on
+
+    def __get_index_and_desc_from_kwargs(self, **kwargs: bool):
+        """Return selected index and sort direction from keyword arguments."""
+        index_to_find_dict = {
+            "active_from": self.active_from_index,
+            "expires_on": self.expires_on_index,
+        }
+        for key, db0_index in index_to_find_dict.items():
+            if key in kwargs:
+                return db0_index, kwargs[key]
+        return self.expires_on_index, True

dbzero_modelkit/calendars.py

@@ -0,0 +1,183 @@
+"""Sparse calendar model primitives backed by dbzero."""
+
+from __future__ import annotations
+
+from calendar import monthrange
+from datetime import date as Date, timedelta
+from typing import Any, Iterable, Iterator
+
+import dbzero as db0
+
+
+def get_month_index(base_year: int, date: Date) -> int:
+    """Return the zero-based month index relative to base_year."""
+    return (date.year * 12 + date.month - base_year * 12) - 1
+
+
+def get_date_from_month_index(base_year: int, month_index: int) -> Date:
+    """Return the first day of the month for a zero-based month index."""
+    return Date(base_year + month_index // 12, month_index % 12 + 1, 1)
+
+
+@db0.memo(no_default_tags=True)
+class MonthCalendar:
+    """Single sparse month view for Calendar."""
+
+    def __init__(self, calendar: "Calendar", month_index: int, prefix: str | None = None) -> None:
+        db0.set_prefix(self, prefix)
+        self.__calendar = calendar
+        self.__index = month_index
+        self.__days = []
+        self.__max_days = monthrange(
+            calendar.base_year + month_index // 12,
+            month_index % 12 + 1,
+        )[1]
+
+    def __validate_date(self, date: Date) -> None:
+        month_index = get_month_index(self.__calendar.base_year, date)
+        if month_index != self.__index:
+            raise ValueError("Date is not in the month")
+        if self.__max_days < date.day:
+            raise ValueError("Date is out of range")
+
+    def set(self, date: Date, value: Any) -> None:
+        """Set a value for a date in this month."""
+        self.__validate_date(date)
+        if len(self.__days) <= date.day:
+            self.__days.extend([None] * (date.day - len(self.__days)))
+        self.__days[date.day - 1] = value
+
+    def get(self, date: Date) -> Any | None:
+        """Return the stored value for date, or None when unset."""
+        self.__validate_date(date)
+        if len(self.__days) >= date.day:
+            return self.__days[date.day - 1]
+        return None
+
+    def range(self, from_date: Date | None, to_date: Date | None = None) -> Iterator[Any | None]:
+        """Yield values from from_date through to_date within this month."""
+        start_day = 0
+        if from_date is not None:
+            self.__validate_date(from_date)
+            start_day = from_date.day - 1
+        end_day = self.__max_days
+        if to_date is not None:
+            self.__validate_date(to_date)
+            end_day = to_date.day
+        if start_day > end_day:
+            raise ValueError("Invalid range. 'from_date' must be before 'to_date'")
+        while start_day <= end_day - 1:
+            if start_day < len(self.__days):
+                yield self.__days[start_day]
+            else:
+                yield None
+            start_day += 1
+
+    def __iter__(self):
+        """Yield `(date, value)` pairs for set non-None days."""
+        actual_day = get_date_from_month_index(self.__calendar.base_year, self.__index)
+        for day in self.__days:
+            if day is not None:
+                yield actual_day, day
+            actual_day += timedelta(days=1)
+
+
+@db0.memo(no_default_tags=True)
+class Calendar:
+    """Sparse date calendar with lazy month creation."""
+
+    def __init__(self, base_year: int = 2025, prefix: str | None = None) -> None:
+        db0.set_prefix(self, prefix)
+        self.__months = []
+        self.__base_year = base_year
+
+    def get_month(self, date: Date, create: bool = False) -> MonthCalendar | None:
+        """Retrieve or create the MonthCalendar associated with date."""
+        self.__validate_date(date)
+        month_index = get_month_index(self.base_year, date)
+        if len(self.__months) <= month_index:
+            if create:
+                self.__months.extend([None] * (month_index - len(self.__months) + 1))
+            else:
+                return None
+        if self.__months[month_index] is None and create is True:
+            self.__months[month_index] = MonthCalendar(self, month_index)
+        return self.__months[month_index]
+
+    def date_range(
+        self,
+        from_date: Date | None = None,
+        to_date: Date | None = None,
+        reverse: bool = False,
+    ) -> Iterable[tuple[Date, Any | None]]:
+        """Yield `(date, value)` pairs for consecutive dates."""
+        if from_date is None:
+            from_date = Date(self.base_year, 1, 1)
+        else:
+            self.__validate_date(from_date)
+        if to_date is not None:
+            self.__validate_date(to_date)
+            if from_date > to_date:
+                raise ValueError("from_date should be less than to_date")
+
+        if reverse:
+            if to_date is None:
+                raise ValueError("to_date is required when iterating in reverse")
+            actual_date = to_date
+            end_date = from_date
+            delta = timedelta(days=-1)
+        else:
+            actual_date = from_date
+            end_date = to_date
+            delta = timedelta(days=1)
+
+        while True:
+            yield actual_date, self.get(actual_date)
+            if actual_date == end_date:
+                break
+            actual_date += delta
+
+    def range(
+        self,
+        from_date: Date | None = None,
+        to_date: Date | None = None,
+        reverse: bool = False,
+    ) -> Iterable[Any | None]:
+        """Yield only values from date_range."""
+        return (value for _date, value in self.date_range(from_date, to_date, reverse))
+
+    def get(self, date: Date) -> Any | None:
+        """Return the stored value for date, or None when unset."""
+        month = self.get_month(date)
+        return month.get(date) if month is not None else None
+
+    def set(self, date: Date, value: Any) -> None:
+        """Set the value for date, creating its month when needed."""
+        self.get_month(date, create=True).set(date, value)
+
+    @property
+    def base_year(self) -> int:
+        """Return the base year for this calendar."""
+        return self.__base_year
+
+    def __validate_date(self, date: Date) -> None:
+        if date.year < self.base_year:
+            raise ValueError(
+                f"Date is out of range. Date must be after year {self.base_year}. Got: {date}"
+            )
+
+    def __iter__(self):
+        """Yield `(date, value)` pairs for all set non-None days."""
+        for month in self.__months:
+            if month is not None:
+                yield from month
+
+    def is_set(self, date: Date) -> bool:
+        """Return True when the calendar value at date is truthy."""
+        return bool(self.get(date))
+
+    def find_not_set(self, dates: Iterable[Date]) -> Iterable[Date]:
+        """Yield dates that do not have a truthy calendar value."""
+        for date in dates:
+            if not self.is_set(date):
+                yield date

dbzero_modelkit/language.py

@@ -0,0 +1,61 @@
+"""Multi-language string support backed by dbzero."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import dbzero as db0
+
+
+@db0.enum(values=["LEN", "LPL", "LGER", "LFR", "LESP"])
+class LanguageCode:
+    """Common language codes used by multi-language strings."""
+
+
+@db0.memo(no_default_tags=True)
+class ML_String:
+    """Store textual information in a primary language and optional translations."""
+
+    def __init__(
+        self,
+        value: str,
+        lang_code: LanguageCode,
+        ml_versions: Optional[dict[LanguageCode, str]] = None,
+        prefix: Optional[str] = None,
+    ) -> None:
+        db0.set_prefix(self, prefix)
+        self.value = value
+        self.__lang_code = lang_code
+        self.__ml_versions = ml_versions
+
+    def __str__(self) -> str:
+        """Return the primary stored value."""
+        return self.value
+
+    def get(
+        self,
+        lang_code: Optional[LanguageCode] = None,
+        fallback_codes: Optional[list[LanguageCode]] = None,
+        default: Optional[str] = None,
+    ) -> Optional[str]:
+        """Return a requested translation, fallback translation, or default value."""
+        if lang_code is None or lang_code == self.__lang_code:
+            return self.value
+
+        if self.__ml_versions is not None:
+            if lang_code in self.__ml_versions:
+                return self.__ml_versions[lang_code]
+
+            if fallback_codes is not None:
+                for code in fallback_codes:
+                    if code in self.__ml_versions:
+                        return self.__ml_versions[code]
+
+        if fallback_codes is not None and self.__lang_code in fallback_codes:
+            return self.value
+
+        return default
+
+    def __load__(self, lang: Optional[LanguageCode] = None) -> Optional[str]:
+        """Load the requested language value, defaulting to Polish fallback."""
+        return self.get(lang, fallback_codes=[LanguageCode.LPL])

dbzero_modelkit/month_store.py

@@ -0,0 +1,139 @@
+"""Sparse month-indexed object store backed by dbzero."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any, Optional
+
+import dbzero as db0
+
+from dbzero_modelkit.rpc_integration import rpc as db0_rpc
+
+
+@db0.memo(no_default_tags=True)
+class MonthStore:
+    """General-purpose container for storing one object per month."""
+
+    def __init__(self, item_type: type, base_year: int = 2025) -> None:
+        self.__item_type = item_type
+        self.__base_year = base_year
+        self.__months = []
+
+    def __str__(self) -> str:
+        """Return a YYYY-MM span for stored months, or an empty string."""
+        span = self.get_span()
+        if not span:
+            return ""
+        start, end = span
+        return f"{start.year:04d}-{start.month:02d} - {end.year:04d}-{end.month:02d}"
+
+    def __get_index(self, month: date) -> int:
+        """Return the month index relative to the base year."""
+        return (month.year * 12 + month.month - self.__base_year * 12) - 1
+
+    @db0_rpc.remote
+    def get_month(self, month: date, create: bool = False) -> Any:
+        """Return the stored month object, optionally creating it when missing."""
+        index = self.__get_index(month)
+
+        if index < 0:
+            raise ValueError(
+                f"Month {month.year}-{month.month:02d} is before base year "
+                f"{self.__base_year}"
+            )
+
+        if index < len(self.__months):
+            existing_item = self.__months[index]
+            if existing_item is not None:
+                return existing_item
+
+        if not create:
+            raise ValueError(
+                f"No item found for month {month.year}-{month.month:02d} and create=False"
+            )
+
+        while len(self.__months) <= index:
+            self.__months.append(None)
+
+        new_item = self.__item_type()
+        self.__months[index] = new_item
+        return new_item
+
+    @db0.immutable
+    def try_get_existing_month(self, month: date) -> Optional[Any]:
+        """Return an existing month object, or None when absent."""
+        index = self.__get_index(month)
+
+        if index < 0:
+            return None
+
+        if index < len(self.__months):
+            existing_item = self.__months[index]
+            if existing_item is not None:
+                return existing_item
+
+        return None
+
+    @db0.immutable
+    def get_existing_month(self, month: date) -> Any:
+        """Return an existing month object, raising if absent."""
+        return self.get_month(month, create=False)
+
+    @db0_rpc.remote
+    def set_month(self, month: date, value: Any) -> None:
+        """Set or clear the object at a specific month."""
+        index = self.__get_index(month)
+
+        if index < 0:
+            raise ValueError(
+                f"Month {month.year}-{month.month:02d} is before base year "
+                f"{self.__base_year}"
+            )
+
+        while len(self.__months) <= index:
+            self.__months.append(None)
+
+        if value is not None and not isinstance(value, self.__item_type):
+            raise TypeError(
+                "Invalid value type for MonthStore: expected "
+                f"{self.__item_type.__name__} or None, got {type(value).__name__}"
+            )
+
+        self.__months[index] = value
+
+    def get_span(self) -> tuple[date, date] | None:
+        """Return the first and last stored month dates, or None when empty."""
+        if not self.__months:
+            return None
+
+        first_index = next((i for i, item in enumerate(self.__months) if item is not None), None)
+        if first_index is None:
+            return None
+
+        last_index = next(i for i, item in enumerate(reversed(self.__months)) if item is not None)
+        last_index = len(self.__months) - 1 - last_index
+
+        def index_to_date(idx: int) -> date:
+            year = self.__base_year + (idx // 12)
+            month = (idx % 12) + 1
+            return date(year, month, 1)
+
+        start_date = index_to_date(first_index)
+        end_date = index_to_date(last_index)
+        return start_date, end_date
+
+    def get_recent(self, count: int = 12) -> list[Any]:
+        """Return up to count stored items in reverse chronological order."""
+        recent_items = []
+        for i in range(len(self.__months) - 1, -1, -1):
+            if len(recent_items) >= count:
+                break
+            item = self.__months[i]
+            if item is not None:
+                recent_items.append(item)
+        return recent_items
+
+    @property
+    def recent(self) -> list[Any]:
+        """Return up to 12 most recent stored items."""
+        return self.get_recent(12)

dbzero_modelkit/object_lock.py

@@ -0,0 +1,41 @@
+"""Tag-based object locking utility backed by dbzero."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Iterable, Type
+
+import dbzero as db0
+
+
+@db0.memo
+class ObjectLock:
+    """General-purpose lock that holds references to locked objects."""
+
+    def __init__(self, locked_objects: Any | list[Any], duration: int = 300) -> None:
+        if not isinstance(locked_objects, list):
+            locked_objects = [locked_objects]
+        self.locked_objects = locked_objects
+        self.expires_at = datetime.now(timezone.utc) + timedelta(seconds=duration)
+        db0.tags(*locked_objects).add("LOCKED")
+
+    def unlock(self) -> None:
+        """Remove the LOCKED tag from all locked objects."""
+        db0.tags(*self.locked_objects).remove("LOCKED")
+
+    def unlock_with_error(self, error_objects: Any | list[Any] | None = None) -> None:
+        """Unlock objects and mark selected or all objects with ERROR."""
+        if error_objects is None:
+            error_targets = self.locked_objects
+        elif isinstance(error_objects, list):
+            error_targets = error_objects
+        else:
+            error_targets = [error_objects]
+
+        self.unlock()
+        if error_targets:
+            db0.tags(*error_targets).add("ERROR")
+
+    def select(self, obj_type: Type) -> Iterable:
+        """Return locked objects that are instances of obj_type."""
+        return filter(lambda obj: isinstance(obj, obj_type), self.locked_objects)

dbzero_modelkit/queues.py

@@ -0,0 +1,95 @@
+"""dbzero-backed queue model utilities."""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List, Optional
+
+import dbzero as db0
+
+
+@db0.memo
+class FQ_Item:  # pylint: disable=invalid-name
+    """Single FIFO queue entry storing keyword arguments and its integer key."""
+
+    def __init__(self, key: int, prefix: str | None = None, **kwargs) -> None:
+        db0.set_prefix(self, prefix)
+        self.__key = key
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+    @property
+    def queue_key(self) -> int:
+        """Return the index key for this queue item."""
+        return self.__key
+
+    def to_dict(self) -> Dict:
+        """Return stored item keyword arguments."""
+        return {
+            key: value
+            for key, value in vars(self).items()
+            if key != "_FQ_Item__key"
+        }
+
+
+@db0.memo
+class FiFoQueue:
+    """FIFO queue container backed by a dbzero index."""
+
+    def __init__(self) -> None:
+        self.__items = db0.index()
+        self.__next_key = 0
+
+    def is_empty(self) -> bool:
+        """Return True when the queue has no items."""
+        return len(self.__items) == 0
+
+    def push_back(self, **kwargs) -> None:
+        """Append a single element to the back of the queue."""
+        prefix = db0.get_prefix_of(self).name
+        self.__items.add(self.__next_key, FQ_Item(self.__next_key, prefix=prefix, **kwargs))
+        self.__next_key += 1
+
+    def has_item(
+        self,
+        filter: Callable,  # pylint: disable=redefined-builtin
+        max_scan: int = 100,
+    ) -> Optional[bool]:
+        """Return whether any queued item matches filter within max_scan items."""
+        scanned = 0
+        for item in self.__items.select():
+            if scanned >= max_scan:
+                return None
+
+            scanned += 1
+            if filter(**item.to_dict()):
+                return True
+
+        return False
+
+    def pop_front(
+        self,
+        count: int,
+        filter: Callable | None = None,  # pylint: disable=redefined-builtin
+    ) -> List[Dict]:
+        """Retrieve and remove up to count first matching elements from the queue."""
+        if filter is not None:
+            def _item_filter(item):
+                return isinstance(item, FQ_Item) and filter(**item.to_dict())
+
+            query = db0.filter(_item_filter, self.__items.select())
+        else:
+            query = self.__items.select()
+
+        results = []
+        items_to_remove = []
+
+        for item in self.__items.sort(query):
+            if len(results) >= count:
+                break
+            items_to_remove.append(item)
+            results.append(item.to_dict())
+
+        for item in items_to_remove:
+            self.__items.remove(item.queue_key, item)
+
+        return results

dbzero_modelkit/rpc_integration.py

@@ -0,0 +1,41 @@
+"""Optional dbzero RPC integration for shared model classes."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any
+
+
+class _NoRpcAdapter:
+    """No-op adapter used when db0_rpc is not installed."""
+
+    @staticmethod
+    def init(*_args: Any, **_kwargs: Any) -> None:
+        return None
+
+    @staticmethod
+    def remote(func: Any = None, **_kwargs: Any) -> Any:
+        if func is None:
+            return lambda wrapped: wrapped
+        return func
+
+
+_NO_RPC_ADAPTER = _NoRpcAdapter()
+
+
+@functools.lru_cache(None)
+def _load_rpc() -> Any:
+    try:
+        import db0_rpc  # pylint: disable=import-outside-toplevel
+
+        return db0_rpc
+    except ModuleNotFoundError:
+        return _NO_RPC_ADAPTER
+
+
+rpc = _load_rpc()
+
+
+def has_rpc() -> bool:
+    """Return True when db0_rpc is available."""
+    return rpc is not _NO_RPC_ADAPTER

dbzero_modelkit/time_utils.py

@@ -0,0 +1,24 @@
+"""Reusable date and datetime helpers for dbzero model utilities."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Optional
+
+
+def normalize_start(value: Optional[datetime | date]) -> datetime:
+    """Normalize a start value to datetime, treating None as datetime.min."""
+    if value is None:
+        return datetime.min
+    if isinstance(value, date) and not isinstance(value, datetime):
+        return datetime.combine(value, datetime.min.time())
+    return value
+
+
+def normalize_end(value: Optional[datetime | date]) -> datetime:
+    """Normalize an end value to datetime, treating None as datetime.max."""
+    if value is None:
+        return datetime.max
+    if isinstance(value, date) and not isinstance(value, datetime):
+        return datetime.combine(value, datetime.max.time())
+    return value

dbzero_modelkit-0.1.1.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: dbzero-modelkit
+Version: 0.1.1.1.0
+Summary: Reusable dbzero-backed data model utilities
+Author-email: Selltime <dev@selltime.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/selltime/dbzero-modelkit
+Project-URL: Repository, https://github.com/selltime/dbzero-modelkit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: dbzero<0.4,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: pylint>=3.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# dbzero-modelkit
+
+Reusable dbzero-backed model utilities copied from Selltime workspace projects.
+
+This package currently contains standalone copies of common data-model helpers only. It does not yet replace implementations in `selltime`, `statek`, or `kangal`; integration into those projects is planned as separate follow-up work.
+
+## Included Models
+
+- `ActiveBase` and `ActiveIndex` for active-window objects.
+- `Calendar`, `MonthCalendar`, `get_month_index`, and `get_date_from_month_index` for sparse date calendars.
+- `LanguageCode` and `ML_String` for multilingual strings.
+- `FiFoQueue` and `FQ_Item` for dbzero-backed FIFO queues.
+- `MonthStore` for sparse month-indexed object storage.
+- `ObjectLock` for tag-based object locking.
+
+## Testing
+
+Run tests from this directory:
+
+```bash
+python3 -m pytest -q
+```

dbzero_modelkit-0.1.1.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+dbzero_modelkit/__init__.py,sha256=gRGv3UB9gTcTNSnu5vWwEU0iC5mJA7VlOHHogu_yoxc,705
+dbzero_modelkit/active.py,sha256=CSjyCuAidbSN-P14t5s8j1taECIqItYzDo99bPhs4h8,8571
+dbzero_modelkit/calendars.py,sha256=9jFy_ubYjizFIVu0cnXRmpWCj97sluekPSLHrnjDOQg,6745
+dbzero_modelkit/language.py,sha256=dh5V_N71JH4DXaw4lgA2G6ndrPLwhFiVckiyrWZWTro,1945
+dbzero_modelkit/month_store.py,sha256=rf2mW7im9kPqJ7iU5j34Iq5S8IpSCpcQk1OovhKpgOU,4647
+dbzero_modelkit/object_lock.py,sha256=Z7qxSLmsrGR1OwYxiaqcP_0NTPYIhz5PmbKFP7SvkVY,1504
+dbzero_modelkit/queues.py,sha256=JMxFhMRsP-Jtzsz8z9A_FtdD66HrCh6APJeqXgwavPg,2779
+dbzero_modelkit/rpc_integration.py,sha256=PJRfK7_iuV2VvW0d9SXPzbH7m7TjhxhZo1rYSrqV7J0,861
+dbzero_modelkit/time_utils.py,sha256=jFAL5U8CwgzT863PmvMUnOCTDXzEpmT1lUNGZanN1CY,851
+dbzero_modelkit-0.1.1.1.0.dist-info/METADATA,sha256=e3K08P9skp5cJWmR5Rd3AZgmzr1L6xH1tf8kImrmGb4,1625
+dbzero_modelkit-0.1.1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dbzero_modelkit-0.1.1.1.0.dist-info/top_level.txt,sha256=kHjhnDkuK5LBnO9XSQ7A4PyY9cdvPRYoVjdWS9UlWXE,16
+dbzero_modelkit-0.1.1.1.0.dist-info/RECORD,,

dbzero_modelkit-0.1.1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dbzero_modelkit-0.1.1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dbzero_modelkit