Funora для Python

Эталонная реализация контракта Funora.

English

Неофициальный проект. Funora не аффилирована с FunPay, не одобрена ею и никак с ней не связана. Работает с приватным веб-интерфейсом, который может измениться в любой момент без предупреждения. Использование может привести к блокировке аккаунта и заморозке средств - этот риск несёте вы. Прочитайте DISCLAIMER.md прежде, чем строить на этом то, что приносит вам деньги.

Тестовый pre-alpha: 0.0.1.dev2

Установка из PyPI:

python -m pip install "funora==0.0.1.dev2"

Установка и ограничения описаны в заметке о выпуске. Контракт пока имеет статус draft; сборка пакета не означает проверку всех операций на действующем аккаунте. Новые версии на PyPI выходят на крупных этапах; текущая доработка идёт в ветках и PR.

Реализованы и проверяются тестами тридцать пять операций: двадцать четыре чтения и одиннадцать записей - отправка текста и картинки, отметка прочтения, отзыв и его снятие, правка цены лота, поднятие предложений, включение и выключение лота, смена валюты интерфейса и возврат по заказу.

Руководство: docs/index.md. Оно собирается в сайт (mkdocs serve) и проверяется тем же прогоном, что и код: примеры разбираются интерпретатором, ссылки разрешаются, а каждая упомянутая операция ищется на настоящем клиенте.

Что это

Python SDK для FunPay. Здесь протокол прорабатывается первым; остальные языки реализуют его заново по спецификации, а не портируют этот код построчно.

from funora import Client, EnvSecretProvider

# Секрет берётся из FUNORA_GOLDEN_KEY и в коде не появляется ни разу.
with Client(EnvSecretProvider()) as client:
    page = client.orders.list()
    for order in page.rows():
        print(order.order_id, order.description_text)

То же асинхронно. Фасада два, ядро одно: нормативный порядок шагов, политика повторов, расход бюджета и правила курсора написаны один раз и обоим достаются готовыми. Перевод бота сводится к await.

from funora import AsyncClient, EnvSecretProvider

async with AsyncClient(EnvSecretProvider()) as client:
    page = await client.orders.list()
    for order in page.rows():
        print(order.order_id, order.description_text)

Что уже работает

Реакция за секунды, а не за минуты

У площадки есть собственный канал обновлений - POST /runner/, промежуток пять секунд, - и наблюдение его слушает. Пока канал молчит, страницы не читаются вовсе; сказал «изменилось» - читаются немедленно. Прежде изменение замечалось за время опроса: от трёх секунд при активности до двух минут в тишине.

Из канала берётся ОДНО решение: изменилось что-нибудь или нет. События по-прежнему собираются чтением страниц, тем же кодом и с теми же гарантиями. Так и задумано: поведения канала при истёкшей сессии и при исчерпании предела не наблюдал никто, а сигналу верить не нужно - ошибка в одну сторону стоит лишнего чтения страниц, в другую ловится сторожевым сроком в две минуты.

Непонятный ответ канала не роняет наблюдение: оно возвращается к опросу страниц и говорит об этом в журнал. Выключить быстрый путь целиком - client.watch(router, use_channel=False).

Для операций записи существенны исход запроса и сохранность прежнего состояния.

Отправка текста - глава в руководстве: исходов у неё три, а не два, и третий - «неизвестно» - это то, ради чего глава написана.

Правка цены - глава про лоты: отправляется прочитанное целиком, меняется ровно одно поле, а прежняя цена ложится в долговечный журнал раньше, чем уходит запрос. Без файла состояния операция отказывает: у площадки нет ни истории цен, ни отката, и «как было» знает только наша запись.

Поверх этого есть слой бота: funora.bot. Он даёт очередь исходящих, в которую можно класть из любого потока - скажем, из обработчика телеграм-бота, - а отправляет тот же поток, что ведёт наблюдение. Прямой вызов из чужого потока портит счёт ограничителя молча, и потому отвергается вслух.

Есть и вторая очередь - каталог с файлами, для телеграм-бота, поднятого ОТДЕЛЬНОЙ командой: до очереди в памяти он не дотягивается ничем. Задание, взятое умершим процессом, повторно не отправляется никогда - его судьба неизвестна, и решает о нём человек. Как это выглядит целиком - в главе про бота.

Полный реестр незавершённых механизмов с причинами лежит в Funora-spec/spec/conformance/not-implemented.yaml. Он включает ограничения планировщика, недостающие наблюдения и ещё не исполняемые части общего контракта. Наличие всех сервисных методов не означает, что весь межъязыковой контракт завершён.

Чего SDK пока не умеет

• Вывод средств не реализован.
• Догрузка длинных списков заказов и операций счёта: семантика continue ещё не установлена. Предыдущие сообщения чата читаются отдельной операцией.
• Восстановление пропущенных событий канала по позиции: сейчас используются повторное чтение страниц и сохранённые курсоры наблюдения.
• Отмена уже отправленного запроса ради более приоритетного.

Публичное чтение рынка уже использует отдельный транспорт без секрета аккаунта. Общий сетевой бюджет и пауза после HTTP 429 сохраняются.

Читаются состояния заказа paid, closed и refunded. Другие носители сохраняются как ненаблюдённое значение; выдачу нужно разрешать по конкретному состоянию, а не по условию «не закрыт». Сообщение в переписке не подтверждает оплату.

orders.details() читает сумму числом и код валюты из структурного ответа. Точное время нельзя восстановить там, где площадка даёт только текст для показа.

Возврат по заказу уже реализован: доступность формы проверяется перед запросом, а результат определяется по ответу. Проверка этой реализации на записанных ответах не заменяет проверку на действующем тестовом аккаунте.

Подробности: границы SDK, план наблюдений.

Как устроено

Три решения, которые видно в первом же вызове.

Результат - страница, а не список. Записи получают методом rows(), и при неполноте нужен явный accept_incomplete=True. Молча отданный неполный список неотличим от полного, и обработчик примет решение по данным, которых нет.

Поля различают «пусто» и «не наблюдалось». None одинаково выглядит для обоих случаев, а решения по ним противоположные: пустое описание перечитывать незачем, отсутствующее - повод заподозрить изменение вёрстки. Поэтому чтение .value у ненаблюдённого поля бросает исключение, а не возвращает None.

Механические части порождаются из спецификации. Ошибки, возможности, политики повторов, бюджет и таблица соответствия вердиктов ошибкам не пишутся руками ни в одном из шести SDK. Сборка падает, если порождённое отстало от источника.

Подробнее - в docs/architecture.md, а как этим пользоваться - в руководстве.

Наблюдения за протоколом

Пакет содержит инструмент funora-observe, которым собраны все факты о протоколе, на которых стоит спецификация. Он сохраняет структурный скелет страницы: разметка целиком, текст и значения атрибутов заменены подписями.

• docs/observations.md - что установлено и как проверить.
• docs/protocol-questions.md - что осталось открытым.
• docs/limits.md - чего Funora не умеет и почему это не чинится кодом.
• docs/observing.md - как снять наблюдение самому.
• tests/fixtures/pages/README.md - формат снимков и почему их можно публиковать.

Проект целиком

Funora - это один контракт, реализованный нативно на нескольких языках. Меняется язык, но не ментальная модель: Client, сервисы, события, роутер и таксономия ошибок означают одно и то же везде.

Участие в разработке

Сначала прочитайте CONTRIBUTING.md.

Полезнее всего сейчас три вещи.

Снимки страниц в состояниях, которых у нас нет: заказ в возврате или споре, непрочитанный диалог, длинный список с постраничной навигацией. Каждый такой снимок закрывает пункт в docs/protocol-questions.md.

Разбор спецификации в Funora-spec: она проверяется употреблением, и первая же попытка её применить дала восемнадцать мест, где она противоречила сама себе.

Реализация операций чтения по уже написанным правилам извлечения.

Безопасность

Никогда не вставляйте сессионный ключ, сырой HTML со страницы под авторизацией или содержимое личной переписки в публичный issue. Сессионный ключ FunPay - это доступ ко всему аккаунту. Сообщайте приватно через Security Advisories, подробности - в SECURITY.md.

Лицензия

Apache-2.0 © Funora Contributors