Python SDK: Context: запуск, данные и прогресс

Платформа передаёт ctx в def run(ctx):. Через него вы получаете параметры, обращаетесь к разрешённым сервисам и отдаёте результаты. Не создавайте ctx самостоятельно.

Примеры являются фрагментами тела def run(ctx):. Все методы SDK синхронны, await не нужен.

Методы

• http()
• state()
• storage()
• browser()
• captcha()
• wildberries()
• dom()
• json()
• text()
• url()
• emit()
• flush()
• log()
• progress()
• metric()
• param()
• params()
• credential()
• sleep()
• cancelled()
• abort()
• fail()
• now()
• mail()
• documents()
• ai()
• sources()

http

ctx.http() -> HttpClient

Аргументы не нужны.

Результат: HttpClient. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить клиент для запросов к сайту. Все запросы используют сетевые настройки текущего сайта.

result = ctx.http()

state

ctx.state() -> KeyValue

Аргументы не нужны.

Результат: KeyValue. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить хранилище небольшого состояния обхода. Подходит для номера последней обработанной страницы.

result = ctx.state()

storage

ctx.storage(code) -> Storage

Результат: Storage. Объект SDK: используйте его методы, не передавайте целиком в emit.

Выбрать файловое S3-хранилище по коду подключения. Подключение нужно заранее настроить и разрешить для сайта.

result = ctx.storage('media')

browser

ctx.browser() -> Browser

Аргументы не нужны.

Результат: Browser. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить браузер для страниц, которым нужен Python, клики или прокрутка.

result = ctx.browser()

wildberries

ctx.wildberries() -> Wildberries

Аргументы не нужны.

Результат: Wildberries. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить готовый источник карточек для сайта, созданного из решения Wildberries. Список товаров и регионов берётся из настроек сайта. Все методы и пример.

result = ctx.wildberries()

dom

ctx.dom(html, base_url=None) -> Dom

Результат: Dom. Объект SDK: используйте его методы, не передавайте целиком в emit.

Разобрать уже полученный HTML. base_url нужен для преобразования относительных ссылок в полные.

result = ctx.dom('<a href="/product">Product</a>', 'https://example.com')

json

ctx.json(text) -> Any

Результат: Any.

Разбирает JSON-текст средствами Python. При невалидном JSON выбрасывает ошибку; параметра глубины у Python-метода нет.

result = ctx.json('{"items": []}')

text

ctx.text() -> TextTools

Аргументы не нужны.

Результат: TextTools. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить помощник для очистки текста, цен и артикулов.

result = ctx.text()

url

ctx.url() -> UrlTools

Аргументы не нужны.

Результат: UrlTools. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить помощник для ссылок, query-параметров и шаблонов страниц.

result = ctx.url()

emit

ctx.emit(item, key=None) -> None

Результат: None. Метод не возвращает значение данных.

Добавляет словарь Python в результат. Не передавайте объекты Response, Dom или Document целиком: соберите нужные поля. Стабильный key позволит обновить запись в следующем прогоне.

ctx.emit({'sku': 'A-1', 'price': 1250}, 'A-1')

flush

ctx.flush() -> None

Аргументы не нужны.

Результат: None. Метод не возвращает значение данных.

Отправить накопленную пачку записей, не дожидаясь автоматической отправки.

result = ctx.flush()

log

ctx.log(message, context=None, level='info') -> None

Результат: None. Метод не возвращает значение данных.

Записать понятное сообщение в журнал прогона. Дополнительные значения передаются объектом context.

ctx.log('Collection started', {'category': 'cables'}, 'info')

progress

ctx.progress(done, total=None, label=None, percent=None) -> None

Результат: None. Метод не возвращает значение данных.

Показать выполненную часть работы и название пользовательского этапа. total можно не знать заранее.

ctx.progress(1, 10, 'Catalog')

metric

ctx.metric(name, value=1) -> None

Результат: None. Метод не возвращает значение данных.

Добавить числовую метрику выполнения, например количество пропущенных карточек.

ctx.metric('processed', 1)

param

ctx.param(name, default=None) -> Any

Результат: Any.

Получить один параметр запуска. default используется, если параметра нет или его значение None.

result = ctx.param('catalog_url', '')

params

ctx.params() -> dict[str, Any]

Аргументы не нужны.

Результат: dict[str, Any].

Получить сразу все параметры запуска.

result = ctx.params()

credential

ctx.credential(name) -> str

Результат: str.

Получить именованный секрет для доступа к целевому сайту. Имя должно соответствовать настроенному ключу.

result = ctx.credential('site_token')

sleep

ctx.sleep(ms) -> None

Результат: None. Метод не возвращает значение данных.

Сделать контролируемую паузу. Аргумент измеряется в миллисекундах.

ctx.sleep(250)

cancelled

ctx.cancelled() -> bool

Аргументы не нужны.

Результат: bool.

Узнать, запросил ли пользователь остановку. Проверяйте в длительных циклах.

result = ctx.cancelled()

abort

ctx.abort(reason) -> NoReturn

Результат: NoReturn.

Остановить выполнение с объяснением причины, сохранив состояние для возможного продолжения. Прогон получает статус остановленного. Если источник ответил ошибкой или сломался формат данных, используйте fail().

ctx.abort('Collection stopped')

fail

ctx.fail(reason) -> NoReturn

Результат: NoReturn.

Завершить прогон с ошибкой, когда источник недоступен или ответ не соответствует ожидаемому формату. В отличие от abort(), такая остановка отмечается как ошибка, а не отмена.

ctx.fail('Website returned an unexpected response')

now

ctx.now() -> datetime

Аргументы не нужны.

Результат: datetime.

Возвращает datetime.datetime с текущим временем UTC и timezone. Для JSON используйте ctx.now().isoformat(); объект datetime целиком не сериализуется в emit.

result = ctx.now()

mail

ctx.mail() -> Mail

Аргументы не нужны.

Результат: Mail. Объект SDK: используйте его методы, не передавайте целиком в emit.

Открывает методы чтения входящего письма в почтовом сценарии. Содержимое доступно только для закреплённого события.

result = ctx.mail()

documents

ctx.documents() -> Documents

Аргументы не нужны.

Результат: Documents. Объект SDK: используйте его методы, не передавайте целиком в emit.

Открывает чтение и разбор разрешённых файлов Excel, PDF, Word, CSV и текста.

result = ctx.documents()

ai

ctx.ai() -> Ai

Аргументы не нужны.

Результат: Ai. Объект SDK: используйте его методы, не передавайте целиком в emit.

Открывает методы анализа, извлечения и преобразования данных. Сетевые вызовы AI синхронны и учитываются в бюджете пространства.

result = ctx.ai()

sources

ctx.sources() -> Sources

Аргументы не нужны.

Результат: Sources. Объект SDK: используйте его методы, не передавайте целиком в emit.

Открывает закреплённые входы процесса и локальное сравнение цен. Сами входы доступны только сценарию соответствующего процесса.

result = ctx.sources()

yandex_market

ctx.yandex_market() -> YandexMarket

Аргументы не нужны.

Результат: YandexMarket. Объект SDK: используйте его методы, не передавайте целиком в emit.

Получить настроенный источник Яндекс Маркета. Его методы сохраняют проверки готового решения.

result = ctx.yandex_market()

Ошибки и контекст выполнения

Все вызовы синхронны. Неверный аргумент или формат данных может вызвать ValueError/TypeError; отказ платформы или недоступность сервиса вызывает RuntimeError. Отсутствие элемента/значения даёт None либо пустой список только там, где это явно описано. Не превращайте любое исключение в пустой успешный результат. Методы внешних сервисов недоступны в преобразовании выгрузки; см. ограничения преобразований и среду.

captcha

captcha() -> Captcha

Возвращает API явных заданий. Каталог и оценка цены не создают платное задание. Создание, получение статуса и обратная связь работают через учёт пространства в облаке и на агенте.

Подробный справочник методов.