Python SDKBETA

В этой статье

Python SDK

Модуль разработки кастомных блоков на языке Python — это инструмент для гибкой настройки и расширения функционала модуля автоматизации с помощью пользовательских блоков и подключений. Он позволяет разработчикам создавать собственные решения, адаптированные под конкретные бизнес-задачи, обрабатывать данные и расширять возможности системы.

С помощью Python SDK вы можете:

Создавать пользовательские блоки. Эти блоки обрабатывают входные данные и возвращают результаты
Реализовывать подключения к внешним API, хранилищам данных или другим системам

Основные термины:

Группа объединяет несколько блоков и подключений в интерфейсе системы
Блок — основная вычислительная единица, получающая входные данные и возвращающая результат
Подключение используется для ввода данных из внешних источников. Оно содержит описание полей, которые будут доступны блоку, и метаинформацию, отображаемую в системе.

Структура проекта

src— корневая директория исходного кода проекта
- main — основная директория с исходниками
  - sdk — базовые компоненты SDK; директория содержит абстрактные классы, утилиты и классы для обработки данных. Все классы и модули здесь отвечают за базовую логику, которую используют пакеты
    - __init__.py— маркер модуля
    - abstract_group.py — абстрактная группа
    - abstract_block.py — абстрактный блок
    - abstract_connection.py — абстрактное подключение
    - argument_processor.py — класс для разбора и валидации аргументов запуска Python-скриптов
    - block_params.py — класс для централизованного хранения параметров блоков
    - default_info.py — шапка стандартного ответа на запрос --get-info
    - input_processor.py — класс, запускающий блок и обрабатывающий поток входных данных
    - message_wrapper.py — набор утилит для формирования сообщений в необходимом формате для обмена с системой
    - utils.py — набор базовых вспомогательных функций (валидация, преобразование данных и пр.)
  - packages — папка для пользовательских пакетов, в каждом из которых реализованы свои группы, блоки и подключения; название подпапки
    задается пользователем и служит пространством имен
    - <user_package_name> — основная директория конкретного пользовательского пакета
      
      blocks — папка с реализациями блоков (файлы с кодом блоков)
      
      __init__.py — маркер модуля
      
      connections — папка с реализациями подключений к внешним системам
      
      __init__.py — маркер модуля
      
      group.py — реализация класса группы, наследуемого от abstract_group.py; здесь описывается мета-информация о группе: UUID, название, иконка и т. п.
      
      python_group_<group_hash>.png — иконка группы; путь к этому файлу относительно папки пакета нужно вернуть в реализации метода группы get_icon(), тогда иконка появится на группе

Заметка

Пользовательские блоки должны храниться в папке blocks, подключения — в папке connections.

Абстрактная группа (abstract_group.py)

Абстрактная группа определяет интерфейс, который должна реализовать любая пользовательская группа: уникальный UUID, название, категория и путь к иконке. Это позволяет системе правильно отобразить группу и связать с ней нужные блоки.

С примерами использования групп можно ознакомиться на странице: Примеры пользовательских реализаций в Python SDK

Код абстрактной группы

Важно

Особенности при реализации группы:
- get_uuid() — возвращает уникальный идентификатор группы
- get_icon() — возвращает путь иконки, ассоциированной с группой относительно папки скрипта
- get_name() — возвращает варианты локализации имени группы в виде словаря
- get_info() — собирает и возвращает всю основную информацию о группе в виде словаря
- get_category() — возвращает категорию группы, используется для группировки в интерфейсе

from abc import abstractmethod
class AbstractGroup():
    def __init__(self):
        pass

    @abstractmethod
    def get_uuid(self)->str:
        """
        Returns group's uuid
        """
        return ""

    @abstractmethod
    def get_name(self)->dict:
        """
        Returns group's name (dict struct)
        """
        return {}

    @abstractmethod
    def get_icon(self)->str:
        """
        Returns group's icon file path
        """
        return ""

    @abstractmethod
    def get_category(self):
        """
        Returns group's type (default - "tools")
        """
        return ""

    def get_info(self):
        """
        Returns group's system info output for --get-info command
        """
        return {
            "uuid":self.get_uuid(),
            "name":self.get_name(),
            "category":self.get_category(),
            "icon":self.get_icon()
        }

Абстрактный блок (abstract_block.py)

Абстрактный блок определяет общую структуру блока: формат входа/выхода, способ обработки данных и поведение блока (например, режим агрегации). Пользователь должен создать наследника этого класса и реализовать логику в методе process_data.

С примерами использования блоков можно ознакомиться на странице: Примеры пользовательских реализаций в Python SDK

Код абстрактного блока

Важно

Особенности при разработке блока:
- get_info() — собирает и возвращает всю основную информацию о блоке в виде словаря
- process_data() — возвращает список с соответствующей глубиной вложенности
  - Итеративный режим (глубина вложенности=3):
    - 1 уровень - каждый элемент соответствует одной входящей записи
    - 2 уровень - каждый элемент соответствует одной исходящей записи. Набор элементов представляет собой ответ на входящую запись
    - 3 уровень - каждый элемент соответствует значению поля исходящей записи. Порядок и типы полей соответствуют описанию в output_variables
  - Аггрегационный режим (глубина вложенности=2, так как нет связи с входящими записями):
    - 1 уровень - каждый элемент соответствует одной результирующей исходящей записи
    - 2 уровень - каждый элемент соответствует значению поля исходящей записи. Порядок и типы полей соответствуют описанию в output_variables
- get_uuid() — возвращает уникальный идентификатор блока
- get_name() — возвращает варианты локализации имени блока в виде словаря
- get_type() — возвращает тип блока
- get_description() — возвращает локализованное описание блока в виде словаря
- get_compatible_connections() — возвращает список совместимых с блоком подключений. Эти подключения должны быть имплементациями абстрактного подключения и импортированы через секцию импорта
- get_fields() — возвращает строковое представление JavaScript описания полей пользовательских интеграций
- get_block_output_options() — возвращает список возможных конфигураций выходных полей
- get_block_aggr_mode() — возвращает булево значение: True — если блок работает в агрегирующем режиме, False — если в итеративном
- get_block_output() — Возвращает словарь со структурами выходных переменных автоматизации. Названия типов данных соответствуют типам данных Java
- get_block_input() — возвращает поля, которые возвращаются в результате вызова метода get_fields. Названия типов данных соответствуют типам данных Java

from abc import abstractmethod

class AbstractBlock():
    def __init__(self):
        pass

    @abstractmethod
    def get_uuid(self)->str:
        """
        Returns block's uuid
        """
        return None

    @abstractmethod
    def get_type(self)->str:
        """
        Returns block's type (default - "action")
        """
        return None

    @abstractmethod
    def get_name(self)->dict:
        """
        Returns block's name (dict struct)
        """
        return None

    @abstractmethod
    def get_description(self)->dict:
        """
        Returns block's description (dict struct)
        """
        return None

    @abstractmethod
    def get_compatible_connections(self)->list:
        """
        Returns block's list of compaible connections
        """
        return None

    @abstractmethod
    def get_optionals(self)->dict:
        """
        Returns block's optionals struct
        """
        return None

    @abstractmethod
    def get_fields(self):
        """
        Returns block's input fields in JS format
        """
        return None

    def get_info(self):
        """
        Returns block's system info output for --get-info command
        """
        return {
            "uuid":self.get_uuid(),
            "type":self.get_type(),
            "name":self.get_name(),
            "description":self.get_description(),
            "compatible_connections":self.get_compatible_connections(),
            "optionals":self.get_optionals(),
            "fields":self.get_fields()
        }

    @abstractmethod
    def get_block_input(self):
        """
        Returns block's input fields in Python dict format with Java data types
        """
        return None

    @abstractmethod
    def get_block_output(self, data_sample:dict):
        """
        Returns block's output fields configuration. Should be presented in `get_block_output_options`
        """
        return None

    @abstractmethod
    def get_block_aggr_mode(self, data_sample:dict)->bool:
        """
        Returns block's aggregation flag
        """
        return None

    @abstractmethod
    def get_block_output_options(self):
        """
        Returns block's output fields options list
        """
        return None

    @abstractmethod
    def process_data(self, **data):
        """
        Return processed data with user defined functions. Output data must follow `get_block_output` format
        """
        return None

    @abstractmethod
    def get_batch_size(self):
        """
        Returns block's batch size
        """
        return None

Абстрактное подключение (abstract_connection.py)

Абстрактный класс задает обязательную структуру подключения: UUID, имя, описание, набор опций и список полей. Пользовательские подключения наследуются от него и реализуют конкретные поля, необходимые для работы с API, файлами и прочими источниками.

С примерами использования подключений можно ознакомиться на странице: Примеры пользовательских реализаций в Python SDK

Код абстрактного подключения

Важно

Особенности при разработке подключения:
- get_info() — собирает и возвращает всю основную информацию о подключении в виде словаря
- get_uuid() — возвращает уникальный идентификатор подключения
- get_name() — возвращает варианты локализации имени подключения в виде словаря
- get_description() — возвращает локализованное описание подключения в виде словаря
- get_fields() — возвращает строковое представление JavaScript описания полей пользовательских интеграций
- get_connection_input() — возвращает поля, которые указаны в значении ключа fields. Названия типов данных соответствуют типам данных Java

from abc import abstractmethod

class AbstractConnection():
    def __init__(self):
        pass

    @abstractmethod
    def get_uuid(self):
        """
        Returns connection's uuid
        """
        return None

    @abstractmethod
    def get_name(self):
        """
        Returns connection's name (dict struct)
        """
        return None

    @abstractmethod
    def get_description(self):
        """
        Returns connection's description (dict struct)
        """
        return None

    @abstractmethod
    def get_optionals(self):
        """
        Returns connection's optionals struct
        """
        return None

    @abstractmethod
    def get_fields(self):
        """
        Returns connection's input fields in JS format
        """
        return None

    @abstractmethod
    def get_connection_input(self):
        """
        Returns connection's input fields in Python dict format with Java data types
        """
        return None

    def get_info(self) -> dict:
        """
        Returns connection's system info output for --get-info command
        """
        info_output =  {
            "uuid":self.get_uuid(),
            "name":self.get_name(),
            "description":self.get_description(),
            "optionals":self.get_optionals(),
            "fields":self.get_fields()
        }
        return info_output

Была ли статья полезна?

Да

Нет

Работа с расширением

Протоколы и режимы обработки данных