funora 0.0.1.dev2__py3-none-any.whl

funora/_market.py

@@ -0,0 +1,406 @@
+"""Чтение публичного списка предложений раздела.
+
+То, что видит ПОКУПАТЕЛЬ, ищущий товар. Не витрина продавца и не страница
+управления: здесь предложения многих продавцов в одном разделе, и потому здесь
+есть колонка, которой нет больше нигде, - сам продавец.
+
+ЛОВУШКА ЗДЕСЬ ОДНА И ДОРОГАЯ. У строки есть атрибут data-user, и по имени он
+ровно то, что нужно. Он не то.
+
+Атрибут есть у строки ТОГДА И ТОЛЬКО ТОГДА, когда предложение поднято.
+Наблюдено точным совпадением в обе стороны: семьдесят строк с классом
+offer-promo - и ровно у этих семидесяти есть data-user; две тысячи девятьсот
+тридцать одна строка без класса - и ни у одной из них его нет.
+
+Разбор, читающий продавца оттуда, отдал бы его у двух процентов предложений и
+выглядел бы работающим: поля заполняются, ошибок нет, а поднятые предложения
+показываются первыми и попадают в глаза первыми.
+
+Продавец лежит в ссылке на профиль внутри строки. Она есть у всех трёх тысяч
+одной строки, и различных значений четыреста семьдесят девять - против четырёх
+различных data-user. Числа расходятся на два порядка, и это и есть
+доказательство.
+
+ЛЕНИВАЯ ЗАГРУЗКА - НЕ УСЕЧЕНИЕ. Две тысячи восемьсот одна строка несёт класс
+lazyload-hidden, и все они присутствуют в теле ответа наравне с прочими. Класс
+говорит о показе, а не о наличии: список прочитан весь одним ответом, догружать
+нечего.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Final
+from urllib.parse import parse_qsl, urlsplit
+
+from selectolax.parser import HTMLParser, Node
+
+from ._money import Money, parse_display_price
+from ._observed import Observed
+from ._result import Completeness, Defect, Severity
+from .errors import IncompleteResultError, ProtocolChangedError, ValidationError
+from .extraction import ATTRIBUTES, QUERY_PARAMS, SELECTORS
+
+__all__ = ["MarketOffer", "MarketPage", "parse_market"]
+
+_ROW: Final[str] = SELECTORS["market.rows"]
+_SERVER: Final[str] = SELECTORS["market.fields.server_text"]
+_DESCRIPTION: Final[str] = SELECTORS["market.fields.description_text"]
+_SELLER_LINK: Final[str] = SELECTORS["market.fields.seller_link"]
+_SELLER_NAME: Final[str] = SELECTORS["market.fields.seller_name"]
+_PRICE_CELL: Final[str] = SELECTORS["market.fields.price_cell"]
+_PRICE_TEXT: Final[str] = SELECTORS["market.fields.price_text"]
+_CURRENCY: Final[str] = SELECTORS["market.fields.currency_symbol_text"]
+
+_OFFER_HREF: Final[str] = ATTRIBUTES["market.rows.attributes.offer_href"]
+
+#: Имя параметра, в котором лежит идентификатор предложения.
+#:
+#: Берётся из порождённой таблицы, а не пишется литералом: имя выбирает
+#: площадка, и живя в двух местах, оно разошлось бы с объявлением молча.
+_OFFER_ID_PARAM: Final[str] = QUERY_PARAMS["market.rows.attributes.offer_id"]
+_SERVER_ID: Final[str] = ATTRIBUTES["market.rows.attributes.server_id"]
+_FILTER_TYPE: Final[str] = ATTRIBUTES["market.rows.attributes.filter_type"]
+_SELLER_HREF: Final[str] = ATTRIBUTES["market.fields.seller_link.attributes.seller_href"]
+_SORT_VALUE: Final[str] = ATTRIBUTES["market.fields.price_cell.attributes.sort_value"]
+_ONLINE: Final[str] = ATTRIBUTES["market.markers.online.attribute"]
+
+#: Классы, которыми площадка помечает поднятое предложение.
+#:
+#: Их два, и они не одно и то же: offer-promo наблюдён у семидесяти строк,
+#: offer-promoted - у одной, и она же первая на странице. Что означает различие,
+#: не установлено: наблюдалась одна страница.
+_PROMO: Final[str] = "offer-promo"
+_PROMOTED: Final[str] = "offer-promoted"
+
+
+@dataclass(frozen=True, slots=True)
+class MarketOffer:
+    """Одно предложение в списке раздела.
+
+    Attributes:
+        offer_id (Observed[str]): Идентификатор предложения.
+
+            ЛЕЖИТ ОН В СТРОКЕ ЗАПРОСА ССЫЛКИ И БОЛЬШЕ НИГДЕ, и до формата
+            скелета v9 наблюдать его было нельзя: снимок заменял строку запроса
+            одной подписью. Из-за этого market.offers не собиралась вовсе, а
+            причиной называли модель.
+
+            Наблюдено 31.08.2026: параметр называется id, значение - восемь
+            цифр, и есть он у всех 1417 строк.
+        offer_href (Observed[str]): Ссылка на предложение целиком.
+        seller_href (Observed[str]): Ссылка на профиль продавца. НАСТОЯЩИЙ
+            продавец строки - не атрибут data-user, которого у большинства строк
+            нет вовсе.
+        seller_name_text (Observed[str]): Отображаемое имя продавца.
+        seller_online (bool): Наблюдался ли признак «в сети».
+        server_text (Observed[str]): Название сервера, как показано.
+        server_id (Observed[str]): Идентификатор сервера из атрибута.
+        filter_type (Observed[str]): Значение фильтра строки.
+        description_text (Observed[str]): Описание, как показано.
+        price_text (Observed[str]): Цена без знака валюты.
+        currency_symbol_text (Observed[str]): Знак валюты.
+        sort_value (Observed[str]): Значение сортировки ячейки цены.
+        price (Observed[Money]): Показанная цена при scale 6, без округления.
+        promoted (bool): Помечено ли предложение поднятым.
+        row_index (int): Место строки, считая с нуля.
+    """
+
+    offer_id: Observed[str]
+    offer_href: Observed[str]
+    seller_href: Observed[str]
+    seller_name_text: Observed[str]
+    seller_online: bool
+    server_text: Observed[str]
+    server_id: Observed[str]
+    filter_type: Observed[str]
+    description_text: Observed[str]
+    price_text: Observed[str]
+    currency_symbol_text: Observed[str]
+    sort_value: Observed[str]
+    promoted: bool
+    row_index: int
+    price: Observed[Money] = field(default_factory=lambda: Observed.missing("price_not_normalized"))
+
+
+@dataclass(frozen=True, slots=True)
+class MarketPage:
+    """Публичный список предложений одного раздела.
+
+    Attributes:
+        completeness (Completeness): Полнота чтения.
+        reason (str | None): Причина неполноты.
+        observed_at (datetime): Момент наблюдения.
+        rows_total (int): Сколько строк нашлось.
+        rows_accepted (int): Сколько собрано.
+        rows_lazy (int): Сколько строк помечено ленивой загрузкой. Усечением это
+            НЕ является: разметка отдана целиком, класс говорит о показе.
+        defects (tuple[Defect, ...]): Замеченные повреждения.
+    """
+
+    completeness: Completeness
+    reason: str | None
+    observed_at: datetime
+    rows_total: int
+    rows_accepted: int
+    rows_lazy: int
+    defects: tuple[Defect, ...] = ()
+    _offers: tuple[MarketOffer, ...] = field(default=(), repr=False)
+
+    def offers(self, *, accept_incomplete: bool = False) -> tuple[MarketOffer, ...]:
+        """Возвращает собранные предложения.
+
+        Args:
+            accept_incomplete (bool): Признание готовности работать с неполным
+                результатом.
+
+        Returns:
+            tuple[MarketOffer, ...]: Предложения в порядке появления.
+
+        Raises:
+            IncompleteResultError: Если полнота отлична от COMPLETE, а неполнота
+                не признана.
+        """
+        if self.completeness is not Completeness.COMPLETE and not accept_incomplete:
+            raise IncompleteResultError(
+                f"список прочитан не полностью ({self.completeness}, причина: "
+                f"{self.reason}), собрано {self.rows_accepted} из {self.rows_total}. "
+                "Передайте accept_incomplete=True, если готовы работать с неполными "
+                "данными"
+            )
+        return self._offers
+
+
+def _text(node: Node | None, name: str) -> Observed[str]:
+    """Читает текст узла как наблюдение.
+
+    Args:
+        node (Node | None): Узел либо None.
+        name (str): Имя поля для причины отсутствия.
+
+    Returns:
+        Observed[str]: Наблюдение.
+    """
+    if node is None:
+        return Observed.missing(f"selector_no_match:{name}")
+    value = " ".join((node.text() or "").split())
+    return Observed.present(value) if value else Observed.empty("")
+
+
+def _own_text(node: Node | None, name: str) -> Observed[str]:
+    """Читает собственный текст узла, без текста вложенных.
+
+    Args:
+        node (Node | None): Узел либо None.
+        name (str): Имя поля для причины отсутствия.
+
+    Returns:
+        Observed[str]: Наблюдение.
+    """
+    if node is None:
+        return Observed.missing(f"selector_no_match:{name}")
+    own = " ".join((node.text(deep=False) or "").split())
+    return Observed.present(own) if own else Observed.empty("")
+
+
+def _attribute(node: Node | None, name: str, field_name: str) -> Observed[str]:
+    """Читает атрибут узла как наблюдение.
+
+    Args:
+        node (Node | None): Узел либо None.
+        name (str): Имя атрибута.
+        field_name (str): Имя поля для причины отсутствия.
+
+    Returns:
+        Observed[str]: Наблюдение.
+    """
+    if node is None:
+        return Observed.missing(f"carrier_missing:{field_name}")
+    attributes = node.attributes or {}
+    if name not in attributes:
+        return Observed.missing(f"attribute_absent:{field_name}")
+    value = (attributes.get(name) or "").strip()
+    return Observed.present(value) if value else Observed.empty("")
+
+
+def _classes(node: Node) -> set[str]:
+    """Возвращает классы узла множеством.
+
+    Разбор идёт по ТОКЕНАМ, а не по подстроке: подстрока «tc-server» входит и в
+    «tc-server-inside», и счёт по ней разошёлся бы вдвое.
+
+    Args:
+        node (Node): Узел.
+
+    Returns:
+        set[str]: Классы.
+    """
+    return set(((node.attributes or {}).get("class") or "").split())
+
+
+def _query_param(href: Observed[str], name: str, field_name: str) -> Observed[str]:
+    """Достаёт параметр строки запроса из наблюдённого адреса.
+
+    ЧИТАЕТСЯ ИЗ УЖЕ НАБЛЮДЁННОГО, а не из узла заново. Так наблюдённость
+    наследуется честно: нет ссылки - нет и идентификатора, и причина у обоих
+    одна.
+
+    Аргументы:
+        href (Observed[str]): Адрес, каким его прочитали.
+        name (str): Имя параметра.
+        field_name (str): Имя поля для причины ненаблюдения.
+
+    Возвращает:
+        Observed[str]: Значение параметра либо причина, по которой его нет.
+    """
+    if not href.is_observed:
+        return Observed.missing(f"carrier_missing:{field_name}")
+
+    for key, value in parse_qsl(urlsplit(href.value).query, keep_blank_values=True):
+        if key != name:
+            continue
+        # Пустое значение параметра - не идентификатор. Отдать его значило бы
+        # выдать «id=» за прочитанный лот.
+        return Observed.present(value) if value else Observed.missing(f"empty:{field_name}")
+    return Observed.missing(f"no_query_param:{name}")
+
+
+def _row(node: Node, index: int) -> tuple[MarketOffer, list[Defect]]:
+    """Собирает одно предложение из строки.
+
+    Продавец читается из ССЫЛКИ НА ПРОФИЛЬ, а не из атрибута data-user: тот есть
+    только у поднятых строк, и разбор по нему отдал бы продавца у двух процентов
+    списка.
+
+    Args:
+        node (Node): Узел строки.
+        index (int): Место строки.
+
+    Returns:
+        tuple[MarketOffer, list[Defect]]: Предложение и перечень повреждений.
+    """
+    defects: list[Defect] = []
+    seller_link = node.css_first(_SELLER_LINK)
+    seller_href = _attribute(seller_link, _SELLER_HREF, "seller_href")
+    if not seller_href.is_observed:
+        defects.append(
+            Defect(
+                severity=Severity.ROW,
+                code="seller_link_missing",
+                detail=(
+                    f"у строки нет ссылки на профиль продавца ({_SELLER_LINK}, атрибут "
+                    f"{_SELLER_HREF}). Это единственный носитель продавца, годный для "
+                    "всех строк: атрибут data-user есть только у поднятых"
+                ),
+                row_index=index,
+                field_name="seller_href",
+            )
+        )
+
+    price_cell = node.css_first(_PRICE_CELL)
+    classes = _classes(node)
+    offer_href = _attribute(node, _OFFER_HREF, "offer_href")
+    offer_id = _query_param(offer_href, _OFFER_ID_PARAM, "offer_id")
+    if not offer_id.is_observed and offer_href.is_observed:
+        defects.append(
+            Defect(
+                severity=Severity.ROW,
+                code="offer_id_missing",
+                detail=(
+                    f"в ссылке строки нет параметра {_OFFER_ID_PARAM!r}. Это "
+                    "единственный носитель идентификатора чужого предложения: "
+                    "атрибутом он не выносится нигде"
+                ),
+                row_index=index,
+                field_name="offer_id",
+            )
+        )
+    price_text = _own_text(node.css_first(_PRICE_TEXT), "price_text")
+    currency_symbol = _text(node.css_first(_CURRENCY), "currency_symbol_text")
+    price: Observed[Money] = Observed.missing("price_source_unobserved")
+    if price_text.is_observed and currency_symbol.is_observed:
+        try:
+            price = Observed.present(parse_display_price(price_text.value, currency_symbol.value))
+        except ValidationError:
+            price = Observed.missing("price_not_normalizable")
+            defects.append(
+                Defect(
+                    severity=Severity.FIELD,
+                    code="price_not_normalizable",
+                    detail="показанная цена не переводится в Money без потери точности",
+                    row_index=index,
+                    field_name="price",
+                )
+            )
+    return (
+        MarketOffer(
+            offer_id=offer_id,
+            offer_href=offer_href,
+            seller_href=seller_href,
+            seller_name_text=_text(node.css_first(_SELLER_NAME), "seller_name_text"),
+            # Признак читается НАЛИЧИЕМ атрибута, а не значением: значение
+            # наблюдалось одно на всех строках, где атрибут есть, а отсутствие
+            # наблюдалось у восьмисот девятнадцати строк той же страницы.
+            seller_online=_ONLINE in (node.attributes or {}),
+            server_text=_text(node.css_first(_SERVER), "server_text"),
+            server_id=_attribute(node, _SERVER_ID, "server_id"),
+            filter_type=_attribute(node, _FILTER_TYPE, "filter_type"),
+            description_text=_text(node.css_first(_DESCRIPTION), "description_text"),
+            price_text=price_text,
+            currency_symbol_text=currency_symbol,
+            price=price,
+            sort_value=_attribute(price_cell, _SORT_VALUE, "sort_value"),
+            promoted=bool(classes & {_PROMO, _PROMOTED}),
+            row_index=index,
+        ),
+        defects,
+    )
+
+
+def parse_market(html: str, *, observed_at: datetime) -> MarketPage:
+    """Разбирает публичный список предложений раздела.
+
+    Args:
+        html (str): Тело страницы.
+        observed_at (datetime): Момент наблюдения. Передаётся снаружи, чтобы
+            разбор оставался чистым и повторяемым на сохранённом снимке.
+
+    Returns:
+        MarketPage: Предложения раздела.
+
+    Raises:
+        ProtocolChangedError: Если на странице нет ни одной строки. Пустой список
+            вернуть нельзя: он неотличим от смены разметки, а разница решает,
+            искать ли товар в другом разделе.
+    """
+    tree = HTMLParser(html)
+    rows = tree.css(_ROW)
+    if not rows:
+        raise ProtocolChangedError(
+            f"на странице нет ни одной строки предложения ({_ROW}). Пустой список "
+            "вернуть нельзя: он неотличим от смены разметки, а разница решает, искать "
+            "ли товар в другом разделе"
+        )
+
+    offers: list[MarketOffer] = []
+    defects: list[Defect] = []
+    lazy = 0
+    for index, node in enumerate(rows):
+        if "lazyload-hidden" in _classes(node):
+            lazy += 1
+        offer, row_defects = _row(node, index)
+        offers.append(offer)
+        defects += row_defects
+
+    damaged = any(one.severity is Severity.ROW for one in defects)
+    return MarketPage(
+        completeness=Completeness.PARTIAL if damaged else Completeness.COMPLETE,
+        reason="rows_damaged" if damaged else None,
+        observed_at=observed_at,
+        rows_total=len(rows),
+        rows_accepted=len(offers),
+        rows_lazy=lazy,
+        defects=tuple(defects),
+        _offers=tuple(offers),
+    )

funora/_matching.py

@@ -0,0 +1,147 @@
+"""Сопоставление заказа с собственным лотом.
+
+ЗАЧЕМ. Автовыдача обязана знать, ЧТО выдавать. Идентификатора предложения в
+заказе нет: ни строка списка продаж, ни страница заказа его не несут. Есть
+только описание - свободный текст, который продавец написал у лота, а площадка
+показала в заказе.
+
+Значит вывод, а не наблюдение, и уверенность у результата всегда выведенная.
+
+ПОЧЕМУ ЭТО ВСЁ ЖЕ ГОДИТСЯ. Круг кандидатов сужается СТРУКТУРНО, а не текстом: со
+страницы заказа приходит адрес раздела, и сравнивать приходится только с лотами
+этого раздела. Не «текст против текста по всей площадке», а «текст против текста
+внутри одного раздела, выбранного точно».
+
+ЧЕМ ЭТО ОТЛИЧАЕТСЯ ОТ ОБЫЧНОГО. Двусмысленность здесь - отказ, а не выбор.
+Готовое решение той же задачи берёт при нескольких совпадениях самое длинное;
+для выдачи товара это выбор наугад, и цена ошибки - чужой товар покупателю.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+from typing import Final
+
+from ._observed import Confidence, Observed
+
+__all__ = ["MatchOutcome", "match_offer", "normalized_for_match"]
+
+#: Причина, по которой лот не выбран: совпадений нет вовсе.
+NO_MATCH: Final[str] = "no_offer_matched"
+
+#: Причина: совпадений несколько, и они не вложены друг в друга.
+AMBIGUOUS: Final[str] = "offer_match_ambiguous"
+
+#: Причина: у заказа нет описания, сравнивать не с чем.
+NO_ORDER_TEXT: Final[str] = "order_description_not_observed"
+
+
+@dataclass(frozen=True, slots=True)
+class MatchOutcome:
+    """Чем кончилось сопоставление.
+
+    Attributes:
+        offer_id (Observed[str]): Идентификатор выбранного предложения.
+            Ненаблюдённый, если выбрать не удалось.
+        candidates (tuple[str, ...]): Идентификаторы всех подошедших
+            предложений. При отказе по двусмысленности их больше одного, и
+            перечень нужен человеку: по нему видно, какие именно лоты
+            неразличимы, и какой из них переименовать.
+    """
+
+    offer_id: Observed[str]
+    candidates: tuple[str, ...]
+
+
+def normalized_for_match(text: str) -> str:
+    """Приводит текст к виду, пригодному для сравнения.
+
+    Три действия, и каждое против своего вида расхождения. Совместимая
+    нормализация Unicode сводит разные записи одного знака к одной. Приведение
+    регистра снимает различие прописных и строчных. Схлопывание пробельных
+    последовательностей снимает разницу между одним пробелом, двумя и переводом
+    строки: площадка показывает текст в разметке, и переносы в нём случайны.
+
+    Аргументы:
+        text (str): Исходный текст.
+
+    Возвращает:
+        str: Текст, пригодный для сравнения.
+    """
+    return " ".join(unicodedata.normalize("NFKC", text).casefold().split())
+
+
+def match_offer(order_description: Observed[str], lots: dict[str, Observed[str]]) -> MatchOutcome:
+    """Ищет собственный лот, о котором идёт речь в заказе.
+
+    ИЩЕТСЯ ВХОЖДЕНИЕ ОПИСАНИЯ ЛОТА В ОПИСАНИЕ ЗАКАЗА, и только оно. Не
+    равенство: площадка дописывает к описанию заказа то, что выбрал покупатель.
+    Не обратное вхождение: описание заказа, оказавшееся внутри описания лота,
+    означало бы, что лот описан подробнее заказа, - а это признак не того лота.
+
+    ПУСТОЕ ОПИСАНИЕ ЛОТА НИКОГДА НЕ КАНДИДАТ. Пустая строка входит в любую, и
+    один лот с пустым описанием совпал бы разом со всеми заказами.
+
+    НЕСКОЛЬКО КАНДИДАТОВ - ОТКАЗ. Исключение ровно одно и оно проверяемо: если
+    все кандидаты вложены друг в друга одной цепочкой, берётся самый длинный.
+    Цепочка означает, что лоты описаны уточнением друг друга, и длиннейший
+    описывает точнее. Развилка - два лота, ни один из которых не уточняет
+    другого, - означает, что различить их нечем, и выбирать наугад нельзя.
+
+    Аргументы:
+        order_description (Observed[str]): Описание из строки списка продаж.
+        lots (dict[str, Observed[str]]): Описания собственных лотов по
+            идентификатору предложения.
+
+    Возвращает:
+        MatchOutcome: Выбранное предложение либо честная причина отказа.
+    """
+    if not order_description.is_observed or not order_description.value.strip():
+        return MatchOutcome(Observed.missing(NO_ORDER_TEXT), ())
+
+    haystack = normalized_for_match(order_description.value)
+
+    hits: list[tuple[str, str]] = []
+    for offer_id, description in lots.items():
+        if not description.is_observed:
+            continue
+        needle = normalized_for_match(description.value)
+        if not needle:
+            continue
+        if needle in haystack:
+            hits.append((offer_id, needle))
+
+    if not hits:
+        return MatchOutcome(Observed.missing(NO_MATCH), ())
+
+    if len(hits) == 1:
+        # Уверенность ВЫВЕДЕННАЯ, и другой у неё быть не может: правило
+        # опирается на текст, часть которого пишет не площадка.
+        return MatchOutcome(Observed.present(hits[0][0], Confidence.INFERRED), (hits[0][0],))
+
+    ordered = sorted(hits, key=lambda one: len(one[1]))
+
+    # Вложенность требуется СТРОГАЯ: каждое следующее описание длиннее
+    # предыдущего и содержит его.
+    #
+    # Строгость здесь не педантизм, и стоила она дорого. Правило без неё
+    # считало цепочкой два лота с ОДИНАКОВЫМ описанием: строка входит сама в
+    # себя, условие выполнялось, и выбирался тот, что оказался последним после
+    # сортировки, - то есть наугад.
+    #
+    # Два лота с одинаковым описанием - это ровно тот случай, ради которого
+    # отказ и придуман: различить их нечем. Покупателю ушёл бы чужой товар, и
+    # ни в отказе, ни в журнале следа бы не осталось.
+    chained = all(
+        len(ordered[index][1]) < len(ordered[index + 1][1])
+        and ordered[index][1] in ordered[index + 1][1]
+        for index in range(len(ordered) - 1)
+    )
+    if chained:
+        return MatchOutcome(
+            Observed.present(ordered[-1][0], Confidence.INFERRED),
+            tuple(one[0] for one in ordered),
+        )
+
+    return MatchOutcome(Observed.missing(AMBIGUOUS), tuple(sorted(one[0] for one in hits)))