funora 0.0.1.dev2__py3-none-any.whl

funora/_whoami.py

@@ -0,0 +1,546 @@
+"""Чтение аккаунта, проверка сессии и профиль возможностей.
+
+Три операции об одном: от чьего имени работает клиент и годна ли его сессия.
+
+Имя модуля - _whoami, а не _identity: последнее занято сетевой идентичностью,
+то есть парой «исходящий адрес и целевой хост». Разные вещи с похожими именами
+стоят рядом, и путать их дорого: одно про то, кем нас видит площадка, другое про
+то, откуда мы к ней приходим.
+
+ЧИТАЕТСЯ СТРАНИЦА С ВИДЖЕТОМ ПЕРЕПИСКИ, и это не безразличная подробность.
+Собственный идентификатор лежит в атрибуте data-user, а атрибут этот есть только
+там, где виджет есть: на списке продаж и на странице баланса его нет вовсе. С
+любой авторизованной страницы прочесть себя нельзя.
+
+ИМЯ И ИДЕНТИФИКАТОР ЧИТАЮТСЯ ПО-РАЗНОМУ. Идентификатор - из атрибута, имя - из
+текста в шапке, и узлов имени ДВА: настольное меню и мобильное. Значение в них
+одно и то же, и разбор обязан их сверить: разошлись - разметка изменилась.
+
+ПРОФИЛЬ ВОЗМОЖНОСТЕЙ СОБИРАЕТСЯ БЕЗ СЕТИ. Он отвечает на «что этот клиент умеет
+прямо сейчас», а это уже известно из того, что наблюдалось. Неуспешная проба
+даёт unknown, а не unsupported: отсутствие объявляется только по положительному
+свидетельству, и неудача таковым не является.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from threading import RLock
+from typing import Final, Literal
+
+from selectolax.parser import HTMLParser, Node
+
+from ._classify import ResponseClass, Verdict
+from ._observed import Observed
+from ._result import Defect, Severity
+from ._secret import Secret
+from .capabilities import CAPABILITY_INITIAL, Capability, CapabilityState
+from .errors import ProtocolChangedError
+from .extraction import SELECTORS
+
+__all__ = [
+    "Account",
+    "AppData",
+    "CapabilityProfile",
+    "CapabilityEvaluation",
+    "SessionHealth",
+    "parse_account",
+    "parse_app_data",
+]
+
+_OWN_ID: Final[str] = SELECTORS["session.identity.own_user_id"]
+_OWN_NAME: Final[str] = SELECTORS["session.identity.own_username"]
+_APP_DATA: Final[str] = SELECTORS["session.identity.app_data"]
+
+#: Имя ключа защитного токена внутри объекта настроек страницы.
+_CSRF_KEY: Final[str] = "csrf-token"
+
+
+@dataclass(frozen=True, slots=True)
+class Account:
+    """Аккаунт, от имени которого работает клиент.
+
+    Балансов здесь нет намеренно: они лежат на другой странице, и читать её ради
+    профиля значило бы ходить на площадку дважды за одним ответом. Отсутствие
+    поля означает «не наблюдали», а не «нулю равно».
+
+    Attributes:
+        user_id (Observed[str]): Собственный идентификатор из атрибута.
+        username (Observed[str]): Собственное отображаемое имя.
+        locale (Observed[str]): Метка языка страницы.
+        observed_at (datetime): Момент наблюдения.
+        defects (tuple[Defect, ...]): Замеченные повреждения.
+    """
+
+    user_id: Observed[str]
+    username: Observed[str]
+    locale: Observed[str]
+    observed_at: datetime
+    defects: tuple[Defect, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class SessionHealth:
+    """Пригодность сессии.
+
+    Attributes:
+        response_class (ResponseClass): Класс ответа площадки.
+        is_usable (bool): Годится ли сессия для работы прямо сейчас.
+        reason (str): Машиночитаемая причина решения классификатора.
+        provisional (bool): Принято ли решение непроверенной сигнатурой.
+        checked_at (datetime): Момент проверки.
+        from_cache (bool): Отдан ли ответ из кэша, а не получен запросом.
+        unsafe_marks (frozenset[str]): Какие защиты вызывающий снял с себя сам.
+
+            Поле заведено потому, что отметки ставились и не читались. Понижение
+            нижнего предела опроса помечалось внутри расписания с самого его
+            появления, и не смотрел на эту пометку никто: защита снималась, след
+            оставался, и вёл он в никуда.
+
+            Перечень имён закрыт контрактом. Снять защиту молча нельзя: новое
+            послабление обязано сперва получить имя в спецификации.
+    """
+
+    response_class: ResponseClass
+    is_usable: bool
+    reason: str
+    provisional: bool
+    checked_at: datetime
+    from_cache: bool
+    unsafe_marks: frozenset[str] = frozenset()
+
+    @classmethod
+    def of(
+        cls,
+        verdict: Verdict,
+        checked_at: datetime,
+        *,
+        from_cache: bool,
+        unsafe_marks: frozenset[str] = frozenset(),
+    ) -> SessionHealth:
+        """Собирает ответ из вердикта классификатора.
+
+        Годной сессия считается РОВНО при классе ok. Прочие классы означают
+        разное, но ни один из них не означает «можно работать»: правило «всё,
+        кроме явного отказа, годится» однажды приняло бы страницу проверки за
+        рабочую.
+
+        Args:
+            verdict (Verdict): Вердикт классификатора.
+            checked_at (datetime): Момент проверки.
+            from_cache (bool): Отдан ли ответ из кэша.
+            unsafe_marks (frozenset[str]): Снятые вызывающим защиты.
+
+        Returns:
+            SessionHealth: Пригодность сессии.
+        """
+        return cls(
+            response_class=verdict.cls,
+            is_usable=verdict.cls is ResponseClass.OK,
+            reason=verdict.reason,
+            provisional=verdict.provisional,
+            checked_at=checked_at,
+            from_cache=from_cache,
+            unsafe_marks=unsafe_marks,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityEvaluation:
+    """Основание состояния одной возможности.
+
+    evaluated_at - время оценки, которое чтение профиля не обновляет.
+    source описывает свидетельство: таблица адаптера, результат операции или
+    сброс после отказа. Это не source из реестра способов определения функций.
+    """
+
+    state: CapabilityState
+    evaluated_at: datetime
+    source: Literal["static", "probe", "observed_failure"]
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityProfile:
+    """Снимок возможностей без сети.
+
+    observed_at - время сборки снимка. Время и основание каждой оценки
+    доступны отдельно через evaluation_of; получение снимка их не освежает.
+    """
+
+    observed_at: datetime
+    _evaluations: dict[Capability, CapabilityEvaluation] = field(repr=False, default_factory=dict)
+
+    def states(self) -> dict[Capability, CapabilityState]:
+        """Возвращает независимую копию состояний всех возможностей."""
+        return {key: value.state for key, value in self._evaluations.items()}
+
+    def state_of(self, capability: Capability) -> CapabilityState:
+        """Возвращает состояние; отсутствующий ключ означает дефект профиля."""
+        return self._evaluations[capability].state
+
+    def evaluations(self) -> dict[Capability, CapabilityEvaluation]:
+        """Возвращает копию оценок с их основаниями и временем."""
+        return dict(self._evaluations)
+
+    def evaluation_of(self, capability: Capability) -> CapabilityEvaluation:
+        """Возвращает неизменяемую оценку одной возможности."""
+        return self._evaluations[capability]
+
+
+class _CapabilityStates:
+    """Хранит состояние и его основание одной неделимой записью.
+
+    Обновление из существующих операций остаётся индексным присваиванием.
+    Снимок и сброс защищены той же блокировкой, чтобы параллельное чтение
+    профиля не соединяло состояние до сброса с его новым основанием.
+    """
+
+    def __init__(self) -> None:
+        self._lock = RLock()
+        self._evaluations: dict[Capability, CapabilityEvaluation] = {}
+        self.reset()
+
+    def __getitem__(self, capability: Capability) -> CapabilityState:
+        with self._lock:
+            return self._evaluations[capability].state
+
+    def __setitem__(self, capability: Capability, state: CapabilityState) -> None:
+        with self._lock:
+            self._evaluations[capability] = CapabilityEvaluation(state, datetime.now(UTC), "probe")
+
+    def snapshot(self) -> CapabilityProfile:
+        with self._lock:
+            return CapabilityProfile(datetime.now(UTC), dict(self._evaluations))
+
+    def reset(self) -> None:
+        with self._lock:
+            now = datetime.now(UTC)
+            self._evaluations = {
+                cap: CapabilityEvaluation(state, now, "static")
+                for cap, state in CAPABILITY_INITIAL.items()
+            }
+
+    def invalidate(self) -> None:
+        with self._lock:
+            now = datetime.now(UTC)
+            self._evaluations = {
+                cap: CapabilityEvaluation(
+                    # Отказ не снимает запрет или требование согласия из контракта.
+                    initial if not initial.usable else CapabilityState.UNKNOWN,
+                    now,
+                    "observed_failure",
+                )
+                for cap, initial in CAPABILITY_INITIAL.items()
+            }
+
+
+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 _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"selector_no_match:{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 _username(tree: HTMLParser) -> tuple[Observed[str], list[Defect]]:
+    """Читает собственное имя и сверяет два его носителя.
+
+    Узлов имени два - настольное меню и мобильное, - и значение в них одно и то
+    же. Взять первый попавшийся значило бы повторить ошибку, на которой уже
+    спотыкались разбор списка продаж и разбор отзывов.
+
+    Args:
+        tree (HTMLParser): Разобранная страница.
+
+    Returns:
+        tuple[Observed[str], list[Defect]]: Имя и перечень повреждений.
+    """
+    nodes = tree.css(_OWN_NAME)
+    if not nodes:
+        return Observed.missing(f"selector_no_match:{_OWN_NAME}"), []
+
+    values = {" ".join((one.text() or "").split()) for one in nodes}
+    if len(values) > 1:
+        return (
+            Observed.missing("username_carriers_disagree"),
+            [
+                Defect(
+                    severity=Severity.PAGE,
+                    code="username_carriers_disagree",
+                    detail=(
+                        f"узлы имени разошлись, прочитано {sorted(values)}. "
+                        "Взять любое значило бы выбрать наугад"
+                    ),
+                    field_name="username",
+                )
+            ],
+        )
+
+    value = values.pop()
+    return (Observed.present(value) if value else Observed.empty("")), []
+
+
+def parse_account(html: str, observed_at: datetime) -> Account:
+    """Разбирает страницу и собирает сведения о собственном аккаунте.
+
+    Args:
+        html (str): Тело страницы. Предполагается уже классифицированным как
+            пригодное: состояние сессии здесь не проверяется.
+        observed_at (datetime): Момент наблюдения. Передаётся снаружи, чтобы
+            разбор оставался чистым и повторяемым на сохранённом снимке.
+
+    Returns:
+        Account: Собственный идентификатор, имя и метка языка.
+
+    Raises:
+        ProtocolChangedError: Если на странице нет ни одного признака собственной
+            личности. Пустой ответ вернуть нельзя: он неотличим от страницы,
+            отданной не нам.
+    """
+    tree = HTMLParser(html)
+
+    carrier = tree.css_first(_OWN_ID)
+    if carrier is None and not tree.css(_OWN_NAME):
+        raise ProtocolChangedError(
+            f"на странице нет ни носителя собственного идентификатора ({_OWN_ID}), "
+            f"ни собственного имени ({_OWN_NAME}). Пустой ответ вернуть нельзя: "
+            "он неотличим от страницы, отданной не нам"
+        )
+
+    username, defects = _username(tree)
+
+    if carrier is None:
+        # Атрибут есть не на всякой странице: там, где виджета переписки нет,
+        # нет и его. Это не поломка - это выбор страницы, и он записан
+        # повреждением, чтобы вызывающий не принял пробел за отсутствие
+        # идентификатора у аккаунта.
+        defects.append(
+            Defect(
+                severity=Severity.PAGE,
+                code="own_id_carrier_missing",
+                detail=(
+                    f"на странице нет носителя собственного идентификатора ({_OWN_ID}). "
+                    "Он есть только там, где есть виджет переписки"
+                ),
+                field_name="user_id",
+            )
+        )
+
+    root = tree.css_first("html")
+    return Account(
+        user_id=_attribute(carrier, "data-user", "user_id"),
+        username=username,
+        locale=_attribute(root, "lang", "locale"),
+        observed_at=observed_at,
+        defects=tuple(defects),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class AppData:
+    """Настройки страницы из атрибута data-app-data.
+
+    ЗДЕСЬ ЛЕЖИТ ЗАЩИТНЫЙ ТОКЕН, без которого не собрать ни одного запроса
+    записи. Отдаётся он обёрнутым в Secret: значение видно только по явному
+    вызову reveal, и ни в repr, ни в журнал, ни в сообщение об ошибке не
+    попадает. Строкой его не отдают нарочно - подстановка в f-строку случайна,
+    вызов reveal виден при чтении кода.
+
+    Идентификатор и метка языка лежат в том же объекте ВТОРЫМИ носителями: их
+    же несут атрибут data-user и html[lang]. Сверка носителей - дело
+    вызывающего разбора, здесь читается ровно то, что написано.
+
+    Attributes:
+        csrf_token (Secret | None): Защитный токен. None, если не прочитан.
+        user_id (Observed[str]): Собственный идентификатор из объекта.
+        locale (Observed[str]): Метка языка из объекта.
+        upload_size_max (Observed[int]): Наибольший размер выгружаемого файла в
+            байтах, КАК ЕГО ОБЪЯВИЛА ПЛОЩАДКА.
+
+            Читается, а не выдумывается, и в этом весь смысл поля. Свой предел
+            отверг бы то, что площадка приняла бы, - и отверг бы молча, на
+            стороне вызывающего, которому нечего было бы возразить.
+        defects (tuple[Defect, ...]): Замеченные повреждения.
+    """
+
+    csrf_token: Secret | None
+    user_id: Observed[str]
+    locale: Observed[str]
+    upload_size_max: Observed[int] = field(default_factory=lambda: Observed.missing("not_read"))
+    defects: tuple[Defect, ...] = ()
+
+
+def _json_field(data: dict[str, object], key: str, field_name: str) -> Observed[str]:
+    """Читает строковое поле объекта настроек как наблюдение.
+
+    Args:
+        data (dict[str, object]): Разобранный объект настроек.
+        key (str): Имя ключа в объекте.
+        field_name (str): Имя поля для причины отсутствия.
+
+    Returns:
+        Observed[str]: Наблюдение.
+    """
+    if key not in data:
+        return Observed.missing(f"key_absent:{field_name}")
+    value = data[key]
+    if not isinstance(value, str):
+        # Число здесь читалось бы как строка молча, и разница вышла бы наружу
+        # только при сравнении с другим носителем.
+        return Observed.missing(f"key_not_a_string:{field_name}")
+    value = value.strip()
+    return Observed.present(value) if value else Observed.empty("")
+
+
+def _upload_limit(parsed: dict[str, object]) -> Observed[int]:
+    """Читает объявленный площадкой предел размера файла.
+
+    ПОЛЕ НАШЛОСЬ 31.08.2026, и до того перечень ключей этого объекта числился
+    полным из пяти. Ключей шесть, и шестой - именно этот.
+
+    Аргументы:
+        parsed (dict[str, object]): Разобранный объект настроек.
+
+    Возвращает:
+        Observed[int]: Предел в байтах либо причина отсутствия.
+    """
+    options = parsed.get("uploadOptions")
+    if not isinstance(options, dict):
+        return Observed.missing("upload_options_absent")
+
+    raw = options.get("fileSizeMax")
+    # Строкой оно приходит на настоящей странице, числом - могло бы; принимаются
+    # оба, а логическое исключается отдельно: истина в Python это единица.
+    if isinstance(raw, bool):
+        return Observed.missing("upload_size_max_not_a_number")
+    if isinstance(raw, int):
+        value = raw
+    elif isinstance(raw, str) and raw.strip().isdigit():
+        value = int(raw.strip())
+    else:
+        return Observed.missing("upload_size_max_not_a_number")
+
+    # Ноль и отрицательное отвергаются: предел, запрещающий любой файл, скорее
+    # означает, что мы прочитали не то поле, чем что площадка запретила выгрузку.
+    if value <= 0:
+        return Observed.missing("upload_size_max_not_positive")
+    return Observed.present(value)
+
+
+def parse_app_data(html: str) -> AppData:
+    """Разбирает объект настроек страницы и достаёт защитный токен.
+
+    НЕ ПАДАЕТ НИ НА ЧЁМ. Атрибута может не быть, он может не разобраться, в нём
+    может не быть нужного ключа - и всё это разные обстоятельства с разными
+    причинами. Отказ здесь превратил бы «токена нет» в «страница сломана», а это
+    решается по-разному: первое ведёт к перезаходу, второе к разбирательству с
+    разметкой.
+
+    Отдельно стоит случай СТАРОГО СНИМКА. До формата скелета v8 атрибут
+    маскировался целиком, одной подписью, и разобрать его как JSON нельзя. Это
+    не поломка площадки, а возраст снимка, и причина названа отдельно.
+
+    Args:
+        html (str): Тело страницы.
+
+    Returns:
+        AppData: Токен, идентификатор и метка языка из объекта настроек.
+    """
+    tree = HTMLParser(html)
+    carrier = tree.css_first(_APP_DATA)
+    if carrier is None:
+        return AppData(
+            csrf_token=None,
+            user_id=Observed.missing("app_data_carrier_missing"),
+            locale=Observed.missing("app_data_carrier_missing"),
+            defects=(
+                Defect(
+                    severity=Severity.PAGE,
+                    code="app_data_carrier_missing",
+                    detail=f"на странице нет носителя настроек ({_APP_DATA})",
+                    field_name="csrf_token",
+                ),
+            ),
+        )
+
+    raw = (carrier.attributes or {}).get("data-app-data") or ""
+    try:
+        parsed: object = json.loads(raw)
+    except ValueError:
+        parsed = None
+
+    if not isinstance(parsed, dict):
+        masked = raw.startswith("T") and ":" in raw
+        code = "app_data_masked_by_skeleton" if masked else "app_data_not_json"
+        detail = (
+            "атрибут настроек замаскирован скелетом целиком: снимок сделан "
+            "форматом старше v8, и ключей объекта в нём нет"
+            if masked
+            else "атрибут настроек не разбирается как объект JSON"
+        )
+        return AppData(
+            csrf_token=None,
+            user_id=Observed.missing(code),
+            locale=Observed.missing(code),
+            defects=(
+                Defect(severity=Severity.PAGE, code=code, detail=detail, field_name="csrf_token"),
+            ),
+        )
+
+    defects: list[Defect] = []
+    token: Secret | None = None
+    value = parsed.get(_CSRF_KEY)
+    if not isinstance(value, str) or not value.strip():
+        # Значения токена в сообщении нет и быть не может: оно часть сессии
+        # владельца. Названо только то, чего не хватило.
+        defects.append(
+            Defect(
+                severity=Severity.PAGE,
+                code="csrf_token_absent",
+                detail=(
+                    f"в объекте настроек нет пригодного ключа {_CSRF_KEY}. "
+                    f"Прочитанные ключи: {sorted(parsed)}"
+                ),
+                field_name="csrf_token",
+            )
+        )
+    else:
+        token = Secret(value.strip(), label=_CSRF_KEY)
+
+    return AppData(
+        csrf_token=token,
+        user_id=_json_field(parsed, "userId", "user_id"),
+        locale=_json_field(parsed, "locale", "locale"),
+        upload_size_max=_upload_limit(parsed),
+        defects=tuple(defects),
+    )

funora/bot/__init__.py

@@ -0,0 +1,52 @@
+"""Слой бота: наблюдение, реакция и отправка из чужого потока.
+
+Подпакет, а не отдельный дистрибутив: он держится на внутренностях ядра, а
+внутренности между дистрибутивами не тянут.
+
+ЧТО ЗДЕСЬ ЕСТЬ И ЧЕГО НЕТ. Есть одно: единственный порядок, при котором
+посторонний поток - скажем, обработчик телеграм-бота - может попросить об
+отправке, не портя счёт ограничителя исходящих. Задание кладётся в очередь,
+разбирает её тот же поток, что ведёт наблюдение.
+
+АВТОВЫДАЧА ЗДЕСЬ ЕСТЬ, и устроена она вокруг одной черты: выдача идёт сама
+только там, где все условия выполнены ПОЛОЖИТЕЛЬНО. Любое незнание - не повод
+действовать осторожнее, а повод не действовать: вопрос уходит человеку.
+
+Идентификатора предложения в заказе нет, и опознаётся лот по описанию - тому
+самому свободному тексту, часть которого дописывает покупатель. Поэтому
+уверенность у опознания всегда выведенная, а двусмысленность - отказ, а не
+выбор наугад.
+
+Управления лотами и рассылки нет. Операций записи над лотами никто не
+наблюдал, а пределы отправки объявлены и соблюдаются. Подробности - в
+docs/guide/bot.md.
+"""
+
+from __future__ import annotations
+
+from .._delivered import Delivery, DeliveryLedger
+from ._delivery import HOLD_FOR_OPERATOR, AutoDelivery, DeliveryDecision, DeliveryPlan
+from ._outbox import MAX_PENDING, Outbox, SendCommand, SendTicket
+from ._runtime import MAX_SENDS_PER_IDLE, Bot
+from ._spool import MAX_SPOOLED, Spool, SpoolEntry, SpoolOutcome
+
+__all__ = [
+    "Bot",
+    "Outbox",
+    "SendCommand",
+    "SendTicket",
+    "MAX_PENDING",
+    "MAX_SENDS_PER_IDLE",
+    # очередь между процессами
+    "Spool",
+    "SpoolEntry",
+    "SpoolOutcome",
+    "MAX_SPOOLED",
+    # автовыдача
+    "AutoDelivery",
+    "DeliveryPlan",
+    "DeliveryDecision",
+    "DeliveryLedger",
+    "Delivery",
+    "HOLD_FOR_OPERATOR",
+]