funora 0.0.1.dev2__py3-none-any.whl

funora/_calc.py

@@ -0,0 +1,182 @@
+"""Расчёт цены покупателя по цене продавца.
+
+ЗАЧЕМ ЭТО НУЖНО. Цена, которую ставит продавец, и цена, которую платит
+покупатель, - РАЗНЫЕ ВЕЛИЧИНЫ: между ними комиссия площадки, и зависит она от
+способа оплаты.
+
+Разрыв этот наблюдаем нашим же снимком формы правки лота - там лежит таблица
+.table-buyers-prices, которую эта точка и перерисовывает, - а в контракте до
+31.08.2026 не назывался нигде. Молчание читалось как «цена одна».
+
+ЦЕНЫ ОТДАЮТСЯ ТЕКСТОМ, и это не лень. Разделитель дробной части нам не
+наблюдался, и перевод «1 234,56» в число зависит от локали.
+
+Сторонняя реализация, у которой взят состав запроса, здесь убирает пробелы и
+зовёт float. На локали с запятой это отказ САМОГО ЯЗЫКА - падение вместо ответа,
+и падение у вызывающего, который ничего такого не просил.
+
+Наблюдено нами: таблица итога на странице правки лота.
+Известно от FunPayAPI (FunPayCardinal, account.py, calc): адреса, имена полей
+запроса и ключи ответа.
+"""
+
+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__ = [
+    "PaymentMethod",
+    "PriceCalculation",
+    "parse_calculation",
+    "LOTS_CALC_PATH",
+    "CHIPS_CALC_PATH",
+]
+
+#: Адрес расчёта для обычных разделов. Известен от сторонней реализации.
+LOTS_CALC_PATH: Final[str] = "/lots/calc"
+
+#: Адрес расчёта для рынка по количеству. Оттуда же.
+CHIPS_CALC_PATH: Final[str] = "/chips/calc"
+
+
+@dataclass(frozen=True, slots=True)
+class PaymentMethod:
+    """Один способ оплаты и цена покупателя при нём.
+
+    Attributes:
+        name (str): Название способа на локали интерфейса, КАК ЕСТЬ. Не
+            разбирается и не классифицируется: выводить из него способ значило
+            бы строить разбор на переводе.
+        price_text (str): Цена покупателя текстом. Числом не отдаётся -
+            разделитель дробной части не наблюдался.
+        currency_symbol (Observed[str]): Знак валюты этой цены. Перевод в код
+            делает funora.currency_of_symbol.
+        sort (Observed[int]): Порядковое число, которым площадка сортирует
+            способы.
+    """
+
+    name: str
+    price_text: str
+    currency_symbol: Observed[str]
+    sort: Observed[int]
+
+
+@dataclass(frozen=True, slots=True)
+class PriceCalculation:
+    """Что заплатит покупатель за названную цену продавца.
+
+    Attributes:
+        methods (tuple[PaymentMethod, ...]): Способы оплаты и цены при них.
+            Пустой перечень означает наблюдение «способов не предложено», а не
+            неудачу разбора: последнюю выражает отказ.
+        min_price_text (Observed[str]): Наименьшая цена, которую площадка
+            разрешает поставить, КАК ОНА ЕЁ НАЗВАЛА - со знаком валюты и
+            целиком. Делить эту строку мы не станем: сторонняя реализация делит
+            её по последнему пробелу и зовёт float на первой половине.
+        asked_price (str): Цена продавца, о которой спрашивали.
+        observed_at (datetime): Момент получения ответа.
+    """
+
+    methods: tuple[PaymentMethod, ...]
+    min_price_text: Observed[str]
+    asked_price: str
+    observed_at: datetime
+
+
+def _sort_of(raw: Any) -> Observed[int]:
+    """Читает порядковое число способа оплаты.
+
+    Аргументы:
+        raw (Any): Значение из ответа.
+
+    Возвращает:
+        Observed[int]: Число либо причина отсутствия.
+    """
+    # Логическое исключается отдельно: истина в Python - это единица, и порядок
+    # True встал бы между нулевым и вторым, ни разу не будучи числом.
+    if isinstance(raw, bool):
+        return Observed.missing("sort_not_a_number")
+    if isinstance(raw, int):
+        return Observed.present(raw)
+    if isinstance(raw, str) and raw.strip().lstrip("-").isdigit():
+        return Observed.present(int(raw.strip()))
+    return Observed.missing("sort_not_a_number")
+
+
+def parse_calculation(payload: Any, *, asked_price: str, observed_at: datetime) -> PriceCalculation:
+    """Разбирает ответ площадки на расчёт цены.
+
+    Аргументы:
+        payload (Any): Разобранное тело ответа.
+        asked_price (str): Цена продавца, о которой спрашивали.
+        observed_at (datetime): Момент получения.
+
+    Возвращает:
+        PriceCalculation: Расчёт.
+
+    Raises:
+        ProtocolChangedError: Если ответ непригоден для чтения.
+    """
+    if not isinstance(payload, dict):
+        raise ProtocolChangedError(f"ответ расчёта не объект, а {type(payload).__name__}")
+
+    error = payload.get("error")
+    if error:
+        raise ProtocolChangedError(
+            f"площадка отказала в расчёте: {error!r}. Что именно ей не подошло - "
+            "неизвестно, а толковать её текст мы не станем"
+        )
+
+    raw_methods = payload.get("methods")
+    if not isinstance(raw_methods, list):
+        raise ProtocolChangedError(
+            "в ответе расчёта нет перечня способов оплаты. Пустой перечень и "
+            "отсутствующий - разные вещи: первый означает «способов не "
+            "предложено», второй - что мы читаем не тот ответ"
+        )
+
+    methods: list[PaymentMethod] = []
+    for one in raw_methods:
+        if not isinstance(one, dict):
+            raise ProtocolChangedError(f"способ оплаты не объект, а {type(one).__name__}")
+
+        raw_price = one.get("price")
+        if not isinstance(raw_price, str) or not raw_price.strip():
+            raise ProtocolChangedError(
+                "у способа оплаты нет цены строкой. Подставить сюда ноль значило "
+                "бы сказать продавцу, что покупатель заплатит ничего"
+            )
+
+        raw_name = one.get("name")
+        raw_unit = one.get("unit")
+        methods.append(
+            PaymentMethod(
+                name=raw_name if isinstance(raw_name, str) else "",
+                price_text=raw_price.strip(),
+                currency_symbol=(
+                    Observed.present(raw_unit.strip())
+                    if isinstance(raw_unit, str) and raw_unit.strip()
+                    else Observed.missing("unit_not_in_response")
+                ),
+                sort=_sort_of(one.get("sort")),
+            )
+        )
+
+    raw_min = payload.get("minPrice")
+    minimum = (
+        Observed.present(raw_min.strip())
+        if isinstance(raw_min, str) and raw_min.strip()
+        else Observed.missing("min_price_not_in_response")
+    )
+
+    return PriceCalculation(
+        methods=tuple(methods),
+        min_price_text=minimum,
+        asked_price=asked_price,
+        observed_at=observed_at,
+    )

funora/_canonical.py

@@ -0,0 +1,235 @@
+"""Каноническая сериализация JSON.
+
+Правила объявлены в docs/canonical-json.md спецификации и до сих пор не
+выполнялись ни одной строкой кода. Файл состояния при этом штамповал в себя
+`canonical_form_version` - то есть утверждал про себя то, чего никто не делал:
+он писался с пробелами после двоеточия и запятой, с числами с плавающей точкой
+и без нормализации Unicode.
+
+Зачем форма нужна. Отпечаток события - ключ идемпотентности, общий для шести
+реализаций. Если байты, от которых считается хэш, зависят от того, каким
+сериализатором пользуется язык, то две реализации дадут одному событию два
+разных идентификатора, и гашение повторов у человека, подключившего обе, не
+сработает ни разу. Для обработчика выдачи это выданный дважды товар.
+
+Форма нарочно узкая. Она не универсальный сериализатор и не должна им быть:
+всё, чего она не умеет выразить однозначно, она отвергает вслух. Число с
+плавающей точкой не имеет единственного десятичного вида, поэтому запрещено;
+ключ не-строка не имеет порядка по кодовым точкам, поэтому запрещён.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import unicodedata
+from datetime import UTC, datetime
+from typing import Any, Final, NoReturn
+
+from ._money import Money
+from .errors import ValidationError
+
+__all__ = [
+    "canonical_dumps",
+    "canonical_instant",
+    "canonical_normalize",
+]
+
+#: Разделители без единого незначащего пробела.
+#:
+#: Правило 5. Умолчание Python - ``(", ", ": ")``, и именно оно делало файл
+#: состояния неканоническим, оставаясь незаметным: JSON от этого не перестаёт
+#: разбираться, расходятся только байты - то есть ровно то, от чего берут хэш.
+_SEPARATORS: Final[tuple[str, str]] = (",", ":")
+
+
+def canonical_normalize(text: str) -> str:
+    """Приводит строку к форме Unicode NFC.
+
+    Правило 2. Одна и та же буква записывается по-разному: «ё» бывает одним
+    знаком и парой «е» с диакритикой. Глазами не отличить, байтами - разные
+    строки, и хэш от них разный.
+
+    Откуда берётся разница: страница приходит из сети, проходит через стек
+    HTTP и разборщик разметки, и каждый из них вправе нормализовать текст
+    по-своему. Две реализации на разных языках получат из одной страницы разные
+    байты одного и того же идентификатора.
+
+    Args:
+        text (str): Исходная строка.
+
+    Returns:
+        str: Та же строка в форме NFC.
+    """
+    return unicodedata.normalize("NFC", text)
+
+
+def canonical_instant(value: datetime) -> str:
+    """Приводит момент к канонической форме.
+
+    Правило 13: RFC 3339 в UTC, суффикс Z, ровно три знака миллисекунд. Три, а
+    не шесть и не сколько получится: длина части после точки меняет байты, а
+    байты входят в хэш.
+
+    Доля миллисекунды ОТБРАСЫВАЕТСЯ, а не округляется. Округление вправе
+    сдвинуть момент вперёд - объявить, что наблюдение случилось позже, чем
+    случилось. Отбрасывание сдвигает назад, то есть говорит «не позже чем», и
+    это единственная сторона, в которую метке времени ошибаться безопасно.
+
+    Args:
+        value (datetime): Момент. Со смещением, отличным от Z, переводится в
+            UTC: смещение - законная запись того же момента.
+
+    Returns:
+        str: Каноническая запись момента.
+
+    Raises:
+        ValidationError: Если у момента нет часового пояса. Счесть его UTC либо
+            местным - домысел, а цена домысла здесь до суток разницы:
+            наблюдение окажется в будущем либо в прошлом, и отпечаток события
+            разойдётся у двух реализаций, работающих в разных поясах.
+    """
+    if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+        raise ValidationError(
+            f"момент {value!r} без часового пояса. Счесть его UTC либо местным - "
+            "домысел ценой до суток разницы; передайте момент с поясом"
+        )
+
+    moment = value.astimezone(UTC)
+    stamp = moment.strftime("%Y-%m-%dT%H:%M:%S")
+    return f"{stamp}.{moment.microsecond // 1000:03d}Z"
+
+
+def _reject(value: Any, where: str) -> NoReturn:
+    """Отвергает значение, которое каноническая форма выразить не может.
+
+    Args:
+        value (Any): Значение.
+        where (str): Путь до значения, для сообщения.
+
+    Returns:
+        None
+
+    Raises:
+        ValidationError: Всегда.
+    """
+    raise ValidationError(
+        f"каноническая форма не выражает {type(value).__name__} однозначно "
+        f"(путь {where}). Значение: {value!r}"
+    )
+
+
+def _prepare(value: Any, where: str) -> Any:
+    """Готовит значение к сериализации: нормализует и проверяет.
+
+    Args:
+        value (Any): Значение любого поддерживаемого вида.
+        where (str): Путь до значения, для сообщения об отказе.
+
+    Returns:
+        Any: Значение, годное для json.dumps в канонической форме.
+
+    Raises:
+        ValidationError: Если значение невыразимо: число с плавающей точкой,
+            ключ не-строка, множество, произвольный объект.
+    """
+    if value is None or isinstance(value, bool):
+        return value
+
+    if isinstance(value, int):
+        # Правило 7: целое выводится без дробной части и без экспоненты - так
+        # json.dumps и делает. Правило 9 про -0 здесь не нужно: в Python -0
+        # целое неотличимо от 0.
+        return value
+
+    if isinstance(value, float):
+        # Правило 8. Отвергать, а не округлять: округление - это молчаливая
+        # подмена значения, а её последствие всплывёт в чужом хэше через
+        # неделю. Отдельно называем не-числа, потому что json.dumps пишет их
+        # как NaN и Infinity - и получившийся файл перестаёт быть JSON, хотя
+        # Python читает его обратно как ни в чём не бывало.
+        if math.isnan(value) or math.isinf(value):
+            raise ValidationError(
+                f"каноническая форма запрещает {value!r} (путь {where}): "
+                "JSON такого значения не знает, и файл с ним перестаёт быть "
+                "разбираемым чем-либо, кроме Python"
+            )
+        raise ValidationError(
+            f"каноническая форма запрещает числа с плавающей точкой "
+            f"(путь {where}, значение {value!r}). У них нет единственного "
+            "десятичного вида, и две реализации запишут их по-разному. "
+            "Выразите величину целым: деньги - минорными единицами, время - "
+            "миллисекундами"
+        )
+
+    if isinstance(value, Money):
+        # Порядок ключей задаёт правило 3, а не это перечисление: словарь
+        # сортируется по кодовым точкам при выводе.
+        return {
+            "amount_minor": value.amount_minor,
+            "currency": value.currency,
+            "scale": value.scale,
+        }
+
+    if isinstance(value, datetime):
+        # Момент выражается строкой канонической формы, а не отвергается: он
+        # объявлен доменным типом, и правило его вида - часть той же формы.
+        return canonical_instant(value)
+
+    if isinstance(value, str):
+        return canonical_normalize(value)
+
+    if isinstance(value, dict):
+        prepared: dict[str, Any] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValidationError(
+                    f"каноническая форма требует строковых ключей "
+                    f"(путь {where}, ключ {key!r}). Порядок ключей задан по "
+                    "кодовым точкам, а у не-строки кодовых точек нет"
+                )
+            # Нормализация ДО сортировки, а не после: NFC меняет кодовые
+            # точки, и порядок, снятый с ненормализованных ключей, разошёлся
+            # бы с порядком, снятым с нормализованных.
+            canonical_key = canonical_normalize(key)
+            if canonical_key in prepared:
+                raise ValidationError(
+                    f"после нормализации ключи {key!r} и другой ключ совпали "
+                    f"(путь {where}). Каноническая форма не решает, какой из "
+                    "них оставить, - это должен решить вызывающий"
+                )
+            prepared[canonical_key] = _prepare(item, f"{where}.{canonical_key}")
+        return prepared
+
+    if isinstance(value, (list, tuple)):
+        # Правило 4: порядок элементов значим и не сортируется.
+        return [_prepare(item, f"{where}[{index}]") for index, item in enumerate(value)]
+
+    _reject(value, where)
+
+
+def canonical_dumps(value: Any) -> str:
+    """Сериализует значение в каноническую форму.
+
+    Выполняются правила 1-9 документа: UTF-8 без BOM, NFC, ключи по кодовым
+    точкам, порядок массива сохраняется, никаких незначащих пробелов,
+    минимальное экранирование, целые без экспоненты, никаких чисел с
+    плавающей точкой, никакого -0.
+
+    Args:
+        value (Any): Значение: словарь, список, строка, целое, булево, None.
+
+    Returns:
+        str: Каноническое представление. Строка, а не байты: кодировка UTF-8
+        применяется при записи, и делать это дважды незачем.
+
+    Raises:
+        ValidationError: Если значение невыразимо канонической формой.
+    """
+    return json.dumps(
+        _prepare(value, "$"),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=_SEPARATORS,
+        allow_nan=False,
+    )