dbzero-modelkit 0.1.1.1.0__tar.gz

dbzero_modelkit-0.1.1.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,22 @@
+# 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/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-0.1.1.1.0/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-0.1.1.1.0/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-0.1.1.1.0/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])