Ресурсы companion на Python

Ресурс companion хранит объект, общий для джобов одного процесса Python: например, клиент или справочные данные. Flow создаёт его с помощью зарегистрированной фабрики и управляет жизненным циклом. У каждого процесса companion свои экземпляры, в том числе при запуске нескольких интерпретаторов.

Используйте этот API после настройки Python companion. Прокси на воркере, зависимости ресурсов и привязки компьютейшена описаны в разделе Подключение ресурсов companion.

Регистрация класса ресурса

Реализуйте FlowResource из yt.yt.flow.library.python.companion и зарегистрируйте его в Pipeline до вызова pipeline.run():

  • pipeline.add_resource(resource_class) использует класс как фабрику без аргументов.
  • pipeline.add_resource(resource_class, factory) использует вашу фабрику без аргументов и имя, полученное из класса.
  • pipeline.add_resource(name, factory) регистрирует явно заданное имя реализации; фабрика обязательна.

При каждом вызове фабрика должна возвращать новый экземпляр FlowResource. У разных идентификаторов ресурсов и у заменяющих экземпляров независимые жизненные циклы. Регистрация фабрики не загружает ресурс.

При регистрации по классу именем реализации служит непустой атрибут flow_resource_class, заданный в самом классе, или полное имя module.qualname. Атрибут не наследуется от базового класса. Укажите это имя в parameters.companion_resource_class; оно отличается от идентификатора ресурса и псевдонима в компьютейшене. Повторная регистрация одного имени отклоняется.

В поддерживаемом тестовом companion показаны именование по классу, явное имя, зависимость и чтение ресурса из компьютейшена. Соответствующие привязки заданы в спецификации пайплайна.

Жизненный цикл и контекст

Переопределите нужные методы ресурса. Аргумент ResourceContext передаёт текущую конфигурацию и инициализированные зависимости.

Метод

Назначение

load(context)

Инициализирует новый экземпляр по статическим и динамическим параметрам и зависимостям. Оставьте конструктор лёгким, а инициализацию ресурса выполняйте здесь.

reconfigure(context)

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

unload()

Освобождает удерживаемые объекты и внешние ресурсы. Очистка должна работать и после частично выполненного load.

context.resource_id — идентификатор из spec.resources. Словарь context.parameters содержит статические параметры ресурса, включая companion_resource_class, а context.dynamic_parameters — динамические параметры. Словарь context.dependencies сопоставляет псевдоним зависимости с её инициализированным FlowResource; если псевдоним не задан, ключом служит идентификатор зависимости. Зависимости удерживаются всё время жизни зависимого экземпляра.

Контекст также предоставляет общие для процесса http_client и https_client; см. HTTP-клиенты.

Чтение ресурса из пользовательского кода

В обработчике вызовите ctx.get_resource(alias), где ctx — контекст выполнения. Добавьте ресурс в required_resource_ids компьютейшена. Для поиска используется alias из этого требования, а если псевдоним не задан — идентификатор ресурса. Отсутствие привязки вызывает ValueError.

Получайте ресурс заново для каждого батча. Не сохраняйте экземпляр в компьютейшене или глобальной переменной между батчами: Flow может вывести его из использования и выполнить очистку до обращения из следующего батча.

Конкурентный доступ и ошибки

Один экземпляр может одновременно обслуживать несколько джобов и потоков. Синхронизируйте доступ к изменяемым данным внутри ресурса. Пока выполняется reconfigure, новые обращения за экземпляром отклоняются, но батчи и зависимые ресурсы, уже получившие его, могут продолжать работу. Удержание ресурса батчем откладывает очистку; оно не синхронизирует изменения и не создаёт снапшот конфигурации.

Если load завершился ошибкой после создания экземпляра, Flow пытается вызвать unload для частично инициализированного объекта. После ошибки reconfigure экземпляр перестаёт быть доступен новым потребителям; при последующей успешной инициализации создаётся новый. Очистка ждёт освобождения уже выданных ссылок. Исключение типа Exception из unload записывается в лог и подавляется; другие подклассы BaseException передаются вызывающему коду.

Воркер повторяет инициализацию согласно настройкам прокси. Предусмотрите повторную инициализацию и освобождение частично полученных объектов в unload. Управление жизненным циклом ресурса не делает внешние эффекты транзакционными.

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

Предыдущая
Computation
Следующая
Общие HTTP-клиенты