funora 0.0.1.dev2__py3-none-any.whl

funora/_currency_switch.py

@@ -0,0 +1,130 @@
+"""Смена валюты показа и разбор ответа площадки.
+
+ЧТО ДЕЛАЕТ ЭТА ОПЕРАЦИЯ И ЧЕМ ОПАСНА. Она меняет валюту, в которой площадка
+показывает суммы, - и меняет ГЛОБАЛЬНО: после неё каждая страница отдаёт другие
+числа.
+
+Дороже всего это для снимков рынка. Сравнение двух снимков, снятых по разные
+стороны от смены, объявит сменившейся КАЖДУЮ цену - без единой ошибки, без строки
+в журнале, без следа.
+
+ДВЕ ВЕТКИ ОТВЕТА, И РАЗЛИЧАТЬ ИХ ОБЯЗАТЕЛЬНО. Либо валюта сменена сразу, либо
+возвращается окно подтверждения - и тогда смены НЕ БЫЛО.
+
+ПОДТВЕРЖДЕНИЕ НЕ ДАЁТСЯ ЗА ПОЛЬЗОВАТЕЛЯ. В запросе есть поле подтверждения, и
+сюда всегда уходит отрицание. Вторая ветка отдаётся исходом, а не проглатывается:
+решать, соглашаться ли, вправе только человек.
+
+КУРС ИЗ ОКНА НЕ РАЗБИРАЕТСЯ. Сторонняя реализация достаёт его регулярным
+выражением из абзаца окна - то есть из ТЕКСТА НА ЛОКАЛИ ИНТЕРФЕЙСА. Смена языка
+аккаунта ломает такой разбор молча, а локаль привязана к аккаунту, а не к адресу.
+
+Текст окна отдаётся как есть.
+
+Наблюдено нами: переключатель в шапке, пункты которого несут код ISO 4217.
+Известно от FunPayAPI (FunPayCardinal, account.py, get_exchange_rate): адрес,
+имена полей запроса и ключи ответа.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Final
+
+from ._observed import Observed
+from .errors import ProtocolChangedError
+
+__all__ = ["CurrencySwitch", "parse_currency_switch", "SWITCH_CURRENCY_PATH", "NEVER_CONFIRMED"]
+
+#: Адрес смены валюты. Известен от сторонней реализации.
+SWITCH_CURRENCY_PATH: Final[str] = "/account/switchCurrency"
+
+#: Что уходит в поле подтверждения. ВСЕГДА отрицание.
+#:
+#: Стоит константой, а не литералом в сборке запроса, чтобы согласие за
+#: пользователя нельзя было дать случайной правкой одного знака. Сторонняя
+#: реализация шлёт то же самое и никогда иного.
+NEVER_CONFIRMED: Final[str] = "false"
+
+
+@dataclass(frozen=True, slots=True)
+class CurrencySwitch:
+    """Исход смены валюты показа.
+
+    Attributes:
+        switched (bool): Сменила ли площадка валюту. Ложь при возвращённом окне
+            означает, что смены не было.
+        confirmation_required (bool): Вернула ли площадка окно подтверждения.
+            Истина означает: смены НЕ БЫЛО, и площадка хочет согласия. Давать
+            его вправе только человек.
+        confirmation_text (Observed[str]): Текст окна, КАК ЕСТЬ. Не разбирается:
+            внутри лежит курс обмена, и вывести его можно только из текста на
+            локали интерфейса.
+        requested (str): Код валюты, о котором просили.
+        observed_at (datetime): Момент получения ответа.
+    """
+
+    switched: bool
+    confirmation_required: bool
+    confirmation_text: Observed[str]
+    requested: str
+    observed_at: datetime
+
+
+def parse_currency_switch(payload: Any, *, requested: str, observed_at: datetime) -> CurrencySwitch:
+    """Разбирает ответ площадки на смену валюты.
+
+    ВЕТКА «СМЕНЕНО» УЗНАЁТСЯ ПОЛОЖИТЕЛЬНО: ключ адреса присутствует и пуст.
+    Присутствие непустого адреса означает не успех, а что-то третье, о чём мы
+    ничего не знаем, - и объявлять успехом его нельзя.
+
+    Аргументы:
+        payload (Any): Разобранное тело ответа.
+        requested (str): Код валюты, о котором просили.
+        observed_at (datetime): Момент получения.
+
+    Возвращает:
+        CurrencySwitch: Исход.
+
+    Raises:
+        ProtocolChangedError: Если ответ непригоден для чтения.
+    """
+    if not isinstance(payload, dict):
+        raise ProtocolChangedError(f"ответ смены валюты не объект, а {type(payload).__name__}")
+
+    raw_modal = payload.get("modal")
+    if isinstance(raw_modal, str) and raw_modal.strip():
+        # Окно есть - значит смены НЕ БЫЛО. Подтверждать за пользователя мы не
+        # станем, и потому это конечный исход, а не промежуточный шаг.
+        return CurrencySwitch(
+            switched=False,
+            confirmation_required=True,
+            confirmation_text=Observed.present(raw_modal),
+            requested=requested,
+            observed_at=observed_at,
+        )
+
+    if "url" not in payload:
+        raise ProtocolChangedError(
+            "в ответе смены валюты нет ни окна подтверждения, ни ключа адреса. "
+            "Сменилась валюта или нет - неизвестно, а угадывать здесь дорого: "
+            "после смены каждая страница отдаёт другие числа"
+        )
+
+    raw_url = payload["url"]
+    # Пустой адрес - положительный признак того, что делать больше нечего.
+    # Непустой означает что-то третье; успехом его объявлять нельзя.
+    if isinstance(raw_url, str) and raw_url.strip():
+        raise ProtocolChangedError(
+            f"ответ смены валюты несёт непустой адрес {raw_url!r}. Наблюдались "
+            "две ветки - смена и окно подтверждения, - и эта не из них"
+        )
+
+    return CurrencySwitch(
+        switched=True,
+        confirmation_required=False,
+        confirmation_text=Observed.missing("no_confirmation_window"),
+        requested=requested,
+        observed_at=observed_at,
+    )

funora/_cursor.py

@@ -0,0 +1,120 @@
+"""Переносимая позиция пагинации, привязанная к операции и её владельцу.
+
+Это формат хранения, а не подпись или разрешение доступа. Проверка сессии
+по-прежнему принадлежит транспорту. Сырые значения кодируются отдельно:
+каноническая нормализация JSON не должна менять непрозрачный токен сервера.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+
+from ._canonical import canonical_dumps
+from .contract import (
+    ACCEPTED_CURSOR_FORMAT_VERSIONS,
+    ADAPTER_FAMILY,
+    CANONICAL_FORM_VERSION,
+    CURSOR_FORMAT_VERSION,
+    MAX_CURSOR_BYTES,
+)
+from .errors import CursorIncompatibleError, ValidationError
+
+_KINDS = {"chats.history_before", "reviews.get"}
+_KEYS = {"version", "canonical_form_version", "adapter_family", "kind", "owner", "position"}
+
+
+def _pack(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _unpack(value: str) -> bytes:
+    if not isinstance(value, str) or not value or len(value) > MAX_CURSOR_BYTES:
+        raise ValueError("cursor size or type")
+    raw = base64.b64decode(value + "=" * (-len(value) % 4), altchars=b"-_", validate=True)
+    if _pack(raw) != value:
+        raise ValueError("non-canonical base64url")
+    return raw
+
+
+def _envelope(
+    kind: str,
+    owner: str,
+    position: str,
+    scope: str | None,
+    *,
+    version: int = CURSOR_FORMAT_VERSION,
+) -> dict[str, str | int | None]:
+    if kind not in _KINDS:
+        raise ValueError("cursor kind")
+    if not isinstance(owner, str) or not owner or len(owner) > MAX_CURSOR_BYTES:
+        raise ValueError("cursor owner")
+    if not isinstance(position, str) or not position.strip() or len(position) > MAX_CURSOR_BYTES:
+        raise ValueError("cursor position")
+    if scope is not None and (
+        not isinstance(scope, str) or not scope or len(scope) > MAX_CURSOR_BYTES
+    ):
+        raise ValueError("cursor scope")
+    envelope: dict[str, str | int | None] = {
+        "version": version,
+        "canonical_form_version": CANONICAL_FORM_VERSION,
+        "adapter_family": ADAPTER_FAMILY,
+        "kind": kind,
+        "owner": _pack(owner.encode("utf-8")),
+        "position": _pack(position.encode("utf-8")),
+    }
+    if version == 2:
+        envelope["scope"] = None if scope is None else _pack(scope.encode("utf-8"))
+    return envelope
+
+
+def encode_cursor(kind: str, owner: str, position: str, *, scope: str | None = None) -> str:
+    """Сохраняет позицию без нормализации её байтов."""
+    try:
+        token = _pack(canonical_dumps(_envelope(kind, owner, position, scope)).encode("utf-8"))
+        if len(token) > MAX_CURSOR_BYTES:
+            raise ValueError("cursor too large")
+        return token
+    except (TypeError, ValueError, ValidationError):
+        raise CursorIncompatibleError(
+            "позиция не помещается в поддерживаемый формат курсора"
+        ) from None
+
+
+def decode_cursor(token: str, *, kind: str) -> tuple[str, str, str | None]:
+    """Возвращает владельца, позицию и область выборки; v1 читается без области."""
+    try:
+        raw = _unpack(token)
+        payload = json.loads(raw)
+        if not isinstance(payload, dict):
+            raise ValueError("cursor envelope")
+        version = payload.get("version")
+        if (
+            type(version) is not int
+            or version not in ACCEPTED_CURSOR_FORMAT_VERSIONS
+            or set(payload) != (_KEYS | {"scope"} if version == 2 else _KEYS)
+            or type(payload["canonical_form_version"]) is not int
+            or payload["canonical_form_version"] != CANONICAL_FORM_VERSION
+            or payload["adapter_family"] != ADAPTER_FAMILY
+            or payload["kind"] != kind
+        ):
+            raise ValueError("cursor incompatible")
+        owner = _unpack(payload["owner"]).decode("utf-8")
+        position = _unpack(payload["position"]).decode("utf-8")
+        scope = payload.get("scope")
+        if scope is not None:
+            scope = _unpack(scope).decode("utf-8")
+        # Сверка отвергает дубликаты ключей, лишние пробелы и альтернативные
+        # кодировки: один курсор имеет одно представление между реализациями.
+        if (
+            canonical_dumps(_envelope(kind, owner, position, scope, version=version)).encode(
+                "utf-8"
+            )
+            != raw
+        ):
+            raise ValueError("non-canonical envelope")
+        return owner, position, scope
+    except (TypeError, ValueError, RecursionError, ValidationError):
+        raise CursorIncompatibleError(
+            "курсор повреждён либо относится к другому формату или операции"
+        ) from None

funora/_delivered.py

@@ -0,0 +1,233 @@
+"""Реестр выданного: что уже отправлено покупателю и по какому заказу.
+
+ЗАЧЕМ ОТДЕЛЬНЫЙ РЕЕСТР, КОГДА ЕСТЬ КУРСОР ЗАКАЗОВ. Курсор защитой не является, и
+это установлено, а не предположено. Три причины, каждая записана в самом коде:
+
+Курсор снимается только с полного чтения, а события по прочитанным строкам
+порождаются и при неполном. Заказ, выпавший из неполного чтения, в курсор не
+попадёт и в следующий раз придёт как новый.
+
+Обрыв тела на передаче по частям даёт правдоподобное «полно» с недостачей строк.
+Выпавшие заказы уходят из курсора и возвращаются событием о создании.
+
+Гашение повторов живёт по сроку и гасит по отпечатку события. «Этот заказ
+выдан» обязано жить, пока жив заказ, а не пока не истёк срок.
+
+ЗАПИСЬ ИДЁТ ВПЕРЕДИ ОТПРАВКИ. Тот же приём и тот же довод, что у реестра
+отправок: «не засчитаем, раз не подтвердилось» означает не считать ровно те
+выдачи, которые могли уйти. Повторная выдача необратима.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Final
+
+from .errors import StateSchemaIncompatibleError
+
+__all__ = ["Delivery", "DeliveryLedger", "QUEUED_OUTCOME"]
+
+#: Исход, с которым запись о выдаче заводится.
+#:
+#: Означает «задание поставлено в очередь, чем кончилось - ещё не известно».
+#: Запись, оставшаяся с ним после разбора очереди, - повод посмотреть заказ
+#: глазами: см. :meth:`DeliveryLedger.unsettled`.
+QUEUED_OUTCOME: Final[str] = "queued"
+
+
+@dataclass(frozen=True, slots=True)
+class Delivery:
+    """Запись о выдаче.
+
+    Attributes:
+        order_id (str): Заказ, по которому выдано.
+        offer_id (str): Предложение, которое сочли выданным. Пустая строка
+            означает, что выдавал человек и предложение не устанавливалось.
+        at_ms (int): Момент выдачи по стенным часам.
+        outcome (str): Исход отправки, каким его вернул канал.
+    """
+
+    order_id: str
+    offer_id: str
+    at_ms: int
+    outcome: str
+
+
+class DeliveryLedger:
+    """Что уже выдано.
+
+    Реестр не забывает записи по сроку НАМЕРЕННО, в отличие от реестра
+    отправок. Тот считает часовые пределы, и старая запись ему не нужна; этот
+    отвечает на вопрос «выдавали ли по этому заказу», и ответ на него не
+    устаревает никогда.
+
+    Растёт он на запись за заказ. Продавец с сотней заказов в день накопит за
+    год тридцать тысяч записей - несколько мегабайт, и это дешевле любой
+    повторной выдачи.
+    """
+
+    __slots__ = ("_done",)
+
+    def __init__(self) -> None:
+        self._done: dict[str, Delivery] = {}
+
+    def seen(self, order_id: str) -> bool:
+        """Говорит, выдавали ли уже по этому заказу.
+
+        Аргументы:
+            order_id (str): Заказ.
+
+        Возвращает:
+            bool: True, если запись о выдаче есть.
+        """
+        return order_id in self._done
+
+    def get(self, order_id: str) -> Delivery | None:
+        """Возвращает запись о выдаче.
+
+        Аргументы:
+            order_id (str): Заказ.
+
+        Возвращает:
+            Delivery | None: Запись либо None.
+        """
+        return self._done.get(order_id)
+
+    def record(self, delivery: Delivery) -> None:
+        """Записывает выдачу.
+
+        Перезаписи НЕТ: первая запись о заказе побеждает. Вторая означала бы,
+        что мы выдали дважды, и затирать след первой выдачи значило бы прятать
+        именно то, ради чего реестр заведён.
+
+        Аргументы:
+            delivery (Delivery): Запись о выдаче.
+
+        Возвращает:
+            None
+        """
+        self._done.setdefault(delivery.order_id, delivery)
+
+    def settle(self, order_id: str, outcome: str) -> None:
+        """Проставляет записи настоящий исход отправки.
+
+        ЗАПИСЬ ЗАВОДИТСЯ ИСХОДОМ ``queued`` И ПРЕЖДЕ ТАК И ОСТАВАЛАСЬ. Поле
+        объявлялось «исход отправки, каким его вернул канал», а канал к нему не
+        притрагивался никто: успешная выдача и выдача, потерянная между записью
+        и отправкой, лежали в реестре одинаковыми.
+
+        Отсюда и был вред: найти потерянные было нечем. Проверка «выдавали ли»
+        на исход не смотрит и смотреть не должна - запись о заказе означает
+        «больше не выдавать», и это верно при любом исходе. Но человеку,
+        который разбирается, чем кончился день, нужно уметь их различать.
+
+        Записи нет - ничего не происходит: settle не заводит записей. Завести
+        её здесь значило бы объявить выданным заказ, по которому решения не
+        принимали.
+
+        Аргументы:
+            order_id (str): Заказ.
+            outcome (str): Исход, каким его вернул канал, либо имя отказа.
+
+        Возвращает:
+            None
+        """
+        existing = self._done.get(order_id)
+        if existing is None:
+            return
+        self._done[order_id] = Delivery(
+            order_id=existing.order_id,
+            offer_id=existing.offer_id,
+            at_ms=existing.at_ms,
+            outcome=outcome,
+        )
+
+    def unsettled(self) -> tuple[str, ...]:
+        """Перечисляет заказы, у которых исход так и остался ``queued``.
+
+        ЭТО И ЕСТЬ СПИСОК ПОДОЗРИТЕЛЬНЫХ. Задание поставлено в очередь, а чем
+        кончилась отправка, реестр не узнал: процесс мог умереть между записью и
+        разбором очереди. Товар при этом покупателю мог не уйти, а повторно он
+        не уйдёт уже никогда - запись о заказе стоит.
+
+        Звать стоит при запуске: заказы отсюда - те, по которым стоит посмотреть
+        переписку глазами.
+
+        Возвращает:
+            tuple[str, ...]: Заказы с незакрытым исходом, в порядке записи.
+        """
+        return tuple(
+            order_id for order_id, one in self._done.items() if one.outcome == QUEUED_OUTCOME
+        )
+
+    def snapshot(self) -> dict[str, Any]:
+        """Отдаёт состояние обычными значениями для файла состояния.
+
+        Возвращает:
+            dict[str, Any]: Состояние, пригодное для записи в файл.
+        """
+        return {
+            "done": [
+                {
+                    "order_id": one.order_id,
+                    "offer_id": one.offer_id,
+                    "at_ms": one.at_ms,
+                    "outcome": one.outcome,
+                }
+                for one in self._done.values()
+            ]
+        }
+
+    def restore(self, payload: dict[str, Any]) -> None:
+        """Восстанавливает реестр целиком после проверки всех записей.
+
+        Повреждение даёт StateSchemaIncompatibleError и сохраняет прежний
+        реестр. Пропущенная выдача разрешила бы выдать тот же заказ повторно.
+        Отсутствующий раздел старого файла означает пустой список; отсутствующие
+        offer_id и outcome остаются пустыми строками, сохраняя защиту по order_id.
+        """
+        if not isinstance(payload, dict):
+            raise StateSchemaIncompatibleError("реестр выдач должен быть объектом")
+        raw = payload.get("done", [])
+        if not isinstance(raw, list):
+            raise StateSchemaIncompatibleError("выдачи должны быть списком записей")
+
+        restored: dict[str, Delivery] = {}
+        for one in raw:
+            if not isinstance(one, dict):
+                raise StateSchemaIncompatibleError("непригодная запись выдачи")
+
+            order_id = one.get("order_id")
+            # Только строка и только непустая. Число, None и словарь дали бы
+            # ключ вида 'None' либо "{'a': 1}" - запись о заказе, которого нет.
+            if not isinstance(order_id, str) or not order_id.strip():
+                raise StateSchemaIncompatibleError("непригодный идентификатор выданного заказа")
+
+            at_ms = one.get("at_ms")
+            # Логическое исключается отдельно: в Python истина - это единица, и
+            # метка времени True прочиталась бы как первая миллисекунда эпохи.
+            if isinstance(at_ms, bool) or not isinstance(at_ms, int):
+                raise StateSchemaIncompatibleError("непригодная метка времени выдачи")
+
+            offer_id = one.get("offer_id", "")
+            outcome = one.get("outcome", "")
+            if not isinstance(offer_id, str) or not isinstance(outcome, str):
+                raise StateSchemaIncompatibleError("непригодное предложение или исход выдачи")
+            if order_id in restored:
+                raise StateSchemaIncompatibleError("повтор заказа в реестре выдач")
+            restored[order_id] = Delivery(
+                order_id=order_id,
+                offer_id=offer_id,
+                at_ms=at_ms,
+                outcome=outcome,
+            )
+
+        self._done = restored
+
+    def __len__(self) -> int:
+        """Возвращает число записей.
+
+        Возвращает:
+            int: Сколько заказов уже выдано.
+        """
+        return len(self._done)