Введение - Python API

Python API

Python API

Примечание

Перед началом работы установите Python-клиент из pip-репозитория следующей командой:

pip install ytsaurus-client

После установки пакета становится доступным:

Python библиотека yt;
Бинарный файл yt;
Бинарный файл yt-fuse для подключения Кипариса в качестве файловой системы локально.

Установка

Библиотеки YSON

Для использования YSON формата для работы с таблицами потребуются C++ биндинги, которые устанавливаются отдельным пакетом. Установка YSON биндингов:

pip install ytsaurus-yson

Внимание

В настоящий момент нет возможности установить YSON биндинги под Windows.

Для пользователей платформы Apple M1

В настоящий момент нет YSON биндингов собранных под платформу Apple. В качестве временного решения можно воспользоваться Rosetta 2 и установить версию Python для архитектуры x86_64.

Подробнее об этом можно прочитать по ссылке.

Подробнее про YSON можно прочитать в разделе Форматы.

Чтобы узнать версию установленной обертки из Python, распечатайте переменную yt.VERSION или вызовите команду yt --version.

При возникновении проблем ознакомьтесь с разделом FAQ. Если проблема сохранилась, напишите в чат.

Исходный код библиотеки.

Внимание

Не рекомендуется устанавливать библиотеку и зависимые от нее пакеты разными способами одновременно. Это может приводить к трудно диагностируемым проблемам.

Документация для пользователей

Справка

Самая актуальная справка по конкретным функциям и их параметрам находится в коде.

Посмотреть описание функций и классов в интерпретаторе можно следующим образом:

$ python
>>> import yt.wrapper as yt
>>> help(yt.run_sort)

Примеры

FAQ

В данном разделе собраны ответы на ряд частых вопросов, касающихся Python API. Ответы на другие частые вопросы в разделе FAQ.

Q: Установил пакет через pypi, но получаю ошибку yt: command not found.
A: Попробуйте выполнить команду
pip install ytsaurus-client --force-reinstall
скорее всего в логе будет warning вида The script yt is installed in '...' which isn't on your PATH. Для решения проблемы необходимо добавить указанный путь в переменную окружения PATH. Для этого нужно выполнить следующую команду:

echo 'export PATH="$PATH:<указанный путь>"' >> ~/.bashrc
source ~/.bashrc

В зависимости от оболочки файл может называться по-другому. Чаще всего на Mac он называется ~/.zshrc.

Q: Чтение с retry завершается ошибкой из-за превышения таймаута.
A: Скорее всего в таблице слишком много чанков, нужно укрупнить их. Используйте yt merge --src table --dst table --spec "{combine_chunks=true}"

Q: Операция завершается с ошибкой YSON-а (например: YsonError: Premature end of stream), а в веб-интерфейсе появляется ошибка парсинга YSON.
A: Скорее всего, операция пишет в stdout. Это запрещено делать явно в Python через print, sys.stdout.write(), если операция не помечена как raw_io, но это может делать сторонняя программа, например, архиватор.

Q: Python библиотека слишком много пишет в stderr, как повысить уровень логирования?
A: Уровень можно повысить, установив переменную окружения YT_LOG_LEVEL="ERROR", или через настройку логгера YTsaurus: logging.getLogger("Yt").setLevel(logging.ERROR).

Q: Запускаю операцию с Mac OS X, а джобы завершаются с ошибками типа ImportError: ./tmpfs/modules/_ctypes.so: invalid ELF header.
A: Так как Python wrapper забирает с собой на кластер все зависимости Python операции, то туда же приезжают бинарные .so и .pyc файлы, которые потом не могут быть загружены. Стоит использовать porto-слой с вашим локальным окружением, а также включить фильтрацию этих файлов, чтобы они не попадали на кластер. Подробнее можно прочитать в разделе.

Q: Джобы завершаются с ошибкой Invalid table index N: expected integer in range [A,B].
A: Сообщение означает, что в записях вы выдаете table index, причем соответствующей таблицы нет. Чаще всего это означает, что у вас несколько входных таблиц, а выходная таблица одна. Во входных записях по умолчанию приходят поля @table_index, чтобы их выключить, можно поменять формат: yt.config["tabular_data_format"] = yt.YsonFormat(process_table_index=None). Подробнее про формат можно прочитать в разделе). В качестве альтернативы явно укажите в спецификации (пример для map-операции): {"mapper": {"enable_input_table_index": False}}.

Q: При запуске операции, после того, как она стала completed, появляется ошибка (ReadTimeout, HTTPConnectionPool(....): Read timed out.).
A: Сообщение означает, что не удалось скачать stderr операции из-за сетевых проблем, причём не помогли даже повторные запросы. В таком случае, стоит воспользоваться опцией ignore_stderr_if_download_failed, которая позволяет игнорировать stderr, если его не удалось скачать. Рекомендуется использовать опцию при написании production-процессов.

Q: Получаю ошибку Yson bindings required.
A: Это означает, что в качестве входного (выходного) формата выбран YSON и в джобе не удалось импортировать биндинги. Подробнее про YSON и биндинги к нему можно прочитать в разделе. Нужно установить пакет с биндингами, а также проверить, что YSON биндинги не отфильтровываются с помощью module_filter. Это динамическая библиотека yson_lib.so, и ее можно легко нечаянно отфильтровать, если отфильтровывать все .so файлы. Кроме того, чтобы yt_yson_bindings, приехавшие в модулях, не удалялись, в файле конфигурации нужно прописать config["pickling"]["ignore_yson_bindings_for_incompatible_platforms"] = False.