funora 0.0.1.dev2__py3-none-any.whl

funora/_updates.py

@@ -0,0 +1,292 @@
+"""Разбор ответа канала обновлений.
+
+ЧТО ЭТО ЗА КАНАЛ. Площадка держит его для собственной страницы: один POST с
+подпиской, в ответ - изменения только тех объектов, на которые подписан. Ничего
+не изменилось - объекты пусты.
+
+ПОЧЕМУ ЭТО ВАЖНЕЕ ВСЕГО ОСТАЛЬНОГО. Наблюдение сегодня читает две полные
+страницы на КАЖДОМ шаге, изменилось что-нибудь или нет. Канал отвечает малым
+телом и молчит, когда молчать нечего.
+
+Три факта, наблюдённые 30.08.2026 и записанные в spec/extraction/updates.yaml:
+
+Метка - это КВИТАНЦИЯ «я видел до сюда», а не пропуск. Площадка принимает любую,
+в том числе выдуманную, и отвечает всем, что изменилось с той поры. Свою метку
+она возвращает в ответе; тот же опрос с ней даёт пустоту.
+
+Подписка длиннее ДЕСЯТИ объектов обрезается МОЛЧА. Послано одиннадцать - пришло
+десять, без единого признака, что один отброшен.
+
+Счётчики приходят ЧИСЛАМИ, а не выводятся из разметки.
+
+ЧТО ЗДЕСЬ НЕ РАЗБИРАЕТСЯ. Поле html внутри объектов - разметка переписки, и
+разбирать её тем же кодом, что разбирает страницу, никто не проверял. Она
+проходит насквозь как непрозрачная строка: разбор по догадке разошёлся бы с
+площадкой молча.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Final
+
+from ._json import load_json
+from .errors import ProtocolChangedError
+
+__all__ = [
+    "MAX_SUBSCRIPTION",
+    "UpdatesAnswer",
+    "ChannelObject",
+    "build_subscription",
+    "parse_updates_answer",
+]
+
+#: Сколько объектов площадка принимает в одной подписке.
+#:
+#: Наблюдено, а не взято у чужой реализации: послано одиннадцать узлов диалога,
+#: вернулось десять. Чужая константа была поводом проверить, а не свидетельством.
+#:
+#: МОЛЧАЛИВОСТЬ ОБРЕЗКИ - главное в этом числе. Признака, что объект отброшен, в
+#: ответе нет никакого. Подписавшийся на пятнадцать диалогов получит десять и не
+#: узнает об этом ниоткуда: сообщения пяти покупателей не придут, и объяснить это
+#: будет нечем.
+MAX_SUBSCRIPTION: Final[int] = 10
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelObject:
+    """Один изменившийся объект из ответа канала.
+
+    Attributes:
+        type (str): Вид объекта, как его назвала площадка.
+        id (str): Идентификатор объекта.
+        tag (str): Непустая метка для следующего опроса.
+        data (dict[str, Any]): Данные объекта как есть. Разметка внутри НЕ
+            разбирается: она проходит насквозь непрозрачной строкой.
+    """
+
+    type: str
+    id: str
+    tag: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def number(self, name: str) -> int | None:
+        """Читает целое поле данных.
+
+        Числа - единственное, что этот разбор берёт из данных объекта, и берёт
+        он их без толкования: что означает счётчик, решает вызывающий.
+
+        Возвращается None, а не ноль, когда поля нет. Ноль означал бы «счётчик
+        равен нулю», а это другое утверждение.
+
+        Аргументы:
+            name (str): Имя поля.
+
+        Возвращает:
+            int | None: Значение либо None, если поля нет или оно не целое.
+        """
+        value = self.data.get(name)
+        # Логическое исключается отдельно: в Python True - это единица, и
+        # счётчик, оказавшийся булевым, прочитался бы числом молча.
+        if isinstance(value, bool) or not isinstance(value, int):
+            return None
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class UpdatesAnswer:
+    """Ответ канала обновлений.
+
+    Attributes:
+        objects (tuple[ChannelObject, ...]): Изменившиеся объекты. Пусто -
+            штатное состояние, а не признак поломки: канал молчит, когда молчать
+            нечего.
+        error (object | None): Поле ошибки без преобразования. Только None означает
+            отсутствие отказа; форма непустого поля не интерпретируется.
+        answered_action (bool): Был ли в запросе действие. Площадка отвечает
+            объектом при опросе С ДЕЙСТВИЕМ и логическим - при опросе без него.
+    """
+
+    objects: tuple[ChannelObject, ...]
+    error: object | None
+    answered_action: bool
+
+    @property
+    def is_quiet(self) -> bool:
+        """Говорит, что изменений не пришло.
+
+        Returns:
+            bool: True, если объектов нет.
+        """
+        return not self.objects
+
+    def tags(self, known: dict[tuple[str, str], str] | None = None) -> dict[tuple[str, str], str]:
+        """Собирает метки для следующего опроса, НАКАПЛИВАЯ прежние.
+
+        Ключ - пара из вида и идентификатора, а не один вид: подписка держит по
+        объекту на каждый диалог, и вид у них общий.
+
+        НАКОПЛЕНИЕ - не удобство, а условие работоспособности. Ответ несёт
+        только ИЗМЕНИВШИЕСЯ объекты: у молчавшего диалога метки в ответе нет
+        вовсе. Собирая метки лишь из последнего ответа, опрос подставлял бы
+        всем молчавшим метку «я ничего не видел» - и площадка отдавала бы их
+        целиком заново на каждом шаге.
+
+        То есть без накопления канал перестаёт быть дешевле страниц ровно в
+        тот момент, когда становится нужен: при десяти диалогах и одном
+        говорящем девять приезжали бы полностью каждый раз.
+
+        Аргументы:
+            known (dict[tuple[str, str], str] | None): Метки прошлых опросов.
+                Пришедшие в этом ответе их вытесняют.
+
+        Returns:
+            dict[tuple[str, str], str]: Метки по объектам.
+        """
+        collected = dict(known or {})
+        collected.update({(one.type, one.id): one.tag for one in self.objects if one.tag})
+        return collected
+
+
+def build_subscription(
+    wanted: list[tuple[str, str]], tags: dict[tuple[str, str], str]
+) -> list[list[dict[str, Any]]]:
+    """Собирает подписку ПОРЦИЯМИ не длиннее предела.
+
+    Порции считает вызывающий, а не площадка: она обрезает лишнее молча, и
+    заметить обрезку в ответе нечем.
+
+    Объект без известной метки получает выдуманную. Это не обход защиты, а
+    значение «я ничего не видел»: площадка отвечает на него всем, что изменилось,
+    - ровно так же, как отвечает странице при первом обращении.
+
+    Аргументы:
+        wanted (list[tuple[str, str]]): На что подписываться: вид и
+            идентификатор.
+        tags (dict[tuple[str, str], str]): Метки прошлого ответа.
+
+    Возвращает:
+        list[list[dict[str, Any]]]: Подписки порциями, каждая не длиннее
+        предела.
+    """
+    objects = [
+        {
+            "type": kind,
+            "id": entity,
+            "tag": tags.get((kind, entity), UNSEEN_TAG),
+            "data": False,
+        }
+        for kind, entity in wanted
+    ]
+    return [
+        objects[at : at + MAX_SUBSCRIPTION] for at in range(0, len(objects), MAX_SUBSCRIPTION)
+    ] or [[]]
+
+
+#: Метка, означающая «я ничего не видел».
+#:
+#: Годится любая несуществующая: площадка отвечает на неё всем, что изменилось.
+#: Наблюдено 30.08.2026 - подписка с этой самой строкой вернула оба объекта
+#: целиком, а повторная с вернувшимися метками вернула пустоту.
+UNSEEN_TAG: Final[str] = "0000000000"
+
+
+def load_runner_json(body: str) -> object:
+    """Читает JSON канала без потери полей и неконечных чисел.
+
+    Опрос и отправка делят один декодер. Ошибки ValueError/RecursionError
+    вызывающий переводит в свой исход: откат к страницам либо unconfirmed.
+    """
+    return load_json(body)
+
+
+def parse_updates_answer(body: str) -> UpdatesAnswer:
+    """Разбирает тело ответа канала.
+
+    Декодер JSON общий с отправкой. Опрос дополнительно проверяет все объекты
+    подписки, прежде чем вызывающий сможет подтвердить их метки.
+
+    Аргументы:
+        body (str): Тело ответа.
+
+    Возвращает:
+        UpdatesAnswer: Разобранный ответ.
+
+    Raises:
+        ProtocolChangedError: Если тело не разбирается либо устроено не так,
+            как наблюдалось.
+    """
+    try:
+        parsed = load_runner_json(body)
+    except (ValueError, RecursionError) as exc:
+        raise ProtocolChangedError(
+            "ответ канала обновлений не разобрался как JSON. Канал отвечал JSON "
+            "во всех наблюдениях; разбор чего-то иного означал бы, что мы "
+            "приняли за канал не канал"
+        ) from exc
+
+    if not isinstance(parsed, dict):
+        raise ProtocolChangedError(
+            f"ответ канала обновлений - не объект, а {type(parsed).__name__}"
+        )
+
+    raw = parsed.get("objects")
+    if not isinstance(raw, list):
+        raise ProtocolChangedError(
+            "в ответе канала обновлений нет перечня объектов. Пустой перечень - "
+            "штатное состояние, а отсутствие поля означает другой ответ"
+        )
+
+    answer = parsed.get("response")
+    # Объект при опросе С ДЕЙСТВИЕМ, логическое - без действия. Различие
+    # наблюдено, и по нему же читается ошибка: у логического ошибке взяться
+    # неоткуда.
+    error = None
+    if isinstance(answer, dict):
+        if "error" not in answer:
+            raise ProtocolChangedError("в ответе действия канала нет поля error")
+        action = True
+        error = answer["error"]
+    elif isinstance(answer, bool):
+        action = False
+    else:
+        raise ProtocolChangedError("поле response канала - не логическое и не объект действия")
+
+    objects: list[ChannelObject] = []
+    seen: set[tuple[str, str]] = set()
+    for one in raw:
+        if not isinstance(one, dict):
+            raise ProtocolChangedError("элемент objects канала - не объект")
+        kind = one.get("type")
+        if not isinstance(kind, str) or not kind:
+            raise ProtocolChangedError("у объекта канала нет непустого строкового type")
+        entity = one.get("id")
+        if not (type(entity) is int or isinstance(entity, str) and entity):
+            raise ProtocolChangedError("id объекта канала - не целое число и не непустая строка")
+        tag = one.get("tag")
+        if not isinstance(tag, str) or not tag:
+            raise ProtocolChangedError("у объекта канала нет непустой строковой tag")
+        data = one.get("data")
+        if not isinstance(data, dict):
+            raise ProtocolChangedError("data объекта канала - не объект")
+        key = (kind, str(entity))
+        try:
+            for value in (*key, tag):
+                value.encode("utf-8")
+        except UnicodeEncodeError:
+            raise ProtocolChangedError(
+                "ключ или метка канала содержит некорректный Unicode"
+            ) from None
+        if key in seen:
+            raise ProtocolChangedError("в ответе канала повторяется объект подписки")
+        seen.add(key)
+        objects.append(
+            ChannelObject(
+                type=kind,
+                id=key[1],
+                tag=tag,
+                data=data,
+            )
+        )
+
+    return UpdatesAnswer(objects=tuple(objects), error=error, answered_action=action)

funora/_verdicts.py

@@ -0,0 +1,91 @@
+"""Превращение вердикта классификатора в ошибку.
+
+Отображение живёт в спецификации и порождается, а не пишется: от него зависит,
+повторит клиент запрос или остановится навсегда. Здесь только то, что таблицей
+не выражается, - три уточнения, зависящие от состояния клиента, а не от ответа.
+
+Первое. Истёкшая сессия и неверный секрет выглядят одинаково, а лечатся
+по-разному: первую имеет смысл обновить и повторить, второй повторять
+бессмысленно, и попытка обновления только добавит подозрительных запросов к
+аккаунту, который и так под вопросом. Различает их одно: подтверждалась ли
+сессия хоть раз за время жизни клиента.
+
+Второе. Вердикт, принятый непроверенной сигнатурой, ошибку поднимает - не
+заметить настоящую страницу проверки опаснее, чем сработать по тексту, - но
+признак непроверенности переносится в экземпляр. По такой ошибке нельзя
+останавливаться навсегда: страницы, ради которой написана сигнатура, никто не
+видел.
+
+Третье. Пара, которой нет в таблице, означает, что классификатор вернул вердикт,
+не предусмотренный спецификацией. Это не повод придумать ошибку на месте:
+придуманная ошибка разойдётся между реализациями именно там, где расхождение
+дороже всего.
+"""
+
+from __future__ import annotations
+
+from ._classify import Verdict
+from .errors import (
+    FunoraError,
+    InvalidCredentialsError,
+    ProtocolChangedError,
+    SessionExpiredError,
+)
+from .response_classes import VERDICT_ERRORS
+
+__all__ = ["error_for", "PROVISIONAL_ATTR"]
+
+#: Имя признака непроверенности на экземпляре ошибки.
+#:
+#: Признак живёт на экземпляре, а не на классе: непроверенность - свойство
+#: конкретного решения, а не вида ошибки. Один и тот же ChallengeRequiredError
+#: может быть поднят и по структурному признаку, и по догадке о тексте.
+PROVISIONAL_ATTR = "provisional"
+
+
+def error_for(
+    verdict: Verdict,
+    *,
+    session_ever_valid: bool = False,
+) -> FunoraError | None:
+    """Возвращает ошибку, соответствующую вердикту.
+
+    Args:
+        verdict (Verdict): Вердикт классификатора.
+        session_ever_valid (bool): Подтверждалась ли сессия хоть раз за время
+            жизни клиента. Отличает истёкшую сессию от неверного секрета.
+
+    Returns:
+        FunoraError | None: Экземпляр ошибки либо None, если ответ пригоден для
+        разбора. У экземпляра выставлен признак provisional, показывающий, было
+        ли решение принято непроверенной сигнатурой.
+
+    Raises:
+        ProtocolChangedError: Если пара «класс, причина» отсутствует в таблице.
+            Придумать ошибку на месте нельзя: придуманная разойдётся между
+            реализациями.
+    """
+    key = (str(verdict.cls), verdict.reason)
+    if key not in VERDICT_ERRORS:
+        raise ProtocolChangedError(
+            f"классификатор вернул вердикт {key}, которого нет в таблице "
+            "соответствия. Либо таблица отстала от спецификации, либо появился "
+            "новый класс ответа"
+        )
+
+    cls = VERDICT_ERRORS[key]
+    if cls is None:
+        return None
+
+    # Уточнение, не выразимое таблицей: истёкшая сессия и неверный секрет
+    # выглядят одинаково, но лечатся по-разному.
+    if cls is SessionExpiredError and not session_ever_valid:
+        cls = InvalidCredentialsError
+
+    detail = f"{verdict.cls}: {verdict.reason}"
+    if verdict.matched:
+        detail += f" (сигнатура {verdict.matched})"
+
+    error = cls(detail)
+    setattr(error, PROVISIONAL_ATTR, verdict.provisional)
+    return error  # type: ignore[return-value]

funora/_viewing.py

@@ -0,0 +1,143 @@
+"""Что покупатель смотрит прямо сейчас.
+
+РАСКОЛ НАБЛЮДЕНИЯ, И ОН ЗДЕСЬ ГЛАВНОЕ. Подписка на этот объект наблюдена НАМИ -
+она лежит в семи наших записях канала, и состав её известен: признак,
+идентификатор из восьми цифр, метка из восьми знаков.
+
+Ответ на неё мы не видели НИ РАЗУ. Что приходит внутри, известно от независимой
+реализации того же протокола: при пустом признаке покупатель не смотрит ничего,
+иначе внутри лежит разметка со ссылкой на лот.
+
+Отсюда устройство записи: разметка сохраняется КАК ЕСТЬ, а ссылка и подпись
+читаются из неё отдельными полями. Не разобралась - поля остаются
+ненаблюдёнными, а разметка при вызывающем: по ней человек увидит то, чего не
+увидел разбор.
+
+ИМЯ ОБЪЕКТА ЗАПИСАНО ДОСЛОВНО и странно выглядит. Что оно означает - неизвестно,
+и догадываться незачем: подписка собирается по имени, а не по смыслу.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Final
+
+from selectolax.parser import HTMLParser
+
+from ._observed import Observed
+
+__all__ = ["BuyerViewing", "parse_buyer_viewing", "VIEWING_OBJECT"]
+
+#: Имя объекта подписки. Наблюдено НАМИ в семи записях канала.
+#:
+#: Записано дословно. Как оно добралось до записи, стоит помнить: прежний
+#: образец протокольного знака его не пропускал, и сборщик записал вместо имени
+#: мерку. Образец расширили дефисом ПО ЭТОЙ МЕРКЕ, а не наугад.
+VIEWING_OBJECT: Final[str] = "c-p-u"
+
+
+@dataclass(frozen=True, slots=True)
+class BuyerViewing:
+    """Что покупатель смотрит прямо сейчас.
+
+    Attributes:
+        buyer_id (str): Идентификатор покупателя, о котором спрашивали.
+        viewing (bool): Смотрит ли он что-нибудь. ЛОЖЬ ЗДЕСЬ - НАБЛЮДЕНИЕ:
+            площадка прислала пустой признак, то есть сказала «не смотрит».
+            Неудачу чтения выражает отказ.
+        lot_href (Observed[str]): Ссылка на лот, прочитанная из разметки.
+        lot_text (Observed[str]): Подпись лота на локали интерфейса. Не
+            разбирается.
+        raw_html (Observed[str]): Разметка блока, КАК ЕСТЬ. Сохраняется затем,
+            что ответа этой точки мы не наблюдали: не разберись наши поля - у
+            вызывающего останется то, из чего он поймёт сам.
+        observed_at (datetime): Момент получения ответа.
+    """
+
+    buyer_id: str
+    viewing: bool
+    lot_href: Observed[str]
+    lot_text: Observed[str]
+    raw_html: Observed[str]
+    observed_at: datetime
+
+
+def _from_markup(markup: str) -> tuple[Observed[str], Observed[str]]:
+    """Читает ссылку и подпись из разметки блока просмотра.
+
+    РАЗБОР ЗДЕСЬ САМЫЙ ПРОСТОЙ ИЗ ВОЗМОЖНЫХ - первая ссылка, - и это не лень.
+    Разметки этой мы не видели; строить по чужому описанию точный селектор
+    значило бы выдать чужое описание за наблюдение.
+
+    Аргументы:
+        markup (str): Разметка блока.
+
+    Возвращает:
+        tuple[Observed[str], Observed[str]]: Ссылка и подпись.
+    """
+    node = HTMLParser(markup).css_first("a[href]")
+    if node is None:
+        return (
+            Observed.missing("viewing_link_absent"),
+            Observed.missing("viewing_text_absent"),
+        )
+
+    raw_href = (node.attributes or {}).get("href")
+    href = (raw_href or "").strip()
+    text = (node.text() or "").strip()
+    return (
+        Observed.present(href) if href else Observed.empty(""),
+        Observed.present(text) if text else Observed.empty(""),
+    )
+
+
+def parse_buyer_viewing(obj: Any, *, buyer_id: str, observed_at: datetime) -> BuyerViewing:
+    """Разбирает объект «покупатель смотрит» из ответа канала.
+
+    ПУСТОЙ ПРИЗНАК - НАБЛЮДЕНИЕ, А НЕ НЕУДАЧА. Площадка сказала «не смотрит», и
+    показать это продавцу можно. Неудачу чтения выражает отказ, а не ложь в
+    поле.
+
+    Аргументы:
+        obj (Any): Объект из ответа канала.
+        buyer_id (str): Идентификатор покупателя, о котором спрашивали.
+        observed_at (datetime): Момент получения.
+
+    Возвращает:
+        BuyerViewing: Что смотрит покупатель.
+    """
+    empty = BuyerViewing(
+        buyer_id=buyer_id,
+        viewing=False,
+        lot_href=Observed.missing("not_viewing"),
+        lot_text=Observed.missing("not_viewing"),
+        raw_html=Observed.missing("not_viewing"),
+        observed_at=observed_at,
+    )
+
+    if not isinstance(obj, dict):
+        return empty
+
+    data = obj.get("data")
+    # Пустой признак означает «не смотрит ничего». Наблюдено это не нами -
+    # известно от сторонней реализации, - и потому обращение осторожное: всё,
+    # что не похоже на разметку, читается как «не смотрит», а не как поломка.
+    if not isinstance(data, dict):
+        return empty
+
+    raw_html = data.get("html")
+    if isinstance(raw_html, dict):
+        raw_html = raw_html.get("desktop")
+    if not isinstance(raw_html, str) or not raw_html.strip():
+        return empty
+
+    href, text = _from_markup(raw_html)
+    return BuyerViewing(
+        buyer_id=buyer_id,
+        viewing=True,
+        lot_href=href,
+        lot_text=text,
+        raw_html=Observed.present(raw_html),
+        observed_at=observed_at,
+    )