funora 0.0.1.dev2__py3-none-any.whl

funora/_snapshot.py

@@ -0,0 +1,276 @@
+"""Снимок выдачи раздела и сравнение двух снимков.
+
+ЗАЧЕМ ОТДЕЛЬНО ОТ [_market.py]. Тот читает страницу: строки в порядке показа,
+со всеми полями. Здесь - то, что СРАВНИВАЕТСЯ: предложения по идентификатору,
+отпечаток запроса и полнота.
+
+Разделены они не для порядка. Порядок строк меняется от поднятия чужого лота, и
+сравнение по позициям давало бы поток ложных изменений каждую минуту.
+Сравнивать надо по идентификатору - а идентификатор чужого предложения стал
+наблюдаем только 31.08.2026, с формата скелета v9. До него этого модуля не могло
+существовать.
+
+Порождения событий рынка здесь нет. Показанная цена теперь нормализуется в
+Money без округления; неизвестный формат остаётся явно ненаблюдённым. Событие
+об исчезновении требует счётчика подряд идущих отсутствий - его ведёт тот,
+кто хранит снимки, а не чистое сравнение.
+
+Поэтому здесь выдаётся РАЗНИЦА как данные, а не события. Разница честна: по ней
+видно, что появилось, что пропало и у чего сменилась цена. Наблюдения и события
+порождает monitoring.watch, который хранит историю и подтверждения доставки.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from hashlib import sha256
+from typing import Final
+
+from ._market import MarketPage
+from ._money import Money
+from ._observed import Observed
+from ._result import Completeness
+from .errors import UsageError
+
+__all__ = [
+    "MarketSnapshot",
+    "SnapshotEntry",
+    "MarketDiff",
+    "PriceChange",
+    "snapshot_of",
+    "compare",
+]
+
+#: Сколько знаков отпечатка запроса хранится.
+#:
+#: Отпечаток служит равенству, а не тайне: шестнадцати шестнадцатеричных знаков
+#: хватает, чтобы два разных запроса не совпали случайно.
+_FINGERPRINT_LENGTH: Final[int] = 16
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotEntry:
+    """Одно предложение внутри снимка.
+
+    Attributes:
+        offer_id (str): Идентификатор предложения. По нему идёт сравнение.
+        price_text (str): Цена, как показана, без знака валюты.
+        currency_symbol_text (str): Знак валюты. Входит в сравнение вместе с
+            ценой: смена знака при том же числе - это смена цены.
+        seller_href (str): Ссылка на профиль продавца.
+        position (int): Место в выдаче, считая с нуля.
+        price (Observed[Money]): Показанная цена при scale 6 либо причина отсутствия.
+    """
+
+    offer_id: str
+    price_text: str
+    currency_symbol_text: str
+    seller_href: str
+    position: int
+    price: Observed[Money] = field(default_factory=lambda: Observed.missing("price_not_normalized"))
+
+
+@dataclass(frozen=True, slots=True)
+class MarketSnapshot:
+    """Состояние выдачи раздела в один момент.
+
+    Attributes:
+        query_fingerprint (str): Отпечаток запроса. Сравнивать можно только
+            снимки с одинаковым отпечатком.
+        node_id (str): Раздел, чья выдача снята.
+        taken_at (datetime): Момент снятия.
+        completeness (Completeness): Полнота снимка.
+        reason (str | None): Причина неполноты. None означает полный снимок.
+        rows_total (int): Сколько строк нашлось.
+        rows_accepted (int): Сколько строк собрано целиком.
+        offers (dict[str, SnapshotEntry]): Предложения по идентификатору.
+    """
+
+    query_fingerprint: str
+    node_id: str
+    taken_at: datetime
+    completeness: Completeness
+    reason: str | None
+    rows_total: int
+    rows_accepted: int
+    offers: dict[str, SnapshotEntry]
+
+    @property
+    def is_complete(self) -> bool:
+        """Говорит, полон ли снимок.
+
+        Возвращает:
+            bool: True, если полнота complete.
+        """
+        return self.completeness is Completeness.COMPLETE
+
+
+@dataclass(frozen=True, slots=True)
+class PriceChange:
+    """Смена цены у предложения, оставшегося на месте.
+
+    Attributes:
+        offer_id (str): Предложение.
+        before (SnapshotEntry): Каким было.
+        after (SnapshotEntry): Каким стало.
+    """
+
+    offer_id: str
+    before: SnapshotEntry
+    after: SnapshotEntry
+
+
+@dataclass(frozen=True, slots=True)
+class MarketDiff:
+    """Разница между двумя снимками одной выдачи.
+
+    Attributes:
+        appeared (tuple[SnapshotEntry, ...]): Предложения, которых в прежнем
+            снимке не было.
+        absent (tuple[SnapshotEntry, ...]): Предложения, которых нет в новом.
+
+            ИМЕННО ОТСУТСТВУЮЩИЕ, А НЕ ИСЧЕЗНУВШИЕ. Одно отсутствие не значит
+            исчезновения: предложение могло не попасть в чтение. Контракт
+            требует у события об исчезновении счётчика подряд идущих
+            отсутствий, и вести его - дело того, кто хранит снимки.
+        price_changed (tuple[PriceChange, ...]): У кого сменилась цена либо знак
+            валюты.
+        seller_changed (tuple[PriceChange, ...]): У кого сменился продавец.
+        absences_trusted (bool): Можно ли делать выводы об отсутствии.
+
+            Ложь означает, что один из снимков неполон, и список absent
+            заполнен не будет: неполный снимок не отличает «пропало» от «не
+            прочитали».
+    """
+
+    appeared: tuple[SnapshotEntry, ...]
+    absent: tuple[SnapshotEntry, ...]
+    price_changed: tuple[PriceChange, ...]
+    seller_changed: tuple[PriceChange, ...]
+    absences_trusted: bool
+
+
+def fingerprint_of(node_id: str) -> str:
+    """Считает отпечаток запроса.
+
+    В отпечаток входит один раздел. Фильтры площадки - сервер и наличие -
+    наблюдались только в исходном, пустом состоянии; класть в отпечаток
+    ненаблюдённое значило бы объявить о нём знание.
+
+    Аргументы:
+        node_id (str): Раздел.
+
+    Возвращает:
+        str: Отпечаток.
+    """
+    return sha256(f"node={node_id}".encode()).hexdigest()[:_FINGERPRINT_LENGTH]
+
+
+def snapshot_of(page: MarketPage, *, node_id: str) -> MarketSnapshot:
+    """Собирает снимок из прочитанной страницы.
+
+    ПРЕДЛОЖЕНИЯ БЕЗ ИДЕНТИФИКАТОРА В СНИМОК НЕ ПОПАДАЮТ. Сравнивать их не по
+    чему, а положив их под выдуманным ключом, мы породили бы исчезновение на
+    ровном месте: в следующем снимке выдуманный ключ будет другим.
+
+    Их потеря при этом видна: rows_accepted берётся у страницы и остаётся
+    больше, чем число предложений в снимке.
+
+    Аргументы:
+        page (MarketPage): Прочитанная страница.
+        node_id (str): Раздел, у которого она прочитана.
+
+    Возвращает:
+        MarketSnapshot: Снимок, пригодный для сравнения.
+    """
+    offers: dict[str, SnapshotEntry] = {}
+    for one in page.offers(accept_incomplete=True):
+        if not one.offer_id.is_observed:
+            continue
+        offers[one.offer_id.value] = SnapshotEntry(
+            offer_id=one.offer_id.value,
+            price_text=one.price_text.or_none() or "",
+            currency_symbol_text=one.currency_symbol_text.or_none() or "",
+            seller_href=one.seller_href.or_none() or "",
+            position=one.row_index,
+            price=one.price,
+        )
+
+    return MarketSnapshot(
+        query_fingerprint=fingerprint_of(node_id),
+        node_id=node_id,
+        taken_at=page.observed_at,
+        completeness=page.completeness,
+        reason=page.reason,
+        rows_total=page.rows_total,
+        rows_accepted=page.rows_accepted,
+        offers=offers,
+    )
+
+
+def compare(before: MarketSnapshot, after: MarketSnapshot) -> MarketDiff:
+    """Сравнивает два снимка одной выдачи.
+
+    ОТПЕЧАТКИ ОБЯЗАНЫ СОВПАДАТЬ. Снимок раздела с фильтром и снимок того же
+    раздела без фильтра описывают разные множества; сравнив их, получишь
+    исчезновение всего, что отфильтровано.
+
+    ОТСУТСТВИЯ СЧИТАЮТСЯ ТОЛЬКО ПО ДВУМ ПОЛНЫМ СНИМКАМ. Неполный не отличает
+    «пропало» от «не прочитали», и разница между ними - это разница между
+    «конкурент ушёл, можно поднять цену» и «мы плохо прочитали страницу».
+
+    Появления при этом считаются и по неполным: предложение, которого раньше не
+    было, а теперь есть, вправду есть - неполнота могла его скрыть прежде, но
+    не могла выдумать сейчас.
+
+    Аргументы:
+        before (MarketSnapshot): Прежний снимок.
+        after (MarketSnapshot): Новый снимок.
+
+    Возвращает:
+        MarketDiff: Разница.
+
+    Raises:
+        UsageError: Если отпечатки запросов не совпадают.
+    """
+    if before.query_fingerprint != after.query_fingerprint:
+        raise UsageError(
+            f"снимки сняты разными запросами: {before.query_fingerprint} и "
+            f"{after.query_fingerprint}. Сравнивать их нельзя - разные запросы "
+            "описывают разные множества, и разница вышла бы исчезновением "
+            "всего, что не попало во второй"
+        )
+
+    appeared = tuple(entry for key, entry in after.offers.items() if key not in before.offers)
+
+    trusted = before.is_complete and after.is_complete
+    absent = (
+        tuple(entry for key, entry in before.offers.items() if key not in after.offers)
+        if trusted
+        else ()
+    )
+
+    price_changed: list[PriceChange] = []
+    seller_changed: list[PriceChange] = []
+    for key, now in after.offers.items():
+        was = before.offers.get(key)
+        if was is None:
+            continue
+        if (
+            was.price.value != now.price.value
+            if was.price.is_observed and now.price.is_observed
+            else (was.price_text, was.currency_symbol_text)
+            != (now.price_text, now.currency_symbol_text)
+        ):
+            price_changed.append(PriceChange(offer_id=key, before=was, after=now))
+        if was.seller_href != now.seller_href:
+            seller_changed.append(PriceChange(offer_id=key, before=was, after=now))
+
+    return MarketDiff(
+        appeared=appeared,
+        absent=absent,
+        price_changed=tuple(price_changed),
+        seller_changed=tuple(seller_changed),
+        absences_trusted=trusted,
+    )

funora/_state.py

@@ -0,0 +1,279 @@
+"""Сохранение состояния клиента между запусками.
+
+Единственная задача файла - пережить перезапуск. Спецификация требует этого
+прямо: кэш гашения повторов только в памяти означает, что после любого
+перезапуска повторно приходит всё, что успело прийти до него. Для обработчика,
+выдающего товар, это выданный дважды товар при каждом перезапуске процесса.
+
+Три решения, каждое против своего вида беды.
+
+Запись атомарна. Файл собирается рядом и переименовывается поверх, а не
+дописывается на месте. Процесс, убитый посреди записи, оставил бы обрезанный
+файл, и следующий запуск не смог бы его прочитать - то есть перезапуск в самый
+неудачный момент отменял бы всю защиту, ради которой файл заведён.
+
+Чужой формат не читается молча. Файл, записанный другой версией формата или
+другим семейством адаптера, даёт ошибку, а не пустое состояние. Молчаливый старт
+с нуля здесь неотличим от штатной работы и приводит к повторной обработке всего,
+что уже обработано.
+
+Отсутствие файла ошибкой не является. Первый запуск - штатное событие, и
+требовать файл значило бы требовать его создать вручную.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from stat import S_ISDIR, S_ISREG
+from typing import Any, Final
+
+from ._canonical import canonical_dumps
+from ._fileio import atomic_write, file_lock
+from ._json import load_json
+from .contract import ADAPTER_FAMILY as _ADAPTER_FAMILY
+from .contract import CANONICAL_FORM_VERSION
+from .errors import CursorIncompatibleError, StateSchemaIncompatibleError
+
+__all__ = ["StateFile", "STATE_FORMAT"]
+
+#: Версия формата файла состояния.
+#:
+#: Меняется при любом изменении состава сохраняемого. Прочитать файл чужой
+#: версии нельзя: неизвестно, что означают его поля.
+#:
+#: v2 добавила курсор. Файл v1 хранил только гашение повторов, и старт по нему
+#: ушёл бы в холодный старт, молча съев всё, что изменилось за простой. Отказ
+#: здесь честнее: пользователь удалит файл сам и будет знать, чем это грозит.
+#:
+#: v3 сменила не состав, а СМЫСЛ хранимого. События о самом наблюдении -
+#: watch.primed и snapshot.incomplete - строились вручную: идентификатор
+#: человекочитаемой строкой, ключ упорядочивания «account:...» мимо нормативной
+#: таблицы. Теперь оба строятся общим путём, и прежние отпечатки в гашении
+#: повторов не совпадут ни с чем.
+#:
+#: Молча принять такой файл значило бы выдать приветствие и жалобу на неполноту
+#: повторно - по разу за срок гашения. Не смертельно, но необъяснимо со стороны
+#: пользователя: он увидит «наблюдение началось» у работающего месяц клиента.
+#:
+#: v4: метки гашения повторов перестали быть монотонными секундами и стали
+#: моментами от эпохи. Прежние файлы принять нельзя: дробное показание
+#: секундомера, прочитанное как момент от эпохи, попадает в тысяча девятьсот
+#: семидесятый - и весь кэш гашения молча выбрасывается по сроку. Это ровно
+#: то, что спецификация запрещает прямо: молчаливое чтение с начала порождает
+#: повторную обработку всего, что уже обработано.
+#: v5 хранит непринятую партию до обработчиков. v4 без незавершённых попыток
+#: читается без сброса; v4 с попытками не содержит самих событий для повтора.
+#: v6 различает личный курсор и набор снимков рынка. v5 читается без сброса.
+STATE_FORMAT: Final[str] = "funora-state-v6"
+
+#: Семейство адаптера, к которому относится состояние.
+#:
+#: Состояние, снятое с другой площадки, бессмысленно здесь целиком: совпадение
+#: идентификаторов было бы случайным, а последствия - молчаливым гашением чужих
+#: событий.
+ADAPTER_FAMILY: Final[str] = _ADAPTER_FAMILY
+
+
+@dataclass(frozen=True, slots=True)
+class StateFile:
+    """Файл состояния клиента.
+
+    Args:
+        path (str | Path): Путь файла. Строка принимается наравне с Path и
+            приводится к нему здесь.
+    """
+
+    path: Path
+
+    def __post_init__(self) -> None:
+        """Закрепляет общий путь файла и блокировок, сохраняя рабочие ссылки."""
+        path = Path(self.path)
+        try:
+            try:
+                resolved = path.resolve(strict=True)
+            except FileNotFoundError:
+                # Новый файл допустим, но битая ссылка в любом компоненте
+                # пути не должна создавать пустой журнал в другом месте.
+                for component in (path, *path.parents):
+                    if component.is_symlink():
+                        component.resolve(strict=True)
+                resolved = path.resolve()
+            object.__setattr__(self, "path", resolved)
+            self._exists()
+        except (OSError, RuntimeError) as exc:
+            raise StateSchemaIncompatibleError(
+                f"путь файла состояния {path} недоступен: {type(exc).__name__}"
+            ) from exc
+
+    def _exists(self) -> bool:
+        """Отличает первый запуск от недоступного или специального файла."""
+        for component in (self.path, *self.path.parents):
+            try:
+                mode = component.stat().st_mode
+            except OSError as exc:
+                if isinstance(exc, FileNotFoundError) and not component.is_symlink():
+                    continue
+                raise StateSchemaIncompatibleError(
+                    f"путь состояния {self.path} недоступен: {type(exc).__name__}"
+                ) from exc
+            if component != self.path and S_ISDIR(mode):
+                return False
+            if component == self.path and S_ISREG(mode):
+                return True
+            raise StateSchemaIncompatibleError(
+                f"неверный тип файла или родительского каталога состояния {self.path}"
+            )
+        raise StateSchemaIncompatibleError(f"путь состояния {self.path} недоступен")
+
+    def load(self) -> dict[str, Any]:
+        """Читает состояние.
+
+        Returns:
+            dict[str, Any]: Сохранённое состояние. Пустой словарь, если файла
+            нет: первый запуск - штатное событие.
+
+        Raises:
+            StateSchemaIncompatibleError: Если файл не читается вовсе либо
+                записан другой версией схемы файла.
+            CursorIncompatibleError: Если сохранённая позиция снята с другого
+                семейства адаптера либо собрана другой канонической формой.
+                Молчаливый старт с нуля здесь неотличим от штатной работы и
+                приводит к повторной обработке всего, что уже обработано.
+        """
+        try:
+            if not self._exists():
+                return {}
+            raw = load_json(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError, RecursionError) as exc:
+            raise StateSchemaIncompatibleError(
+                f"файл состояния {self.path} не читается: {type(exc).__name__}. "
+                "Удалите его вручную, если готовы к повторной обработке всего, "
+                "что уже обработано"
+            ) from exc
+
+        if not isinstance(raw, dict):
+            raise StateSchemaIncompatibleError(
+                f"файл состояния {self.path} имеет неожиданное устройство"
+            )
+
+        stored_format = raw.get("format")
+        if stored_format not in (STATE_FORMAT, "funora-state-v5", "funora-state-v4"):
+            raise StateSchemaIncompatibleError(
+                f"файл состояния {self.path} записан форматом {stored_format!r}, "
+                f"ожидался {STATE_FORMAT!r}"
+            )
+
+        # Семейство адаптера и каноническая форма - про КУРСОР, а версия схемы
+        # файла выше - про файл. Спецификация делит их прямо: 1801 говорит
+        # «курсор принадлежит другой версии формата или другому семейству
+        # адаптера», 1802 - «версия схемы сохранённого состояния не
+        # поддерживается». Обе ветки ниже подпадают под первое и возбуждали
+        # второе.
+        #
+        # Разница не в номере. Она в том, что делать: чужая схема файла лечится
+        # выходом новой версии SDK, чужое семейство - никогда. Курсор, снятый с
+        # другой площадки, не станет совместимым от обновления.
+        stored_family = raw.get("adapter_family")
+        if stored_family != ADAPTER_FAMILY:
+            raise CursorIncompatibleError(
+                f"файл состояния {self.path} снят с семейства {stored_family!r}, "
+                f"ожидалось {ADAPTER_FAMILY!r}. Сохранённая позиция принадлежит "
+                "другой площадке и совместимой не станет"
+            )
+
+        stored_canonical = raw.get("canonical_form_version")
+        if stored_canonical is not None and stored_canonical != CANONICAL_FORM_VERSION:
+            raise CursorIncompatibleError(
+                f"файл состояния {self.path} записан канонической формой "
+                f"{stored_canonical!r}, ожидалась {CANONICAL_FORM_VERSION!r}. "
+                "Сохранённые отпечатки собраны по другим правилам и не совпадут "
+                "ни с чем"
+            )
+
+        payload = raw.get("payload")
+        if not isinstance(payload, dict):
+            raise StateSchemaIncompatibleError(
+                f"файл состояния {self.path}: payload обязан быть объектом; "
+                "начать с пустым журналом значило бы забыть уже выполненные действия"
+            )
+        if stored_format == "funora-state-v4" and payload.get("attempts"):
+            raise CursorIncompatibleError(
+                "файл v4 содержит незавершённые попытки без сохранённых событий; "
+                "завершите их прежней версией SDK перед обновлением. "
+                "Восстановить исходную партию по новому снимку невозможно"
+            )
+        if (
+            "watch_owner" in payload
+            and not {
+                "watch_pending",
+                "watch_greeted",
+                "cursor",
+            }
+            <= payload.keys()
+        ):
+            raise StateSchemaIncompatibleError("в состоянии watch отсутствует журнал или курсор")
+        if payload.get("attempts") and payload.get("watch_pending") is None:
+            raise StateSchemaIncompatibleError("попытки watch сохранены без непринятой партии")
+        return payload
+
+    def update(self, patch: dict[str, Any]) -> None:
+        """Правит часть состояния, не трогая остального.
+
+        Нужен затем, что состояние пишут ДВОЕ и в разное время. Цикл наблюдения
+        сохраняет курсоры и гашение раз в шаг; ограничитель исходящих обязан
+        сохраниться сразу после отправки, иначе перезапуск между отправкой и
+        концом шага теряет её из реестра - а реестр для того и заведён, чтобы
+        часовая квота не обнулялась перезапуском.
+
+        Прямая запись целиком тут не годится: сохранив один только реестр, мы
+        затёрли бы курсоры, и перезапуск ушёл бы в холодный старт.
+
+        Слияние поверхностное, по ключам верхнего уровня. Глубокого не нужно:
+        разделы состояния независимы, и владелец у каждого один.
+
+        Args:
+            patch (dict[str, Any]): Ключи верхнего уровня, которые надо заменить.
+
+        Returns:
+            None
+
+        Raises:
+            StateSchemaIncompatibleError: Если существующий файл не читается.
+            CursorIncompatibleError: Если он снят с другого семейства адаптера.
+        """
+        self._exists()
+        with file_lock(self.path.with_suffix(self.path.suffix + ".lock")):
+            current = self.load()
+            current.update(patch)
+            self._save(current)
+
+    def save(self, payload: dict[str, Any]) -> None:
+        """Записывает состояние.
+
+        Запись атомарна: файл собирается рядом и переименовывается поверх.
+        Дописывание на месте оставило бы обрезанный файл при убийстве процесса
+        посреди записи, и следующий запуск не смог бы его прочитать - то есть
+        перезапуск в самый неудачный момент отменил бы всю защиту.
+
+        Args:
+            payload (dict[str, Any]): Сохраняемое состояние.
+
+        Returns:
+            None
+        """
+        self._exists()
+        with file_lock(self.path.with_suffix(self.path.suffix + ".lock")):
+            self._save(payload)
+
+    def _save(self, payload: dict[str, Any]) -> None:
+        self._exists()
+        body = canonical_dumps(
+            {
+                "format": STATE_FORMAT,
+                "adapter_family": ADAPTER_FAMILY,
+                "canonical_form_version": CANONICAL_FORM_VERSION,
+                "payload": payload,
+            }
+        )
+        atomic_write(self.path, body)

funora/_stock.py

@@ -0,0 +1,32 @@
+"""Общий разбор показанного наличия в колонке и поле формы."""
+
+from typing import Final
+
+from selectolax.parser import Node
+
+from ._observed import Observed
+
+# Граница разбора SDK, а не объявленный площадкой предел запасов.
+_MAX_DIGITS: Final[int] = 18
+
+
+def parse_stock_text(raw: str | None) -> Observed[int]:
+    """Не подменяет отсутствие, пустоту и неизвестный формат нулём."""
+    if raw is None:
+        return Observed.missing("stock_not_shown")
+    value = raw.strip()
+    if not value:
+        return Observed.missing("stock_empty")
+    if not value.isascii() or not value.isdecimal():
+        return Observed.missing("stock_format_unknown")
+    if len(value) > _MAX_DIGITS:
+        return Observed.missing("stock_out_of_range")
+    return Observed.present(int(value))
+
+
+def parse_stock_column(row: Node, selector: str) -> Observed[int]:
+    """Читает единственную ячейку внутри строки, исключая заголовки."""
+    cells = row.css(selector)
+    if len(cells) > 1:
+        return Observed.missing("stock_ambiguous")
+    return parse_stock_text(cells[0].text() if cells else None)