funora 0.0.1.dev2__py3-none-any.whl

funora/_reviews.py

@@ -0,0 +1,584 @@
+"""Разбор отзывов со страницы профиля продавца.
+
+Модуль чистый по тем же причинам, что и разбор списка продаж: вход - разметка и
+момент наблюдения, выход - страница записей, и повторить его на сохранённом
+снимке спустя полгода обязано давать тот же результат.
+
+Три решения отличают его от разбора продаж.
+
+Оценка читается из ИМЕНИ КЛАССА, а не из текста. У узла оценки текста нет
+вовсе: площадка рисует звёзды стилями, а число прячет в классе - div.rating5.
+Перечисление закрыто по наблюдению, а не по догадке: площадка сама перечислила
+все пять уровней в выпадающем списке фильтра отзывов.
+
+Узлов оценки в строке ДВА, а не один - широкий макет и узкий. Значение в них
+одно и то же, и разбор обязан их сверить. Взять первый попавшийся значило бы
+повторить ошибку, на которой уже спотыкался разбор продаж: он брал первый
+[data-href] строки, в снимке их было два, оба вели на одного человека, и ошибка
+не была видна ровно до того дня, когда перестала бы.
+
+Полнота определяется строками и наблюдённым управлением догрузкой. COMPLETE
+подтверждает конец текущей выборки при целостном ответе. Продолжение связано
+с продавцом и выбранной оценкой, которую сервер может не повторять в форме.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Final
+
+from selectolax.parser import HTMLParser, Node
+
+from ._cursor import decode_cursor, encode_cursor
+from ._extract import attribute
+from ._observed import Observed
+from ._result import Completeness, Defect, Severity, collect_rows
+from .errors import (
+    CursorIncompatibleError,
+    IncompleteResultError,
+    ProtocolChangedError,
+    ValidationError,
+)
+from .extraction import SELECTORS
+
+__all__ = ["Review", "ReviewsCursor", "ReviewsPage", "parse_reviews_page"]
+
+#: Внешний контейнер таблицы отзывов.
+_TABLE: Final[str] = SELECTORS["reviews.table"]
+
+#: Контейнер строк. Тот же класс, что у списка продаж: площадка переиспользует
+#: виджет dyn-table.
+_ROWS_CONTAINER: Final[str] = SELECTORS["reviews.rows_container"]
+
+#: Строка отзыва.
+_ROW: Final[str] = SELECTORS["reviews.row"]
+
+#: Кнопка догрузки. Стоит сразу за таблицей отзывов.
+#:
+#: Утром 24.08.2026 контракт утверждал, что её нет: перебор классов по образцу
+#: more|pagin|load|next|prev ничего не нашёл, и это приняли за отсутствие.
+#: Названа она иначе, и образец её не поймал.
+_CONTINUE: Final[str] = SELECTORS["reviews.pagination.continue_button"]
+
+#: Форма догрузки. Второй узел того же механизма.
+_PAGE_FORM: Final[str] = SELECTORS["reviews.pagination.form"]
+
+#: Обёртка ОДНОГО отзыва, а не списка - имя обманывает.
+#:
+#: Служит третьим счётом строк, не зависящим ни от класса строки, ни от прямых
+#: потомков контейнера. Обёрток ровно столько же, сколько отзывов, и расхождение
+#: означает, что разметка изменилась там, где два других счёта этого не видят.
+_WRAPPER: Final[str] = SELECTORS["reviews.row.wrapper"]
+
+#: Узел оценки. В строке их два - широкий макет и узкий.
+_RATING: Final[str] = SELECTORS["reviews.fields.rating"]
+
+_AUTHOR_NAME: Final[str] = SELECTORS["reviews.fields.author_name"]
+_AUTHOR_HREF: Final[str] = SELECTORS["reviews.fields.author_href"]
+_AUTHOR_PHOTO_HREF: Final[str] = SELECTORS["reviews.fields.author_photo_href"]
+_ORDER_HREF: Final[str] = SELECTORS["reviews.fields.order_href"]
+_TEXT: Final[str] = SELECTORS["reviews.fields.text"]
+_DATE_TEXT: Final[str] = SELECTORS["reviews.fields.date_text"]
+_DETAIL_TEXT: Final[str] = SELECTORS["reviews.fields.detail_text"]
+
+#: Оценка в имени класса: rating5 значит пять звёзд.
+#:
+#: Перечисление закрыто нарочно. Открытое приняло бы rating7 или rating0 за
+#: оценку, а закрытое объявит незнакомое ненаблюдённым - и это правильный ответ:
+#: смена шкалы у площадки должна быть заметна, а не подхвачена молча.
+_RATING_CLASS: Final[re.Pattern[str]] = re.compile(r"^rating([1-5])$")
+
+
+@dataclass(frozen=True, slots=True)
+class Review:
+    """Отзыв, прочитанный с профиля продавца.
+
+    Момента времени в записи нет, и это не упущение. Дата показана
+    локализованной человеческой записью - тридцать один знак с буквами, цифрами
+    и пунктуацией, - и разбирать её значило бы угадывать по одной локали из
+    трёх. Строка, которую нельзя разобрать, честнее момента, угаданного неверно.
+
+    Attributes:
+        row_index (int): Место отзыва на странице, считая с нуля.
+        rating (Observed[int]): Оценка в звёздах, целое от одного до пяти.
+        author_name (Observed[str]): Отображаемое имя автора.
+        author_href (Observed[str]): Адрес профиля автора.
+        order_href (Observed[str]): Адрес заказа, к которому отзыв относится.
+        text (Observed[str]): Текст отзыва.
+        date_text (Observed[str]): Дата в том виде, в каком её показали.
+        detail_text (Observed[str]): Подпись под отзывом: что купили и почём.
+    """
+
+    row_index: int
+    rating: Observed[int]
+    author_name: Observed[str]
+    author_href: Observed[str]
+    order_href: Observed[str]
+    text: Observed[str]
+    date_text: Observed[str]
+    detail_text: Observed[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ReviewsCursor:
+    """Позиция отзывов одного продавца с той же выбранной оценкой."""
+
+    user_id: str
+    value: str = field(repr=False)
+    rating: int | None = None
+
+    def to_token(self) -> str:
+        """Сериализует курсор для сохранения между запусками."""
+        try:
+            scope = normalize_review_rating(self.rating) or None
+        except ValidationError:
+            raise CursorIncompatibleError(
+                "оценка в курсоре должна быть целым 1..5 либо None"
+            ) from None
+        return encode_cursor("reviews.get", self.user_id, self.value, scope=scope)
+
+    @classmethod
+    def from_token(cls, token: str) -> ReviewsCursor:
+        """Восстанавливает курсор, проверяя версию, семейство и операцию."""
+        owner, position, scope = decode_cursor(token, kind="reviews.get")
+        if scope is not None and scope not in {"1", "2", "3", "4", "5"}:
+            raise CursorIncompatibleError("неподдерживаемая оценка в курсоре отзывов")
+        return cls(owner, position, None if scope is None else int(scope))
+
+
+def normalize_review_rating(rating: int | None) -> str:
+    """Проверяет оценку до запроса и возвращает значение поля формы."""
+    if rating is None:
+        return ""
+    if type(rating) is not int or not 1 <= rating <= 5:
+        raise ValidationError("rating должен быть целым от 1 до 5 либо None")
+    return str(rating)
+
+
+@dataclass(frozen=True, slots=True)
+class ReviewsPage:
+    """Результат чтения отзывов.
+
+    Записи отдаются методом, а не полем, по той же причине, что и у списка
+    продаж: открытый список делает неполноту незаметной.
+
+    Attributes:
+        completeness (Completeness): Полнота прочитанного.
+        reason (str): Машиночитаемая причина, по которой полнота такова.
+        observed_at (datetime): Момент наблюдения.
+        rows_total (int): Сколько кандидатов в отзывы нашлось, штук.
+        rows_accepted (int): Сколько отзывов собрано, штук.
+        rows_rejected (int): Сколько кандидатов отброшено, штук.
+        defects (tuple[Defect, ...]): Замеченные повреждения.
+    """
+
+    completeness: Completeness
+    reason: str
+    observed_at: datetime
+    rows_total: int
+    rows_accepted: int
+    rows_rejected: int
+    defects: tuple[Defect, ...] = ()
+    next_cursor: ReviewsCursor | None = None
+    _entries: tuple[Review, ...] = field(repr=False, default=())
+
+    def rows(self, *, accept_incomplete: bool = False) -> tuple[Review, ...]:
+        """Возвращает собранные отзывы.
+
+        Args:
+            accept_incomplete (bool): Признание того, что результат может быть
+                неполным. Без него неполный результат не выдаётся.
+
+        Returns:
+            tuple[Review, ...]: Отзывы в порядке появления на странице.
+
+        Raises:
+            IncompleteResultError: Если полнота отлична от COMPLETE, а неполнота
+                не признана.
+        """
+        if self.completeness is not Completeness.COMPLETE and not accept_incomplete:
+            raise IncompleteResultError(
+                f"результат неполон ({self.completeness}, причина: {self.reason}), "
+                f"собрано {self.rows_accepted} из {self.rows_total}, "
+                f"повреждений {len(self.defects)}. Передайте accept_incomplete=True, "
+                "если готовы работать с неполными данными"
+            )
+        return self._entries
+
+    def __len__(self) -> int:
+        """Возвращает число собранных отзывов.
+
+        Returns:
+            int: Число собранных отзывов.
+        """
+        return len(self._entries)
+
+
+def _text_of(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 _rating(row: Node, index: int) -> tuple[Observed[int], list[Defect]]:
+    """Читает оценку из имени класса и сверяет два узла между собой.
+
+    Узлов оценки в строке два: один для широкого макета, другой для узкого.
+    Значение в них одно и то же, и расхождение означает не выбор, а изменение
+    разметки - объявлять оценку по первому попавшемуся значило бы отдать
+    покупателю чужую звезду молча.
+
+    Args:
+        row (Node): Строка отзыва.
+        index (int): Место строки на странице, для сообщения о повреждении.
+
+    Returns:
+        tuple[Observed[int], list[Defect]]: Оценка и перечень повреждений.
+    """
+    nodes = row.css(_RATING)
+    if not nodes:
+        return Observed.missing("selector_no_match:rating"), []
+
+    seen: set[int] = set()
+    unknown: list[str] = []
+    for node in nodes:
+        for name in (node.attributes.get("class") or "").split():
+            match = _RATING_CLASS.match(name)
+            if match is not None:
+                seen.add(int(match.group(1)))
+            else:
+                unknown.append(name)
+
+    if not seen:
+        # Узел есть, а оценки в его классах нет. Это не «оценки не показали»:
+        # это класс, которого перечисление не знает, и подхватить его молча
+        # значило бы принять чужую шкалу за свою.
+        return (
+            Observed.missing("rating_class_not_recognised"),
+            [
+                Defect(
+                    severity=Severity.ROW,
+                    code="rating_class_not_recognised",
+                    detail=(
+                        f"строка {index}: у узлов оценки классы {sorted(set(unknown))}, "
+                        "ни один не входит в наблюдённое перечисление rating1..rating5"
+                    ),
+                    field_name="rating",
+                )
+            ],
+        )
+
+    if len(seen) > 1:
+        return (
+            Observed.missing("rating_carriers_disagree"),
+            [
+                Defect(
+                    severity=Severity.ROW,
+                    code="rating_carriers_disagree",
+                    detail=(
+                        f"строка {index}: узлы оценки разошлись, прочитано {sorted(seen)}. "
+                        "Взять любую из них значило бы выбрать наугад"
+                    ),
+                    field_name="rating",
+                )
+            ],
+        )
+
+    return Observed.present(seen.pop()), []
+
+
+def _author_href(row: Node, index: int) -> tuple[Observed[str], list[Defect]]:
+    """Читает адрес профиля автора и сверяет два его носителя.
+
+    Адресов в строке два: на имени и на аватаре. Ведут они в одно место, и
+    расхождение означает изменение разметки. Проверка заведена по той же
+    причине, по которой сверяются два узла оценки.
+
+    Args:
+        row (Node): Строка отзыва.
+        index (int): Место строки на странице, для сообщения о повреждении.
+
+    Returns:
+        tuple[Observed[str], list[Defect]]: Адрес и перечень повреждений.
+    """
+    from_name = attribute(row.css_first(_AUTHOR_HREF), "href", "author_href")
+    from_photo = attribute(row.css_first(_AUTHOR_PHOTO_HREF), "href", "author_photo_href")
+
+    if not from_name.is_observed or not from_photo.is_observed:
+        return from_name, []
+
+    if from_name.value != from_photo.value:
+        return (
+            Observed.missing("author_href_mismatch"),
+            [
+                Defect(
+                    severity=Severity.ROW,
+                    code="author_href_mismatch",
+                    detail=(
+                        f"строка {index}: адрес на имени {from_name.value!r} и адрес "
+                        f"на аватаре {from_photo.value!r} ведут в разные места"
+                    ),
+                    field_name="author_href",
+                )
+            ],
+        )
+
+    return from_name, []
+
+
+def _parse_row(row: Node, index: int) -> tuple[Review, list[Defect]]:
+    """Собирает один отзыв.
+
+    Отказа здесь нет ни одного: у отзыва нет поля, без которого запись
+    бессмысленна. У записи продажи такое поле есть - идентификатор заказа, - и
+    строка без него отбрасывается. Отзыв без адреса заказа остаётся отзывом:
+    оценка и текст читаются и без него.
+
+    Args:
+        row (Node): Строка отзыва.
+        index (int): Место строки на странице, считая с нуля.
+
+    Returns:
+        tuple[Review, list[Defect]]: Отзыв и перечень повреждений строки.
+    """
+    rating, defects = _rating(row, index)
+    author_href, href_defects = _author_href(row, index)
+    defects.extend(href_defects)
+
+    return (
+        Review(
+            row_index=index,
+            rating=rating,
+            author_name=_text_of(row.css_first(_AUTHOR_NAME), "author_name"),
+            author_href=author_href,
+            order_href=attribute(row.css_first(_ORDER_HREF), "href", "order_href"),
+            text=_text_of(row.css_first(_TEXT), "text"),
+            date_text=_text_of(row.css_first(_DATE_TEXT), "date_text"),
+            detail_text=_text_of(row.css_first(_DETAIL_TEXT), "detail_text"),
+        ),
+        defects,
+    )
+
+
+def _totality(tree: HTMLParser) -> tuple[Completeness, str]:
+    """Определяет конец выборки по наблюдённой кнопке догрузки.
+
+    Видимая кнопка сопровождает страницы с продолжением; скрытая вместе с
+    пустой позицией - конечную страницу. Отсутствие кнопки не доказывает конец.
+    Форму, курсор и повреждения строк вызывающий проверяет отдельно.
+    """
+    button = tree.css_first(_CONTINUE)
+    if button is None:
+        # Кнопки нет вовсе. Это не «догружать нечего»: страницы без неё никто не
+        # видел, и объявлять по её отсутствию полноту значило бы вывести знание
+        # из ненаходки - ровно та ошибка, из-за которой этот раздел и переписан.
+        return Completeness.PARTIAL, "pagination_control_missing"
+
+    if "hidden" not in (button.attributes.get("class") or "").split():
+        # Кнопка показана: догружать есть что.
+        return Completeness.PARTIAL, "more_rows_available"
+
+    return Completeness.COMPLETE, "all_rows_parsed"
+
+
+def _next_cursor(
+    tree: HTMLParser, defects: list[Defect], user_id: str | None, rating: int | None
+) -> ReviewsCursor | None:
+    forms = tree.css(_PAGE_FORM)
+    buttons = tree.css(_CONTINUE)
+    if len(forms) > 1 or len(buttons) > 1:
+        defects.append(
+            Defect(Severity.PAGE, "pagination_controls_ambiguous", "несколько форм или кнопок")
+        )
+        return None
+    if not forms or not buttons:
+        return None  # Полнота отдельно учитывает отсутствие управляющих узлов.
+    visible = "hidden" not in (buttons[0].attributes.get("class") or "").split()
+    values = {}
+    for name, selector in (
+        ("user_id", SELECTORS["reviews.pagination.fields.user_id"]),
+        ("continue", SELECTORS["reviews.pagination.fields.continue"]),
+        ("filter", SELECTORS["reviews.pagination.fields.filter"]),
+    ):
+        nodes = tree.css(selector)
+        if len(nodes) > 1:
+            defects.append(Defect(Severity.PAGE, "pagination_fields_ambiguous", name))
+            return None
+        if nodes:
+            values[name] = nodes[0].attributes.get("value") or ""
+    owner = values.get("user_id")
+    if owner and user_id is not None and owner != user_id:
+        raise ProtocolChangedError("форма отзывов принадлежит другому продавцу")
+    if values.get("filter") and values["filter"] != normalize_review_rating(rating):
+        defects.append(
+            Defect(Severity.PAGE, "pagination_filter_mismatch", "форма содержит другую оценку")
+        )
+        return None
+    token = values.get("continue", "")
+    if not visible:
+        if token:
+            defects.append(
+                Defect(Severity.PAGE, "pagination_controls_conflict", "скрытая кнопка с курсором")
+            )
+        return None
+    if not owner or not token:
+        defects.append(
+            Defect(
+                Severity.PAGE, "pagination_cursor_missing", "форма не содержит пригодного курсора"
+            )
+        )
+        return None
+    return ReviewsCursor(owner, token, rating)
+
+
+def parse_reviews_page(
+    html: str, observed_at: datetime, *, user_id: str | None = None, rating: int | None = None
+) -> ReviewsPage:
+    """Разбирает страницу профиля и собирает отзывы.
+
+    Args:
+        html (str): Тело страницы. Предполагается уже классифицированным как
+            пригодное: состояние сессии здесь не проверяется.
+        observed_at (datetime): Момент наблюдения. Передаётся снаружи, чтобы
+            разбор оставался чистым и повторяемым на сохранённом снимке.
+
+    Returns:
+        ReviewsPage: Отзывы вместе с полнотой и перечнем повреждений.
+
+    Raises:
+        ProtocolChangedError: Если разметка изменилась настолько, что читать
+            нечего: нет таблицы либо нет контейнера строк.
+    """
+    normalize_review_rating(rating)
+    tree = HTMLParser(html)
+    defects: list[Defect] = []
+
+    empty = tree.css(SELECTORS["reviews.empty_filtered"])
+    if empty:
+        if (
+            rating is None
+            or len(empty) != 1
+            or not empty[0].text(strip=True)
+            or len(tree.css(SELECTORS["reviews.filter"])) != 1
+            or any(
+                tree.css_first(selector) is not None
+                for selector in (_TABLE, _ROWS_CONTAINER, _ROW, _WRAPPER, _PAGE_FORM, _CONTINUE)
+            )
+        ):
+            raise ProtocolChangedError("неоднозначный признак пустой выборки отзывов")
+        return ReviewsPage(
+            completeness=Completeness.COMPLETE,
+            reason="empty_filtered_list",
+            observed_at=observed_at,
+            rows_total=0,
+            rows_accepted=0,
+            rows_rejected=0,
+            defects=(),
+            _entries=(),
+        )
+
+    if tree.css_first(_TABLE) is None:
+        raise ProtocolChangedError(
+            f"на странице профиля нет контейнера таблицы отзывов ({_TABLE}). "
+            "Пустой список вернуть нельзя: профиля без отзывов проект не видел, "
+            "и отличить его от смены разметки нечем"
+        )
+
+    if tree.css_first(_ROWS_CONTAINER) is None:
+        raise ProtocolChangedError(
+            f"на странице профиля нет контейнера строк ({_ROWS_CONTAINER}). "
+            "Без него нельзя проверить, что строки найдены все"
+        )
+
+    if tree.css_first(_PAGE_FORM) is None:
+        defects.append(
+            Defect(
+                severity=Severity.PAGE,
+                code="pagination_form_missing",
+                detail=(
+                    f"формы догрузки ({_PAGE_FORM}) на странице нет. Она стоит за "
+                    "таблицей отзывов на всех наблюдённых снимках; её исчезновение "
+                    "означает, что механизм догрузки изменился"
+                ),
+            )
+        )
+
+    found = collect_rows(tree, _ROWS_CONTAINER, _ROW)
+    defects.extend(found.defects)
+
+    # Третий счёт. Обёрток столько же, сколько отзывов, и разойдись они - это
+    # повреждение уровня страницы, а не повод молча вернуть меньше строк.
+    wrappers = len(tree.css(_WRAPPER))
+    if wrappers != len(found.rows):
+        defects.append(
+            Defect(
+                severity=Severity.PAGE,
+                code="wrapper_count_mismatch",
+                detail=(
+                    f"обёрток отзыва {wrappers}, а строк найдено {len(found.rows)}. "
+                    "Один из двух счётчиков видит не то, что другой"
+                ),
+            )
+        )
+
+    entries: list[Review] = []
+    for index, row in enumerate(found.rows):
+        entry, row_defects = _parse_row(row, index)
+        defects.extend(row_defects)
+        entries.append(entry)
+
+    rating_mismatch = rating is not None and any(
+        entry.rating.is_observed and entry.rating.value != rating for entry in entries
+    )
+    if rating_mismatch:
+        defects.append(
+            Defect(Severity.PAGE, "review_filter_mismatch", "строки содержат другую оценку")
+        )
+
+    rows_total = max(len(found.rows), found.children, len(tree.css(_ROW)))
+    rows_accepted = len(entries)
+    rows_rejected = len(found.rows) - rows_accepted
+
+    if rows_total and not rows_accepted:
+        raise ProtocolChangedError(
+            f"кандидатов в отзывы {rows_total}, собрать не удалось ни одного. "
+            "Это изменение разметки, а не пустой список"
+        )
+
+    # Без положительного признака пустой выборки ноль строк не доказывает
+    # пустоту: класс строки мог измениться, даже если таблица ещё узнаваема.
+    next_cursor = _next_cursor(tree, defects, user_id, rating)
+    if rating_mismatch:
+        next_cursor = None
+    if not rows_total:
+        completeness, reason = Completeness.UNKNOWN, "empty_list_not_observed"
+    elif any(one.severity is Severity.PAGE for one in defects):
+        completeness, reason = Completeness.PARTIAL, "page_defects"
+    elif defects:
+        completeness, reason = Completeness.PARTIAL, "row_defects"
+    else:
+        completeness, reason = _totality(tree)
+
+    return ReviewsPage(
+        completeness=completeness,
+        next_cursor=next_cursor,
+        reason=reason,
+        observed_at=observed_at,
+        rows_total=rows_total,
+        rows_accepted=rows_accepted,
+        rows_rejected=rows_rejected,
+        defects=tuple(defects),
+        _entries=tuple(entries),
+    )