Python-интерфейс для работы с данными системы¶
Содержание
Для доступа к данным системы из сторонних python-приложений можно использовать модуль netdbclient.py
Модуль предоставляет доступ к данным NetDB — чтение и запись данных из/в реестры и отчеты:
>>> from netdbclient import Connection
>>> conn = Connection ( 'http://netdb.server.ru' , 'api_key' )
>>> print ( conn.get(300) )
[['1', '2'], ['3', '4'], ['229', '321'], ['333', '12']]
>>>
Используется сервис NetDB XML API, преобразования в xml и обратно выполняются автоматически.
Авторизация¶
В качестве ключа для доступа к NetDB используется api_key (см раздел Компонент «XML API»). Все операции будут выполняться от имени этого пользователя.
Начало работы¶
Перед началом работы необходимо иметь следующую информацию:
- url сервера NetDB, например http://netdb.server.ru.
- api_key пользователя на этом сервере.
Все операции выполняются через netdbclient.Connection (которое на самом деле просто хранит параметры доступа и не поддерживает постоянного соединения с сервером):
>>> from netdbclient import Connection
>>> conn = Connection ( 'http://netdb.server.ru' , 'api_key' )
Первый аргумент — url, второй — api_key.
Полное описание интерфейса¶
Модуль netdbclient полностью независим и использует только стандартные библиотеки Python.
class Connection¶
- class Connection
- Объекты этого класса хранят параметры доступа к серверу NetDB. Инициализируются вызовом:
- Connection ( url , api_key , **request_kwargs )
где:
url: адрес сервера NetDB, строка, например http://netdb.server.ru. api_key: ключ доступа, строка. kwargs: дополнительные параметры для urllib.request.Request хранятся как атрибуты объекта.
методы:
- get ( report_id , params=None )
где:
report_id: идентификатор отчета или реестра, целое число, params: список значений параметров для отчета. возвращает объект класса Response (см. ниже)
Примечание
значения параметров в params должны следовать в том же порядке, что и параметры при просмотре отчета.
- put ( data , report_id , params=None )
где:
data: данные для записи, список списков, каждый список report_id: идентификатор формы или реестра, целое число, params: список значений параметров для отчета. возвращает tuple из трех элементов — количество измененных, созданных и удаленных записей соответственно.
- blocks
- кэшируемый список всех блоков (Block) данных системы (может вернуть None если на сервере еще не посчиталось, надо подождать и повторить).
- descriptors
- кэшируемый словарь (по идентификатору) описаний показателей (Descriptor).
- descriptors_by_name
- кэшируемый словарь (по названию) описаний показателей (Descriptor).
- create_descriptor ( name , type , choice=None , related=None , groups=None )
Создает новый показатель
name: название type: название или код типа (из descriptor_types) choice: название или id спраавочника если соответствующий тип related: список названий или идентификаторов аналитических признаков groups: список идентификаторов элементов из «Группы показателей» или их названий. - forms, sets, reports, registries
- кэшируемые словари (по идентификатору) соответственно форм, справочников, отчетов, реестров.
- forms_by_name, sets_by_name, reports_by_name, registries_by_name
- кэшируемые словари (по названию) соответственно форм, справочников, отчетов, реестров.
- reset ()
- Обновляет кэшированные значения (блоки, формы справочники, отчеты и реестры).
- reset_sets ()
- Аналогично reset без блоков.
- reset_blocks ()
- Обновляет список блоков (фактически делает запрос на вычисление).
- delete_objects ( ids )
- Удаляет объекты из системы
- create_objects ( data )
Создает новые объекты. Возвращает список созданных.
data: список словарей descriptor -> значение - update_objects ( data )
Изменяет объекты
data: словарь идентификатор -> словарь descriptor -> значение - create_set ( name )
Создает новый справочник с заданным именем
name: имя справочника - delete_from_set ( id_or_name , ids )
Удаляет из справочника заданные объекты (только из справочника)
id_or_name: идентификатор (целое) или название справочника ids: список идентификаторов объектов - add_to_set ( id_or_name , ids )
Добавляет в справочник заданные объекты
id_or_name: идентификатор (целое) или название справочника ids: список идентификаторов объектов - get_set ( id_or_name , format=“pandas“ )
Возвращает содержимое справочника.
id_or_name: идентификатор (целое) или название справочника format: pandas или raw. raw содержит больше информации (загруженный json).
get_report ( id_or_name , params=None , format=“pandas“ ) get_form ( id_or_name , params=None , format=“pandas“ ) get_registry ( id_or_name , params=None , format=“pandas“ )
Возвращают содержимое отчета/формы/реестра соответственно
id_or_name: идентификатор (целое) или название отчета params: Словарь id_or_name-показателя -> значение-параметра format: pandas или raw. raw содержит больше информации (загруженный json).
get_report_parameters ( id_or_name , format=“pandas“ ) get_form_parameters ( id_or_name , format=“pandas“ ) get_registry_parameters ( id_or_name , format=“pandas“ )
Выдает список доступных параметров для отчета/формы/реестра
- get_block ( block_or_descrs_list , format=“pandas“ , extra_descrs_list=None , from_set=None )
ПВозвращает содержимое блока данных или реестра по заданным показателям:
block_or_descrs_list: блок (Block) из списка blocks или список идентификаторов или названий обязательных показателей. extra_descrs_list: список идентификаторов или названий необязательных показателей (игнорируется если задан блок) from_set: идентификатор или название множества. Ограничивает множество рассматриваемых объектов заданным. Игнорируется если задан блок (используется значение из его описания).
class Response¶
- class Response
внутренний класс модуля netdbclient, производный от list. Хранит результат запроса в виде списка списков значений в строках отчета. Дополнительные свойства:
code: код результата запроса ( 200 = ОК ) xml: строка, оригинальный ответ сервера, tree: xml.etree.ElementTree.Element, разобранная строка ответа, params: список значений параметров из ответа сервера (при успешном выполнении запроса). Если запрос завершился неудачно — список пуст, code содержит код ошибки, а xml и tree детальную информацию.
class Set¶
- class Set
- Именовнный кортеж с полями id и name, хранит информацию о справочнике, реестре, форме или отчете.
class Block¶
- class Block
- Именовнный кортеж с полями descriptors, related_descriptors, set_id, total, хранит информацию о блоке данных.
class Descriptor¶
- class Descriptor
- Именовнный кортеж с полями id, model, name, type, related_descriptors, choice, auto, description, ignored_in_calculations, хранит информацию о показателе.
Преобразования периодов¶
- period ( datetime , type )
Период по дате-времени и типу
datetime: дата-время, начало периода type: строка, тип, одна из: „day“, „week“, „decade“, „month“, „quarter“, „3 quarters“, „halfyear“, „year“, „день“, „неделя“, „декада“, „месяц“, „квартал“, „3 квартала“, „полугодие“, „год“ - rperiod ( offset , type )
Относительный период (сдвиг), на количество типов
offset: целое, количество элементов type: строка, тип, одна из: „day“, „week“, „decade“, „month“, „quarter“, „3 quarters“, „halfyear“, „year“, „день“, „неделя“, „декада“, „месяц“, „квартал“, „3 квартала“, „полугодие“, „год“
Типы показателей¶
descriptor_types - словарь - название типа -> идентификатор