funora 0.0.1.dev2__py3-none-any.whl

funora/_refund.py

@@ -0,0 +1,102 @@
+"""Возврат средств покупателю: адрес и разбор ответа.
+
+САМАЯ ОПАСНАЯ ИЗ НАПИСАННЫХ ОПЕРАЦИЙ. Деньги уходят покупателю, и площадка не
+предлагает вернуть их обратно ничем. «Попробовать и посмотреть» здесь стоит
+настоящих денег продавца.
+
+ЧТО НАБЛЮДЕНО НАМИ, А ЧТО НЕТ. Наблюдён ЗАПРОС - целиком: адрес в атрибуте
+формы, оба поля в ней же, и признак того, что площадка возврат по этому заказу
+предлагает.
+
+НЕ НАБЛЮДЁН ОТВЕТ. Что в нём приходит, известно от независимой реализации того
+же протокола: объект с признаком отказа error и сообщением msg.
+
+ОТСЮДА ОТКАЗ ЧИТАТЬ ОТВЕТ БЕЗ ПРИЗНАКА. Площадка отвечает признаком ОТКАЗА, а не
+успеха; отсутствие поля означает не успех, а непонятный ответ.
+
+У поднятия то же правило стоило суток ожидания при ошибке. Здесь оно стоит денег,
+о судьбе которых вызывающий не узнает, - и потому отказ здесь громче.
+
+СУММЫ ВОЗВРАТА НЕТ НИГДЕ - ни в запросе, ни в ответе. Сколько именно вернулось,
+вызывающий узнаёт только чтением заказа.
+
+Наблюдено нами 31.08.2026: order.v9.logged.ru, форма возврата и её поля.
+Известно от FunPayAPI (FunPayCardinal, account.py, refund): состав ответа.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Final
+
+from .errors import ProtocolChangedError
+
+__all__ = ["RefundResult", "parse_refund", "REFUND_PATH"]
+
+#: Адрес возврата. Наблюдён НАМИ - в атрибуте action формы на странице заказа.
+REFUND_PATH: Final[str] = "/orders/refund"
+
+
+@dataclass(frozen=True, slots=True)
+class RefundResult:
+    """Исход возврата средств покупателю.
+
+    Attributes:
+        refunded (bool): Состоялся ли возврат. Читается ОТРИЦАНИЕМ признака
+            отказа: площадка отвечает признаком отказа, а не успеха.
+        message (str): Сообщение площадки человеку, как есть. Не разбирается:
+            это текст на локали интерфейса, а причина здесь про деньги.
+        order_id (str): Заказ, по которому просили возврат.
+        observed_at (datetime): Момент получения ответа.
+    """
+
+    refunded: bool
+    message: str
+    order_id: str
+    observed_at: datetime
+
+
+def parse_refund(payload: Any, *, order_id: str, observed_at: datetime) -> RefundResult:
+    """Разбирает ответ площадки на возврат.
+
+    ПРИЗНАК ОТКАЗА ОБЯЗАТЕЛЕН. Без него неизвестно, ушли деньги или нет, а
+    повторить, чтобы выяснить, нельзя: повтор здесь - второй возврат.
+
+    Аргументы:
+        payload (Any): Разобранное тело ответа.
+        order_id (str): Заказ, по которому просили возврат.
+        observed_at (datetime): Момент получения.
+
+    Возвращает:
+        RefundResult: Исход.
+
+    Raises:
+        ProtocolChangedError: Если в ответе нет признака отказа.
+    """
+    if not isinstance(payload, dict):
+        raise ProtocolChangedError(
+            f"ответ на возврат не объект, а {type(payload).__name__}. Что "
+            f"случилось с деньгами по заказу {order_id} - неизвестно; прочитайте "
+            "заказ и посмотрите"
+        )
+
+    error = payload.get("error")
+    # Логическое требуется строго. Истина в Python - это единица, и error=1
+    # прочиталось бы как отказ, а error=0 как успех, ни разу не будучи
+    # логическим. У денег такая подмена стоит дороже всего.
+    if not isinstance(error, bool):
+        raise ProtocolChangedError(
+            f"в ответе на возврат по заказу {order_id} нет признака отказа error. "
+            "Площадка отвечает признаком ОТКАЗА, а не успеха, и без него исход "
+            "неизвестен. Деньги МОГЛИ уйти покупателю: прочитайте заказ и "
+            "посмотрите, а повторять не надо - повтор здесь второй возврат"
+        )
+
+    raw_message = payload.get("msg")
+    return RefundResult(
+        refunded=not error,
+        message=raw_message if isinstance(raw_message, str) else "",
+        order_id=order_id,
+        observed_at=observed_at,
+    )

funora/_result.py

@@ -0,0 +1,157 @@
+"""Общие понятия разбора: полнота, повреждения, сбор строк.
+
+Файл появился после разбора, нашедшего одну и ту же дыру во всех трёх
+разборщиках сразу. Причина была общая: каждый брал первый попавшийся контейнер
+строк и считал внутри него оба счётчика, поэтому строки во втором контейнере
+исчезали молча - и механизм двух счётчиков, написанный ровно против такого
+исчезновения, с ними соглашался.
+
+Пока эти понятия жили в разборе заказов, а два других разборщика их оттуда
+импортировали, чинить приходилось бы в трёх местах. Теперь место одно.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from selectolax.parser import HTMLParser, Node
+
+__all__ = ["Severity", "Completeness", "Defect", "RowSet", "collect_rows"]
+
+
+class Severity(StrEnum):
+    """Уровень, на котором обнаружено повреждение разбора.
+
+    Уровни различают, что именно потеряно, потому что решения по ним разные.
+    """
+
+    #: Пострадала страница целиком. Записям доверять нельзя.
+    PAGE = "page"
+
+    #: Пострадала одна строка. Она отброшена, остальные целы.
+    ROW = "row"
+
+    #: Пострадало одно поле одной строки. Строка сохранена.
+    FIELD = "field"
+
+
+class Completeness(StrEnum):
+    """Полнота прочитанного.
+
+    Словарь взят из спецификации и не расширяется реализацией: значение уходит
+    в решение вызывающего, и лишнее значение здесь означает, что шесть SDK
+    ответят на один вопрос по-разному.
+    """
+
+    #: Всё разобрано, повреждений нет.
+    COMPLETE = "complete"
+
+    #: Часть данных потеряна. Что именно - в перечне повреждений.
+    PARTIAL = "partial"
+
+    #: Полноту установить не удалось.
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class Defect:
+    """Повреждение, обнаруженное при разборе.
+
+    Attributes:
+        severity (Severity): Уровень, на котором обнаружено.
+        code (str): Машиночитаемый код, например ``row_selector_undercount``.
+        detail (str): Пояснение для человека. Содержимого страницы не содержит.
+        row_index (int | None): Номер строки при severity ROW и FIELD.
+        field_name (str | None): Имя поля при severity FIELD.
+    """
+
+    severity: Severity
+    code: str
+    detail: str
+    row_index: int | None = None
+    field_name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RowSet:
+    """Строки, найденные на странице, вместе с обнаруженными расхождениями.
+
+    Attributes:
+        rows (tuple[Node, ...]): Узлы строк в порядке появления.
+        children (int): Сколько прямых потомков у всех контейнеров вместе.
+        containers (int): Сколько контейнеров строк нашлось.
+        defects (tuple[Defect, ...]): Расхождения счётчиков.
+    """
+
+    rows: tuple[Node, ...]
+    children: int
+    containers: int
+    defects: tuple[Defect, ...]
+
+
+def collect_rows(tree: HTMLParser, container: str, row: str) -> RowSet:
+    """Собирает строки по всем контейнерам и сверяет три независимых счёта.
+
+    Счётчиков три, и каждый ловит своё.
+
+    Совпадения селектора строки внутри контейнеров - основной счёт.
+
+    Прямые потомки контейнеров - счёт, не зависящий от класса строки. Он ловит
+    самый вероятный вид изменения вёрстки: переименование класса при живом
+    контейнере, дающее иначе пустой список, неотличимый от «записей нет».
+
+    Совпадения селектора строки по всему документу - счёт, не зависящий от
+    контейнера. Он ловит то, чего не ловят первые два: строки, оказавшиеся во
+    втором контейнере либо вне контейнера вовсе. Прежний разбор брал первый
+    попавшийся контейнер, и оба счётчика соглашались друг с другом внутри него,
+    пока часть записей исчезала молча - при полноте complete и нуле повреждений.
+
+    Args:
+        tree (HTMLParser): Разобранный документ.
+        container (str): Селектор контейнера строк.
+        row (str): Селектор строки.
+
+    Returns:
+        RowSet: Найденные строки, счётчики и расхождения.
+    """
+    containers = tree.css(container)
+    rows: list[Node] = []
+    children = 0
+
+    for node in containers:
+        rows.extend(node.css(row))
+        children += len([child for child in node.iter() if child.tag != "-text"])
+
+    defects: list[Defect] = []
+
+    if len(rows) != children:
+        defects.append(
+            Defect(
+                severity=Severity.PAGE,
+                code="row_selector_undercount",
+                detail=(
+                    f"селектор строки нашёл {len(rows)}, а прямых потомков у контейнеров {children}"
+                ),
+            )
+        )
+
+    in_document = len(tree.css(row))
+    if in_document != len(rows):
+        defects.append(
+            Defect(
+                severity=Severity.PAGE,
+                code="rows_outside_container",
+                detail=(
+                    f"по документу строк {in_document}, а внутри контейнеров "
+                    f"{len(rows)}: часть записей лежит вне разбираемой области"
+                ),
+            )
+        )
+
+    return RowSet(
+        rows=tuple(rows),
+        children=children,
+        containers=len(containers),
+        defects=tuple(defects),
+    )

funora/_retry.py

@@ -0,0 +1,213 @@
+"""Решение о повторе запроса.
+
+Модуль чистый и не спит. Он отвечает на вопрос «повторять ли и через сколько», а
+ждать обязан вызывающий. Разделение нужно затем, что решение проверяется
+тестами, а сон - нет: планировщик, который спит внутри, приходится проверять
+часами вместо секунд, и в итоге не проверяют вовсе.
+
+Условий для повтора три, и каждое отсекает свой вид беды.
+
+Ошибка обязана быть помечена повторяемой. Это свойство класса ошибки, взятое из
+спецификации: соединение не установилось - запрос не дошёл, повторять безопасно.
+
+Решение не должно быть принято непроверенной сигнатурой. Признак ``provisional``
+означает, что страницу такого вида никто не видел и вердикт вынесен по догадке
+о тексте. Повторяться против догадки нельзя: если догадка неверна, клиент
+долбится в исправную страницу, а если верна - подтверждает подозрение площадки.
+
+Операция обязана быть безопасной. Повтор небезопасной операции может выполнить
+её дважды, и списанные деньги вторым разом не возвращаются.
+
+Разброс задержки полный, а не половинный, и это не мелочь. При нескольких
+клиентах на одном адресе детерминированное отступление синхронизирует их, и
+площадка видит не шесть вежливых клиентов, а один невежливый.
+"""
+
+from __future__ import annotations
+
+import random as _random
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Final
+
+from ._verdicts import PROVISIONAL_ATTR
+from .errors import ConfigurationError, FunoraError
+from .operations import Safety
+from .retry import (
+    DECISION_MATRIX,
+    FALLBACK_POLICY,
+    GLOBAL_MAX_ATTEMPTS,
+    RETRY_POLICIES,
+    RetryDecision,
+    RetryPolicy,
+)
+
+__all__ = ["RETRY_REASON_ATTR", "decide", "Safety", "Attempt", "policy_for", "plan_attempt"]
+
+
+#: Имя признака, которым причина решения о повторе переносится в исключение.
+#:
+#: Заведено потому, что решение reconcile_first снаружи было НЕОТЛИЧИМО от
+#: прочих отказов в повторе. На чтениях это безвредно: не повторили и не
+#: повторили. На первой же операции записи это ровно тот сигнал, ради которого
+#: матрица решений и заведена: вызывающему полагается СВЕРИТЬСЯ, а не считать
+#: отправку неудавшейся. Отправка могла и пройти - неоднозначным был исход, а не
+#: результат.
+#:
+#: Признак ставится на всякий отказ в повторе, а не только на reconcile_first:
+#: правило «переносим одну причину из пяти» разошлось бы с матрицей молча, стоит
+#: добавить в неё шестую.
+RETRY_REASON_ATTR = "retry_reason"
+
+
+@dataclass(frozen=True, slots=True)
+class Attempt:
+    """Решение о следующей попытке.
+
+    Attributes:
+        retry (bool): Повторять ли запрос.
+        delay_ms (int): Через сколько миллисекунд. Ноль, если повтора не будет.
+        reason (str): Машиночитаемая причина решения. Уходит в журнал, поэтому
+            по ней должно быть видно, какое из условий не выполнилось.
+        policy (RetryPolicy): Политика, по которой принято решение.
+    """
+
+    retry: bool
+    delay_ms: int
+    reason: str
+    policy: RetryPolicy
+
+
+def policy_for(error: FunoraError) -> RetryPolicy:
+    """Подбирает политику повторов для ошибки.
+
+    Поиск идёт от самого точного к общему: сначала по устойчивому идентификатору
+    самой ошибки, затем по идентификаторам её предков, затем запасная. Такой
+    порядок нужен, чтобы добавление подтипа не меняло поведение молча: подтип без
+    собственной политики наследует политику родителя, а не самую щедрую.
+
+    Args:
+        error (FunoraError): Экземпляр ошибки.
+
+    Returns:
+        RetryPolicy: Политика. Запасная, если ни один предок не описан.
+    """
+    for cls in type(error).__mro__:
+        stable_id = getattr(cls, "stable_id", None)
+        if stable_id in RETRY_POLICIES:
+            return RETRY_POLICIES[stable_id]
+    return FALLBACK_POLICY
+
+
+def decide(error: Exception, safety: Safety) -> RetryDecision:
+    """Находит строку матрицы, которая решает о повторе.
+
+    Матрица - пересечение двух вещей: класса ошибки и безопасности операции.
+    Реализация долго сводила её к одному условию «повторяем только чтения»: это
+    строже контракта и потому безопасно, но расходится - второй SDK на той же
+    трассе поступит иначе, и разойдутся они молча.
+
+    Строки читаются сверху вниз, первая подошедшая решает. Порядок значим и
+    задан спецификацией: первая строка отсекает неповторяемый класс ошибки
+    независимо от операции.
+
+    Args:
+        error (Exception): Полученная ошибка.
+        safety (Safety): Безопасность операции при повторе.
+        idempotency_key (str | None): Ключ идемпотентности, если вызывающий его
+            вычислил. Нужен идемпотентной операции: без него матрица считает её
+            небезопасной.
+
+    Returns:
+        RetryDecision: Что матрица говорит о повторе.
+
+    Raises:
+        ConfigurationError: Если ни одна строка не подошла. Матрица обязана быть
+            полной: сочетание без строки означает, что реализации решат сами.
+    """
+    retryable = bool(getattr(type(error), "retryable", False))
+    effects = bool(getattr(type(error), "side_effects_possible", False))
+
+    for row_retryable, row_safety, row_effects, result in DECISION_MATRIX:
+        if row_retryable is not retryable:
+            continue
+        if row_safety is not None and row_safety != safety.value:
+            continue
+        if row_effects is not None and row_effects is not effects:
+            continue
+        return result
+
+    raise ConfigurationError(
+        f"матрица решения о повторе не покрывает сочетание: повторяемость "
+        f"{retryable}, безопасность {safety.value}, побочный эффект {effects}. "
+        "Неполная матрица означает, что реализации решат сами - и разойдутся"
+    )
+
+
+def plan_attempt(
+    error: FunoraError,
+    *,
+    attempt: int,
+    safety: Safety = Safety.SAFE,
+    idempotency_key: str | None = None,
+    retry_after_ms: int | None = None,
+    rand: Callable[[], float] = _random.random,
+) -> Attempt:
+    """Решает, повторять ли запрос после ошибки.
+
+    Args:
+        error (FunoraError): Ошибка, из-за которой попытка не удалась.
+        attempt (int): Номер завершившейся попытки, начиная с единицы.
+        safety (Safety): Безопасность операции при повторе.
+        retry_after_ms (int | None): Значение заголовка Retry-After в
+            миллисекундах, если площадка его прислала.
+        rand (Callable[[], float]): Источник случайности для разброса. Передаётся
+            снаружи, чтобы решение можно было проверить: со случайностью внутри
+            проверить нечего.
+
+    Returns:
+        Attempt: Решение вместе с причиной и применённой политикой.
+    """
+    policy = policy_for(error)
+
+    if not type(error).retryable:
+        return Attempt(False, 0, "error_not_retryable", policy)
+
+    if getattr(error, PROVISIONAL_ATTR, False):
+        return Attempt(False, 0, "verdict_provisional", policy)
+
+    decision = decide(error, safety)
+    if decision is RetryDecision.NEVER:
+        return Attempt(False, 0, "error_not_retryable", policy)
+    if decision is RetryDecision.RECONCILE_FIRST:
+        # Повтор запрещён не потому, что бесполезен, а потому, что опасен:
+        # операция небезопасна, и ошибка допускает побочный эффект. Прежде чем
+        # повторять, надо прочитать фактическое положение дел. Это тот случай,
+        # когда покупатель получает второе сообщение или второй ключ автовыдачи.
+        return Attempt(False, 0, "reconcile_first", policy)
+    if decision is RetryDecision.ALLOWED_WITH_KEY and idempotency_key is None:
+        # Без ключа идемпотентная операция ведёт себя как небезопасная - так
+        # сказано в самой матрице. Отказ здесь честнее повтора: ключ не
+        # придумывается реализацией, его вычисляет вызывающий по составу,
+        # объявленному у операции.
+        return Attempt(False, 0, "idempotency_key_required", policy)
+
+    limit = min(policy.max_attempts, GLOBAL_MAX_ATTEMPTS)
+    if attempt >= limit:
+        return Attempt(False, 0, f"attempts_exhausted:{limit}", policy)
+
+    if retry_after_ms is not None and policy.respect_retry_after:
+        # Верхняя граница обязательна: битое или враждебное значение вида
+        # 86400 секунд вешает цикл опроса на сутки, и снаружи это неотличимо
+        # от зависшего процесса.
+        delay = min(retry_after_ms, policy.max_retry_after_ms)
+        return Attempt(True, delay, "retry_after_header", policy)
+
+    ideal = policy.base_ms * (policy.multiplier ** (attempt - 1))
+    capped = min(int(ideal), policy.cap_ms)
+    delay = int(capped * rand()) if policy.jitter == "full" else capped
+    return Attempt(True, delay, "backoff", policy)
+
+
+#: Значение, которым обозначается отсутствие ожидания.
+NO_DELAY: Final[int] = 0

funora/_review_write.py

@@ -0,0 +1,138 @@
+"""Написание и снятие отзыва: адреса и разбор ответа.
+
+ОДНА ТОЧКА НА ТРИ ДЕЙСТВИЯ. Написать отзыв, ПРАВИТЬ уже написанный и ответить на
+чужой - всё это один адрес; различает их сама площадка по тому, кто автор и есть
+ли оценка. Отдельного адреса у правки нет, и потому повтор не создаёт второго
+отзыва, а переписывает тот же самый.
+
+УСПЕХ УСТАНАВЛИВАЕТСЯ ПОЛОЖИТЕЛЬНЫМ ПРИЗНАКОМ, и это главное отличие нашего
+разбора от стороннего.
+
+Независимая реализация того же протокола объявляет успехом отсутствие отказа:
+смотрит код ответа и в тело не заглядывает. Тело же несёт ПЕРЕРИСОВАННЫЙ виджет
+отзыва - готовый положительный признак, который остаётся только прочитать.
+
+Читаем мы его тем же разбором, что и отзыв на странице заказа: тот же класс
+.review-container, тот же атрибут data-rating. Разбор наш и наблюдён нами;
+чужое здесь - только то, что в ответе лежит именно он.
+
+Наблюдено нами: атрибуты data-order и data-author на странице заказа.
+Известно от FunPayAPI (FunPayCardinal, account.py): адреса, имена полей запроса
+и ключи ответа.
+"""
+
+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__ = [
+    "ReviewResult",
+    "parse_review_response",
+    "REVIEW_PATH",
+    "REVIEW_REMOVE_PATH",
+    "RATING_MIN",
+    "RATING_MAX",
+]
+
+#: Адрес написания отзыва. Известен от сторонней реализации.
+REVIEW_PATH: Final[str] = "/orders/review"
+
+#: Адрес снятия отзыва. Оттуда же.
+REVIEW_REMOVE_PATH: Final[str] = "/orders/reviewDelete"
+
+#: Наименьшая наблюдённая оценка.
+RATING_MIN: Final[int] = 1
+
+#: Наибольшая наблюдённая оценка.
+#:
+#: Границы стоят здесь, а не литералами в проверке: они наблюдение, и менять их
+#: можно только новым наблюдением. Что площадка сделает с шестёркой либо с нулём,
+#: никто не видел, и отправлять непроверенное мы не станем.
+RATING_MAX: Final[int] = 5
+
+
+@dataclass(frozen=True, slots=True)
+class ReviewResult:
+    """Исход написания либо снятия отзыва.
+
+    Attributes:
+        applied (bool): Удалось ли ПОДТВЕРДИТЬ исход положительным признаком.
+
+            Ложь означает не «не получилось», а «подтвердить не удалось»:
+            запрос ушёл, ответ пришёл, а виджет в нём не разобрался либо оценка
+            в нём не та, что отправляли. Различие существенное - первое
+            разрешает повторить, второе требует ПОСМОТРЕТЬ.
+        message (str): Сообщение площадки человеку, как есть. Не разбирается:
+            это текст на локали интерфейса.
+        rating (Observed[int]): Оценка, прочитанная В ОТВЕТЕ, а не отправленная
+            нами. Её сверка с отправленной и даёт applied. Ноль означает
+            отсутствие отзыва - так же, как на странице заказа.
+        observed_at (datetime): Момент получения ответа.
+    """
+
+    applied: bool
+    message: str
+    rating: Observed[int]
+    observed_at: datetime
+
+
+def parse_review_response(
+    payload: Any, *, expected_rating: int | None, observed_at: datetime
+) -> ReviewResult:
+    """Разбирает ответ площадки на написание либо снятие отзыва.
+
+    ОЖИДАЕМАЯ ОЦЕНКА - ЭТО ТО, ЧЕМ СВЕРЯЮТ, а не то, что подставляют. Придёт в
+    ответе другая - applied станет ложью, и вызывающий узнает, что площадка
+    сделала не то, о чём просили.
+
+    Аргументы:
+        payload (Any): Разобранное тело ответа.
+        expected_rating (int | None): Отправленная оценка либо None при снятии,
+            где ожидается отсутствие отзыва.
+        observed_at (datetime): Момент получения.
+
+    Возвращает:
+        ReviewResult: Исход.
+
+    Raises:
+        ProtocolChangedError: Если ответ непригоден для чтения вовсе.
+    """
+    if not isinstance(payload, dict):
+        raise ProtocolChangedError(
+            f"ответ на отзыв не объект, а {type(payload).__name__}. Что случилось "
+            "с отзывом - неизвестно"
+        )
+
+    raw_message = payload.get("msg")
+    message = raw_message if isinstance(raw_message, str) else ""
+
+    raw_content = payload.get("content")
+    if not isinstance(raw_content, str) or not raw_content.strip():
+        # Тела виджета нет - подтверждать нечем. Это НЕ отказ: запрос мог
+        # состояться, и объявлять неудачу так же неверно, как объявлять успех.
+        return ReviewResult(
+            applied=False,
+            message=message,
+            rating=Observed.missing("review_widget_absent_from_response"),
+            observed_at=observed_at,
+        )
+
+    # Разбор тот же, что у отзыва на странице заказа: те же селекторы, то же
+    # чтение. Второй разбор для той же разметки разошёлся бы с первым молча.
+    from ._order import parse_review_block
+
+    rating, _author, _defects = parse_review_block(raw_content)
+
+    expected = 0 if expected_rating is None else expected_rating
+    applied = rating.or_none() == expected
+    return ReviewResult(
+        applied=applied,
+        message=message,
+        rating=rating,
+        observed_at=observed_at,
+    )