funora 0.0.1.dev2__py3-none-any.whl

funora/_extract.py

@@ -0,0 +1,124 @@
+"""Чтение атрибута как наблюдаемого значения.
+
+Файл появился по той же причине, что и `_host.py`: правило нашлось написанным в
+трёх местах. Две копии были одинаковы дословно, третью я дописал сам - и она
+разошлась с ними в первый же час, потому что различала на одно состояние больше.
+
+Различает она вот что. Атрибута нет вовсе и атрибут есть, но пуст - разные вещи.
+Первое означает «площадка не дала», второе - «площадка дала пустое», и обе
+прежние копии сводили их в пустое значение. Для адреса разница видна глазом:
+`<a href="">` перезагружает текущую страницу, а `<a>` без адреса ссылкой не
+является вовсе.
+
+Правило одно на весь пакет и живёт здесь.
+"""
+
+from __future__ import annotations
+
+import re
+
+from selectolax.parser import HTMLParser, Node
+
+from ._observed import Observed, Presence
+from .extraction import ATTRIBUTES, SELECTORS
+
+__all__ = ["attribute", "text"]
+
+
+def text(node: Node | None, field_name: str) -> Observed[str]:
+    """Читает подпись, различая отсутствие узла и пустой текст."""
+    if node is None:
+        return Observed.missing(f"selector_no_match:{field_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]:
+    """Извлекает значение атрибута как наблюдаемое значение.
+
+    Различаются три исхода, и все три вызывающему нужны. Селектор не нашёл узла:
+    искать атрибут не у чего. Узел есть, атрибута нет: площадка его не дала.
+    Атрибут есть и пуст: площадка дала пустое - факт о странице, а не о нашем
+    незнании.
+
+    Тип Observed обещает, что PRESENT - это непустое значение, и собирать его в
+    состоянии, которое он сам себе запрещает, значит отбирать у вызывающего
+    единственный способ отличить «адрес есть» от «атрибут пуст».
+
+    Args:
+        node (Node | None): Узел либо None, если селектор не нашёл ничего.
+        name (str): Имя атрибута.
+        field_name (str): Имя поля, попадающее в причину отсутствия.
+
+    Returns:
+        Observed[str]: Наблюдение. Причина отсутствия называет, какой из двух
+        случаев произошёл: `selector_no_match:` либо `attribute_absent:`.
+    """
+    if node is None:
+        return Observed.missing(f"selector_no_match:{field_name}")
+
+    attributes = node.attributes or {}
+    # Проверяется наличие ключа, а не значение по нему. Разборщик отдаёт None и
+    # для атрибута без значения, и для пустого, так что .get() свёл бы «атрибута
+    # нет» с «атрибут пуст» - ровно то различие, ради которого файл и написан.
+    if name not in attributes:
+        return Observed.missing(f"attribute_absent:{field_name}")
+
+    raw = attributes[name]
+    if raw is None:
+        # `data-href` без значения и `data-href=""` разборщик не различает, и
+        # различать их незачем: оба означают «атрибут есть, значения нет».
+        return Observed.empty("")
+
+    value = raw.strip()
+    return Observed.present(value) if value else Observed.empty("")
+
+
+#: Как выглядит языковая метка по BCP 47.
+#:
+#: Проверка формы, а не перечня: перечень объявлен контрактом и означает другое -
+#: для каких локалей у адаптера есть текстовые шаблоны. Здесь вопрос проще:
+#: похоже ли прочитанное на метку языка вообще.
+_LANGUAGE_TAG = re.compile(r"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$")
+
+
+def observe_locale(html: str) -> Observed[str]:
+    """Читает локаль интерфейса со страницы.
+
+    Локаль привязана к аккаунту, а не к адресу: запрос с префиксом /en/ отдаёт
+    ту же страницу на том же языке. Переключить её запросом нельзя, и
+    единственное, что остаётся, - узнать, какая она.
+
+    Прежде не узнавали вовсе. Страница на чужой локали разбиралась молча, и
+    вызывающий получал английские тексты, полагая их русскими: поля, которые
+    приходят текстом - описание заказа, подпись времени, имя собеседника, -
+    возвращаются на том языке, на котором их отдала площадка.
+
+    Прочитанное проверяется на форму. Атрибут, который есть и языковой меткой
+    не выглядит, даёт ненаблюдённое значение, а не локаль: сообщить «интерфейс
+    отдан на локали T2:a#1» хуже, чем сказать «локали не видно».
+
+    Случай не выдуманный. Структурный скелет заменяет значения атрибутов
+    подписями, и всякий снимок проекта несёт в lang подпись вместо метки. Разбор
+    такого снимка объявлял возможность protocol.locale неподдержанной и писал в
+    журнал предупреждение о локали, которой не бывает, - то есть собственные
+    фикстуры проекта заставляли его говорить неправду. Проверка формы закрывает
+    это для снимков любой версии, включая уже снятые.
+
+    Args:
+        html (str): Разметка страницы.
+
+    Returns:
+        Observed[str]: Локаль либо причина, по которой её не видно. Исходов
+        четыре: узла нет, атрибута нет, значение пусто, значение не метка.
+    """
+    node = HTMLParser(html).css_first(SELECTORS["session.locale"])
+    observed = attribute(node, ATTRIBUTES["session.locale.attribute"], "locale")
+    # Пустой атрибут проверке формы не подлежит: это факт о странице - площадка
+    # отдала пустую локаль, - а не мусор в значении. Сводить их значило бы
+    # отбирать у вызывающего единственный способ их различить.
+    if observed.presence is not Presence.PRESENT:
+        return observed
+    if _LANGUAGE_TAG.match(observed.value) is None:
+        return Observed.missing("locale_not_a_language_tag")
+    return observed

funora/_field_schema.py

@@ -0,0 +1,112 @@
+"""Схема фильтров раздела по наблюдённым элементам .lot-fields."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from selectolax.parser import HTMLParser
+
+from ._extract import attribute, text
+from ._observed import Observed
+from ._result import Completeness, Defect, Severity
+from .errors import IncompleteResultError, UnsupportedCapabilityError
+from .extraction import SELECTORS
+
+
+@dataclass(frozen=True, slots=True)
+class FieldOption:
+    """Вариант выбора. Пустое value тоже является допустимым значением."""
+
+    value: Observed[str]
+    label_text: Observed[str]
+
+
+@dataclass(frozen=True, slots=True)
+class FieldDefinition:
+    """Поле фильтра; kind открыт для новых видов, неизвестный вид - unknown."""
+
+    field_id: Observed[str]
+    input_name: Observed[str]
+    label_text: Observed[str]
+    kind: str
+    options: tuple[FieldOption, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class FieldSchema:
+    """Схема конкретного раздела с явным признаком полноты."""
+
+    section_id: str
+    observed_at: datetime
+    completeness: Completeness
+    reason: str
+    defects: tuple[Defect, ...] = ()
+    _fields: tuple[FieldDefinition, ...] = field(default=(), repr=False)
+
+    def fields(self, *, accept_incomplete: bool = False) -> tuple[FieldDefinition, ...]:
+        if self.completeness is not Completeness.COMPLETE and not accept_incomplete:
+            raise IncompleteResultError(f"схема полей неполна: {self.reason}")
+        return self._fields
+
+
+def parse_field_schema(html: str, *, section_id: str, observed_at: datetime) -> FieldSchema:
+    """Читает choice и range; новый вид сохраняется как неполный результат."""
+    tree = HTMLParser(html)
+    container = tree.css_first(SELECTORS["catalog.field_schema.container"])
+    if container is None:
+        raise UnsupportedCapabilityError("на странице раздела нет наблюдённого блока полей")
+    fields: list[FieldDefinition] = []
+    defects: list[Defect] = []
+    seen: set[str] = set()
+    for index, node in enumerate(container.css(SELECTORS["catalog.field_schema.fields"])):
+        field_id = attribute(node, "data-id", "field_id")
+        input_name = attribute(
+            node.css_first(SELECTORS["catalog.field_schema.input"]), "name", "input_name"
+        )
+        choice = node.css_first(SELECTORS["catalog.field_schema.kinds.choice"])
+        range_box = node.css_first(SELECTORS["catalog.field_schema.kinds.range"])
+        kind = "choice" if choice is not None else "range" if range_box is not None else "unknown"
+        options = (
+            tuple(
+                FieldOption(attribute(button, "value", "value"), text(button, "option_label"))
+                for button in choice.css(SELECTORS["catalog.field_schema.kinds.choice.options"])
+            )
+            if choice is not None
+            else ()
+        )
+        problems: list[str] = []
+        if not field_id.or_none() or not input_name.or_none():
+            problems.append("field_identifier_missing")
+        name = input_name.or_none()
+        if name:
+            if name in seen:
+                problems.append("duplicate_input_name")
+            seen.add(name)
+        if kind == "unknown" or (choice is not None and range_box is not None):
+            problems.append("field_kind_unrecognized")
+        if choice is not None and (
+            not options
+            or any(not option.value.is_observed for option in options)
+            or len({option.value.or_none() for option in options}) != len(options)
+        ):
+            problems.append("choice_options_unusable")
+        for code in problems:
+            defects.append(Defect(severity=Severity.ROW, code=code, detail=code, row_index=index))
+        fields.append(
+            FieldDefinition(
+                field_id,
+                input_name,
+                text(node.css_first(SELECTORS["catalog.field_schema.label"]), "label"),
+                kind,
+                options,
+            )
+        )
+    return FieldSchema(
+        section_id,
+        observed_at,
+        Completeness.PARTIAL if defects else Completeness.COMPLETE,
+        "field_defects" if defects else "all_fields_parsed",
+        tuple(defects),
+        tuple(fields),
+    )

funora/_fileio.py

@@ -0,0 +1,58 @@
+"""Атомарная запись и межпроцессная блокировка локальных журналов."""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def file_lock(path: Path, *, blocking: bool = True) -> Iterator[None]:
+    """Блокирует отдельный постоянный файл на время чтения и изменения данных.
+
+    Файл блокировки не удаляется: удаление позволило бы двум процессам
+    блокировать разные inode по одному пути. ОС освобождает блокировку при
+    завершении процесса, в том числе аварийном.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a+b") as handle:
+        if sys.platform == "win32":
+            import msvcrt
+
+            if os.fstat(handle.fileno()).st_size == 0:
+                handle.write(b"\0")
+                handle.flush()
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK if blocking else msvcrt.LK_NBLCK, 1)
+            try:
+                yield
+            finally:
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB))
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def atomic_write(path: Path, body: str) -> None:
+    """Публикует полностью записанный файл; при отказе сохраняет прежний."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    temporary = Path(name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(body)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)

funora/_gate.py

@@ -0,0 +1,69 @@
+"""Ворота возможности: пускать вызов или отказать.
+
+Ворота задают два вопроса, а не один, и порядок между ними значения не имеет -
+важно, что задаются оба. Первый: есть ли позитивное свидетельство того, что
+возможности нет. Второй: не требует ли состояние явного включения, которого
+вызывающий не давал.
+
+Ошибиться здесь легко ровно одним способом: спросить «работает ли возможность»
+вместо «можно ли звать её прямо сейчас». Это разные вопросы, и у состояния
+experimental ответы на них противоположны. Так и произошло в первой версии
+порождённого модуля возможностей.
+
+Отдельно стоит объяснить, почему unknown пропускается. Состояние означает «ещё
+не выяснено», а не «нет». Блокировать по нему значило бы запрещать работу из-за
+собственной неуверенности, и SDK выглядел бы как не умеющий ничего. Позитивным
+свидетельством отсутствия может быть только полученный ответ, а не отсутствие
+ответа.
+"""
+
+from __future__ import annotations
+
+from .capabilities import CAPABILITY_INITIAL, Capability, CapabilityState
+from .errors import ExperimentalCapabilityError, UnsupportedCapabilityError
+
+__all__ = ["check_capability"]
+
+
+def check_capability(
+    capability: Capability,
+    *,
+    state: CapabilityState | None = None,
+    opted_in: bool = False,
+) -> CapabilityState:
+    """Проверяет, разрешён ли вызов возможности.
+
+    Args:
+        capability (Capability): Проверяемая возможность.
+        state (CapabilityState | None): Текущее состояние. По умолчанию берётся
+            начальное из спецификации.
+        opted_in (bool): Включил ли вызывающий возможность явно.
+
+    Returns:
+        CapabilityState: Состояние, с которым вызов пропущен.
+
+    Raises:
+        UnsupportedCapabilityError: Если есть позитивное свидетельство того, что
+            возможности нет.
+        ExperimentalCapabilityError: Если состояние требует явного включения, а
+            вызывающий его не дал. Контракт такой возможности может измениться,
+            и молча его принимать нельзя за того, кто про это не знает.
+    """
+    current = state if state is not None else CAPABILITY_INITIAL[capability]
+
+    # Решение берётся у порождённого allows_call, а не собирается здесь заново.
+    # Правило объявлено нормативным в spec/capabilities.yaml, и второй его
+    # экземпляр разошёлся бы с первым молча: состояния те же, поведение разное.
+    if current.allows_call(opted_in=opted_in):
+        return current
+
+    if current.opt_in_required:
+        raise ExperimentalCapabilityError(
+            f"возможность {capability.value} экспериментальна: контракт может "
+            "измениться. Включите её явно, если готовы к этому"
+        )
+
+    raise UnsupportedCapabilityError(
+        f"возможность {capability.value} отсутствует по наблюдению. "
+        "Это не догадка: состояние выставляется только по полученному ответу"
+    )

funora/_hops.py

@@ -0,0 +1,101 @@
+"""Решение о следующем переходе, отделённое от способа сходить в сеть.
+
+Модуль появился ради асинхронного транспорта. Без него правило переходов
+пришлось бы написать второй раз - а именно оно однажды уже стоило сессионного
+ключа, и оно же в проекте уже жило трижды и по-разному (см. [_host.py]).
+Копия правила безопасности расходится ровно так же, как любая другая, но цена
+расхождения здесь - чужой доступ к аккаунту.
+
+Функция чистая: на вход - то, что видно в ответе, на выход - решение. Ни
+синхронный, ни асинхронный транспорт не знают, как оно принято, и оба обязаны
+поступить одинаково.
+
+Решений три, и они не сводятся к двум.
+
+``Stop`` - переходов больше нет либо исчерпан предел. Ответ, который на руках,
+и есть конечный.
+
+``Follow`` - переход проверен, секрет можно отправить дальше.
+
+``Reject`` - переход уводит с ожидаемого хоста либо понижает схему. Запрос туда
+не отправляется вовсе: проверка после отправки бесполезна, секрет уже ушёл бы.
+Отвергнутый адрес всё равно объявляется конечным - это не мелочь, а разница
+между диагнозом «нас пытались увести» и диагнозом «разметка изменилась».
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urljoin
+
+from ._host import is_safe_hop
+
+__all__ = ["Stop", "Follow", "Reject", "Hop", "next_hop"]
+
+
+@dataclass(frozen=True, slots=True)
+class Stop:
+    """Переходов больше нет: ответ на руках конечный."""
+
+
+@dataclass(frozen=True, slots=True)
+class Follow:
+    """Переход проверен и разрешён.
+
+    Attributes:
+        url (str): Адрес, по которому можно отправить запрос вместе с секретом.
+    """
+
+    url: str
+
+
+@dataclass(frozen=True, slots=True)
+class Reject:
+    """Переход отвергнут: секрет туда не уходит.
+
+    Attributes:
+        url (str): Адрес, куда нас пытались увести. Объявляется конечным, чтобы
+            классификатор увидел чужой хост и поставил диагноз wrong_identity, а
+            не unknown по пустому телу.
+    """
+
+    url: str
+
+
+#: Любое из трёх решений.
+Hop = Stop | Follow | Reject
+
+
+def next_hop(
+    *,
+    current: str,
+    is_redirect: bool,
+    location: str,
+    redirects: int,
+    max_redirects: int,
+    expected: str,
+) -> Hop:
+    """Решает, что делать с полученным ответом.
+
+    Args:
+        current (str): Адрес, на который был отправлен запрос.
+        is_redirect (bool): Является ли ответ перенаправлением.
+        location (str): Значение заголовка Location. Пустая строка, если его нет.
+        redirects (int): Сколько переходов уже выполнено.
+        max_redirects (int): Предел числа переходов.
+        expected (str): Ожидаемый хост площадки.
+
+    Returns:
+        Hop: Stop, Follow либо Reject.
+    """
+    if not is_redirect or redirects >= max_redirects:
+        return Stop()
+    if not location:
+        # Перенаправление без адреса перехода. Идти некуда, и придумывать адрес
+        # самим - последнее, чем стоит заниматься с секретом в руках.
+        return Stop()
+
+    target = urljoin(current, location)
+    if not is_safe_hop(current, target, expected):
+        return Reject(target)
+    return Follow(target)

funora/_host.py

@@ -0,0 +1,120 @@
+"""Правило «тот ли это хост».
+
+Файл появился после разбора, который нашёл это правило написанным в проекте
+трижды и по-разному: верно в классификаторе, подстрокой в разборе переписки и
+отсутствующим в транспорте. Последнее стоило сессионного ключа: переход по
+заголовку Location уводил запрос на чужой адрес вместе с секретом.
+
+Сравнение подстрокой особенно коварно тем, что выглядит работающим. Адрес
+``https://funpay.com.evil.example/`` содержит ``funpay.com`` и проходит такую
+проверку, а ведёт совсем не туда.
+
+Правило одно на весь пакет и живёт здесь: разъехаться трём копиям было легко,
+одной копии - не с чем.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+from urllib.parse import urlparse
+
+__all__ = ["host_of", "same_host", "is_safe_hop"]
+
+
+#: Имя хоста, каким его допускает DNS.
+#:
+#: Метки из букв, цифр и дефисов, разделённые точками. Всё остальное именем
+#: хоста не является, и притворяться им не должно.
+_HOSTNAME_RE: Final[re.Pattern[str]] = re.compile(
+    r"^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))*\.?$"
+)
+
+
+def host_of(url: str) -> str:
+    """Извлекает хост из адреса.
+
+    Возвращает пустую строку, если разобранное имя хоста именем хоста не
+    является. Проверка не косметическая, и вот почему.
+
+    Питон разбирает адрес по RFC 3986, браузер - по правилам WHATWG, и в одном
+    месте они расходятся: обратная косая черта. Для питона
+    ``https://evil.example\\.funpay.com/`` имеет хост
+    ``evil.example\\.funpay.com``, и правило «оканчивается на .funpay.com»
+    признаёт такой адрес своим. Браузер по тому же адресу идёт на
+    ``evil.example``, а всё остальное считает путём.
+
+    Расхождение стоит дорого дважды. Ссылка в переписке проходит как своя,
+    хотя ведёт к чужому. Путь такой ссылки сохраняется в снимке дословно, как
+    сохраняются пути площадки, - и написанное там имя уходит в открытый
+    репозиторий, вместо того чтобы стать ``{t}``.
+
+    Args:
+        url (str): Адрес.
+
+    Returns:
+        str: Хост без порта, в нижнем регистре. Пустая строка, если хоста нет
+        либо разобранное имя недопустимо в DNS.
+    """
+    host = (urlparse(url).hostname or "").lower()
+    if not host or not _HOSTNAME_RE.match(host):
+        return ""
+    return host
+
+
+def same_host(url: str, expected: str) -> bool:
+    """Сообщает, принадлежит ли адрес ожидаемому хосту.
+
+    Поддомен ожидаемого хоста считается своим: у площадки есть поддомены, и
+    отвергать их значило бы отвергать её же страницы. Сравнение идёт по границе
+    точки, а не подстрокой: адрес вида ``funpay.com.evil.example`` содержит
+    ожидаемый хост как подстроку и ведёт не туда.
+
+    Args:
+        url (str): Проверяемый адрес.
+        expected (str): Ожидаемый хост. Порт, если он есть, отбрасывается.
+
+    Returns:
+        bool: True, если адрес принадлежит ожидаемому хосту либо его поддомену.
+    """
+    want = expected.split("@")[-1].split(":")[0].strip().lower().rstrip(".")
+    if not want or not _HOSTNAME_RE.match(want):
+        return False
+
+    # host_of отвергает имена, недопустимые в DNS, и пустая строка здесь
+    # означает «своим это считать нельзя». Направление отказа безопасное во всех
+    # трёх местах, где правило применяется: секрет не уходит, ссылка считается
+    # чужой, путь маскируется целиком.
+    actual = host_of(url).rstrip(".")
+    if not actual:
+        return False
+
+    return actual == want or actual.endswith("." + want)
+
+
+def is_safe_hop(current: str, target: str, expected: str) -> bool:
+    """Решает, можно ли отправить секрет по следующему переходу.
+
+    Два условия, и оба обязательны.
+
+    Целевой адрес принадлежит ожидаемому хосту. Иначе секрет уходит туда, где
+    ему делать нечего, и одного заголовка Location достаточно для угона
+    аккаунта.
+
+    Схема не понижается. Переход с https на http отдаёт секрет открытым текстом
+    любому, кто видит трафик, и заметить это по поведению клиента невозможно.
+
+    Args:
+        current (str): Адрес, с которого выполняется переход.
+        target (str): Адрес перехода.
+        expected (str): Ожидаемый хост площадки.
+
+    Returns:
+        bool: True, если переход безопасен.
+    """
+    if not same_host(target, expected):
+        return False
+
+    was_secure = urlparse(current).scheme == "https"
+    goes_secure = urlparse(target).scheme == "https"
+    return goes_secure or not was_secure