CDictionary

Основной класс для работы со справочниками.

Создает окружение и отправляет запросы на шину/API для создания, обновления, удаления и расчета справочника, а так же данных справочника.

Очистка класса

Необходимо вызвать очистку (метод .clear()) после завершения работы.

Инициализация

Доступно несколько вариантов инициализации класса.

Ускорение расчетов

Для ускорения расчетов желательно в самом справочнике указать все необходимые атрибуты.

Прямая инициализация

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

from src.service_dictionary import CDictionary

CDictionary(
    block_id: Optional[str] = None,
    user_id: Optional[str] = None,
    dictionary_id: Optional[str] = None,
    dictionary_type: Optional[Union[EDictionaryTypes, str]] = None,,
    revision_id: Optional[str] = None
)

- block_id - идентификатор блока справочника. - user_id - идентификатор пользователя. - dictionary_id - идентификатор справочника. Если не указывать, то ищется автоматически, исходя из block_id. Если по блоку будет найдено несколько справочников, то будет использован идентификатор первого найденного. - dictionary_type - тип справочника. Если не указывать, то ищется автоматически, исходя из block_id. - revision_id - идентификатор ревизии данных справочника. Если не указывать, то для работы с данными будет использована самая свежая ревизия.

Для опытных пользователей

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

• attributes: Optional[CAttributes] = None - атрибуты справочника. Если не указывать, то ищутся автоматически, исходя из dictionary_id.
• lazy_load: bool = False - флаг отложенной загрузки данных справочника. Если включен, то справочник не будет обновлять данные при расчете блока.
• binding: Optional[Dict] = None - привязки атрибутов справочника.
• specific_params: Optional[Dict] = None - специфические параметры, необходимые для расчета справочника.

Альтернативный способ инициализации справочника

execution_context.create_dictionary_instance(
    dictionary_id: str,
    revision: Optional[str] = None,
    blockid: Optional[str] = None,
    dictionary_type: Optional[str] = None
) -> CDictionary

В качестве пользователя справочника здесь будет указан пользователь, запустивший блок Python на исполнение

Инициализация из данных входа

Данный тип инициализации самостоятельно обрабатывает вход и создает класс справочника.

Аналогично методу create_dictionary_instance, В качестве пользователя справочника здесь будет указан пользователь, запустивший блок Python на исполнение

execution_context.create_dictionary_from_input(
    input_data: Dict
)-> CDictionary

• input_data - входные данные из метода execution_context.get_input_by_id !!! warning "Важно" Для корректной передачи данных необходимо прописать параметр raw_data=True

Параметры класса

• block_id: Optional[str] - Идентификатор блока, в котором создан справочник
• user_id: Optional[str] - Идентификатор пользователя, для которого создан справочник
• dictionary_id: str - Идентификатор справочника
• dictionary_type: EDictionaryTypes - Тип справочника
• attributes: CAttributes - Список атрибутов справочника
• binding: Dict - Словарь с привязками полей справочника
• lazy_load: bool - Флаг ленивой (отложенной) загрузки данных справочника
• dictionary_id: Optional[str] - Идентификатор справочника
• revision_id: Optional[str] - Идентификатор ревизии данных справочника
• specific_params: Dict - Специфические параметры для инициализации конкретного типа справочника
• hierarchy: Optional[CDictionaryHierarchyManager] - Иерархии справочника

Методы

serialize

Сериализация описания справочника в словарь.

serialize(self) -> Dict

Пример справочника

{
    "dictionary_id",
    "dictionary_type",
    "revision_id",
    "block_id",
    "user_id",
    "binding",
    "lazy_load",
    "specific_params"
}

clear

Очистка класса справочника, для его корректной обработки сборщиком мусора.

clear(self) -> None

invalidate_cache

Инвалидация кеша справочника.

invalidate_cache(self, by_block: bool = False) -> None

Работа с данными

get_data

Получение рассчитанных данных справочника. Если в справочнике есть иерархия - придут иерархические данные.

get_data(
    limit: Optional[int] = None,    
    offset: Optional[int] = None,
    get_by_block: bool = False,
    selected_fields: Optional[List[str]] = None
) -> CDictionaryElements

• limit - количество объектов.
• offset - сдвиг объектов.
• get_by_block - получение данных по идентификатору блока.
• selected_fields - массив полей, которые необходимо отобразить. !!! warning "Пустой массив" Для отображения всех элементов требуется передать параметру значение None. Пустой массив [] означает, что не будет выбрано ни одного элемента.

get_origin_data

Получение данных справочника без иерархий.

get_origin_data(
    limit: Optional[int] = None,    
    offset: Optional[int] = None,
    get_by_block: bool = False,
    selected_fields: Optional[List[str]] = None
) -> CDictionaryElements

• limit - количество объектов.
• offset - сдвиг объектов.
• get_by_block - получение данных по идентификатору блока.
• selected_fields - массив полей, которые необходимо отобразить. !!! warning "Пустой массив" Для отображения всех элементов требуется передать параметру значение None. Пустой массив [] означает, что не будет выбрано ни одного элемента.

get_old_format_data

Получение данных справочника в устаревшем формате.

get_old_format_data(
    limit: Optional[int] = None,    
    offset: Optional[int] = None,
    skip_missing_revision: bool = False,
    flatten: bool = False,
    update_metadata_cache: bool = True
) -> List[Dict]

• limit - количество объектов.
• offset - сдвиг объектов.
• skip_missing_revision - флаг пропуска ошибки не найденной ревизии. В случае отсутствия нужной ревизии будут взяты данные на самую свежую ревизию.
• flatten - получение данных без иерархий (плоский список).
• update_metadata_cache - флаг обновления кеша метаданных.

get_filter_data

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

get_filter_data(
    filter_params: List[Dict],
    limit: Optional[int] = None,    
    offset: Optional[int] = None,
    get_by_block: bool = False,
    selected_fields: Optional[List[str]] = None
) -> CDictionaryElements

• filter_params - параметры фильтра. Формат: [{"key": <key>, "eq": <eq>, "vl": <vl>}]
  • <key> - ключ атрибута, по которому производится фильтрация;
  • <eq> - условие фильтрации. На текущий момент реализованы следующие условия:
    • == - равно;
    • != - не равно;
    • in - входит в массив;
    • not in - не входит в массив;
    • < -меньше;
    • <= - меньше или равно;
    • >- больше;
    • >= - больше или равно.
  • <vl> - значения ключа для фильтра.
  • Для корректной передачи массивов необходимо использовать in/not in
• limit - количество объектов;
• offset - сдвиг объектов;
• get_by_block - получение данных по идентификатору блока;
• selected_fields - массив полей, которые необходимо отобразить. !!! warning "Пустой массив" Для отображения всех элементов требуется передать параметру значение None. Пустой массив [] означает, что не будет выбрано ни одного элемента.

Ревизии (дельтами)

get_last_delta

Получение последней созданной ревизии для справочника. Если ревизии отсутствуют - возвращается None.

get_last_delta() -> Optional[str]

get_all_deltas

Получение списка всех ревизий для справочника.

get_all_deltas() -> List[Dict]

Формат ответа

[
      {
        "revision": "<идентификатор ревизии>",
        "prev_revision": "<идентификатор предыдущей ревизии>",
        "delta": {
          "insert": "<Количество добавленных элементов>",
          "update": "<Количество измененных элементов>",
          "delete": "<Количество удаленных элементов>"
        }
     }
]

get_revision_history

Получение списка ревизий от начальной (созданной при создании справочника) до текущей (указывается в параметрах класса).

get_revision_history() -> List[Dict]

Формат ответа

[
      {
        "revision": "<идентификатор ревизии>",
        "prev_revision": "<идентификатор предыдущей ревизии>",
        "delta": {
          "insert": "<Количество добавленных элементов>",
          "update": "<Количество измененных элементов>",
          "delete": "<Количество удаленных элементов>"
        }
     }
]

save_delta

Сохранение дельты справочника и создания новой ревизии от текущей (указывается в параметрах класса).

save_delta(        
    delta: Optional[Dict[str, List]] = None,
    insert: Optional[List] = None,
    update: Optional[List] = None,
    delete: Optional[List] = None,
    update_revision: bool = False
) -> Optional[str]

Данные в самом справочнике не будут затронуты изменениями. В ответе придет идентификатор созданной ревизии.

Ревизии уникальны для блока, создающего их, и идентификатора предыдущей ревизии, то есть, в случае, если один блок будет пытаться сохранить несколько ревизий от одной и той же, то результатом будет одна ревизия, сохраненная последней (остальные данные будут затерты).

• delta - Словарь с изменениями данных, формата {<insert>, <update>, <delete>} <insert>, <update>, <delete> являются массивами, содержащими словари формата: {"keys": {<id>: <value>}, "value": {<id>: <value>}}
• • keys - словарь ключей (атрибутов, у которых параметр primary_key=1);
  • value - словарь всех атрибутов (в том числе и ключей);
    • <id> - идентификатор атрибута;
    • <value> - значение атрибута.

• insert - Массив с данными для добавления.

• update - Массив с данными для обновления.

• delete - Массив с данными для удаления.

  insert, update, delete

  Данные поля служат облегченным способом сохранения дельты. Формат словарей аналогичен формату в параметре delta, однако у этих полей более высокий приоритет заполнения, т.е. значения этих полей будут перетирать аналогичное значение в параметре delta

• update_revision - Флаг автоматического обновления ревизии справочника. С помощью этого флага можно сразу получать данные по сохраненной ревизии.

  Пример использования флага

  # Создаем новую ревизию
  new_revision_id = dictionary.save_delta(delta, update_revision=True)
  # Получаем данные
  result_data = dictionary.get_data().to_json()
  

where

Создание новой ревизии по условию

where(
    condition: List[Dict], 
    update_revision: bool = False
) -> Optional[str]:

• condition - условие выборки данных. Формат: [{"key": <key>, "eq": <eq>, "vl": <vl>}] (аналогичен методу get_filter_data)

  • <key> - ключ атрибута, по которому производится фильтрация;
  • <eq> - условие фильтрации. На текущий момент реализованы следующие условия:
    • == - равно;
    • != - не равно;
    • in - входит в массив;
    • not in - не входит в массив;
    • < -меньше;
    • <= - меньше или равно;
    • >- больше;
    • >= - больше или равно.
  • <vl> - значения ключа для фильтра.
  • Для корректной передачи массивов необходимо использовать in/not in

• update_revision - Флаг автоматического обновления ревизии справочника. С помощью этого флага можно сразу получать данные по сохраненной ревизии.

  Пример использования флага

  # Создаем новую ревизию
  new_revision_id = dictionary.where(condition, update_revision=True)
  # Получаем данные
  result_data = dictionary.get_data().to_json()
  

Работа с потоковым справочником

Следующие методы работают только с потоковым справочником

load_stream_data

Загрузка (добавление, обновление или удаление) элементов в потоковый справочник.

load_stream_data(insert: List, update: List, delete: List) -> Dict

После загрузки элементов, все ревизии справочника будут удалены (т.к. данные справочника были изменены).

• insert: Массив словарей с добавленными элементами, формат: {"keys": {<id>: <value>}, "value": {<id>: <value>}}
  • keys - словарь ключей (атрибутов, у которых параметр primary_key=1);
  • value - словарь всех атрибутов (в том числе и ключей);
  • <id> - идентификатор атрибута;
  • <value> - значение атрибута.
• update: Массив словарей с обновленными элементами, формат аналогичен insert.
• delete: Массив словарей с удаленными элементами, формат аналогичен insert.

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

Пример возвращаемого значения

{
    "insert": <Массив со значениями 0/1, 0 - если сохранение успешно, 1 - если нет.>
    "update": <Массив со значениями 0/1, 0 - если сохранение успешно, 1 - если нет.>,
    "delete": <Массив со значениями 0/1, 0 - если сохранение успешно, 1 - если нет.>
}

clear_stream_data

Очистка потокового справочника от данных.

clear_stream_data() -> bool

Все ревизии, если они были, будут так же удалены. Результат работы - флаг успешности очистки.