SnakeCat - ctypes-обертка для irbis64_client.dll

Введение. Установка. Примеры программ

Введение

Пакет snakecat представляет легкую обертку над irbis64_client.dll на основе ctypes и предназначен для создания клиентских приложений для системы автоматизации библиотек ИРБИС64 на языке Python.

Успешно работает на 32-битных и 64-битных версиях операционных систем Windows, а именно: Windows Vista/7/8/10. Работа на других версиях Windows, а именно: Windows 95/98/ME/NT не гарантируется.

Поддерживается интерпретатор CPython версий, начиная с 3.6. Другие интерпретаторы, например, IronPython, не тестировались и работоспособность пакета под ними не гарантируется.

Поддерживаются сервер ИРБИС64, начиная с версии 2014. Более ранние версии сервера ИРБИС64 не тестировались и работоспособность пакета под ними не гарантируется.

Основные возможности пакета:

  • Поиск и расформатирование записей.

  • Создание и модификация записей, сохранение записей в базе данных на сервере.

  • Работа с поисковым словарем: просмотр терминов и постингов.

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

Установка

snakecat загружен в централизованный репозиторий пакетов PyPI, поэтому можно установить его с помощью стандартного клиента pip, входящего в поставку Python:

pip install snakecat --user --upgrade

Здесь --user означает установку только для текущего пользователя (без этого ключа установка будет выполняться для всех пользователей и может потребовать администраторских прав), а --upgrade - обновление пакета при необходимости. Если уже установлена последняя версия пакета, то pip просто сообщит об этом и завершит работу.

Также можно установить пакет, скачав необходимые файлы с репозитория GitHub: https://github.com/amironov73/snakecat

Кроме того, доступны ночные dist-сборки на AppVeyor: https://ci.appveyor.com/project/AlexeyMironov/snakecat/build/artifacts

Режимы работы клиента

irbis64_client.dll имеет несколько режимов работы.

Во-первых, клиент может обращаться к серверу по нативному протоколу ИРБИС64 (этот режим используется по умолчанию) либо через Web-шлюз (этот режим включается вызовом IC_set_webserver(1)).

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

Бегущий ирбис

Для неинтерактивных скриптов такое поведение нежелательно, поэтому клиент можно переключить в блокирующий режим сокетов c помощью вызова IC_set_blocksocket(1).

Заметьте, переключение режима клиента должно выполняться до выполнения подключения к серверу!

Примеры программ

Ниже прилагается пример простой программы. В каталог находятся и загружаются 10 первых библиографических записей, в которых автором является А. С. Пушкин. Показано нахождение значения поля с заданным тегом и подполя с заданным кодом. Также показано расформатирование записи в формат brief.

import sys
import snakecat as irbis

# Устанавливаем блокирующий режим сокета,
# чтобы не появлялось ненужное окно
irbis.hide_window()

# данные для подключения к серверу
HOST = '127.0.0.1'
PORT = '6666'
ARM = 'C'
USER = 'librarian'
PASSWORD = 'secret'
DB = 'IBIS'

# Подключение к серверу
rc, ini = irbis.connect(HOST, PORT, ARM, USER, PASSWORD)
print('connect=', rc)
if rc < 0:
    print(irbis.error_to_string(rc))
    print('EXIT')
    sys.exit(1)

# Поиск записей
print()
_, found = irbis.search(DB, '"K=ПУШКИН$"')
print('Найдено записей:', len(found))

# Чтобы не распечатывать все найденные записи, отберем только 10 первых
for mfn in found[:10]:

    # Получаем запись из базы данных
    _, record = irbis.read_record(DB, mfn)
    title = irbis.fm(record, 200, 'a')
    print('Заглавие:', title)

    # Форматирование записи
    _, description = irbis.format_record(DB, mfn, '@brief')
    print('Биб. описание:', description)

    print()  # Добавляем пустую строку

# Отключение от сервера
print()
rc = irbis.disconnect(USER)
print('disconnect=', rc)

Высокоуровневые функции

Подключение и отключение

connect(host: str, port: str, arm: str, user: str, password: str) -> Tuple[int, str]

Подключение к серверу – регистрация клиента на сервере.

  • host - адрес сервера в числовом виде (например 192.168.5.140).

  • port - рабочий порт сервера (чаще всего 6666).

  • arm - тип клиента: IRBIS_READER, IRBIS_CATALOG и т. д.

  • user - имя пользователя, зарегистрированного на сервере.

  • password - пароль пользователя.

Функция возвращает кортеж “код возврата, содержимое INI-файла”.

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

disconnect(user: str) -> int

Отключение от сервера – разрегистрация клиента на сервере, сигнал об окончании работы.

  • user - имя пользователя, ранее выполнившего вход на сервер.

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

is_busy() -> bool

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

Возвращает True, если в настоящий момент выполняется клиентский запрос, иначе False.

Настройка клиента

hide_window() -> None

Прячем надоедливое окно, переходя в блокирующий режим сокетов.

use_web_gateway(cgi: Optional[str] = None) -> int

Установка режима работы через Web-шлюз.

  • cgi - путь к шлюзу (по умолчанию /cgi-bin/wwwirbis.exe).

Функции работы с ресурсами

read_file(database: Optional[str], file_name: str, path: int = DBNPATH2) -> Tuple[int, str]

Чтение текстового файла с сервера.

  • database - имя базы данных (не используется для путей SYSPATH и DATAPATH).

  • file_name - имя требуемого текстового файла (ресурса) с расширением.

  • path - код, определяющий относительный путь раземещения ресурса на сервере (см. ниже).

Коды путей:

  • SYSPATH – общесистемный путь (т.е. там, где размещается собственно исполняемый модуль сервера C:\irbis64\).

  • DATAPATH – путь, где размещаются сведения о базах данных (C:\irbis64\datai\).

  • DBNPATH2 – путь, где размещается собственно база данных (C:\irbis64\datai\ibis\);

  • DBNPATH3 - путь, где размещается собственно база данных;

  • DBNPATH10 - путь, где размещается собственно база данных.

Функция возвращает кортеж “код возврата, содержимое файла”. Файл ожидается в кодировке ANSI.

write_file(database: Optional[str], file_name: str, content: str, path: int = DBNPATH2) -> int

Запись текстового файла на сервер.

  • database - имя базы данных (не используется для путей SYSPATH и DATAPATH).

  • file_name - имя текстового файла (ресурса) с расширением.

  • content - содержимое файла.

  • path - код, определяющий относительный путь раземещения ресурса на сервере (см. ниже).

clear_cache() -> int

Очистка локального кэша форматов, меню и прочих ресурсов, прочитанных с сервера.

В результате выполнения функции очищается кэш, в котором сохраняются запрошенные текстовые ресурсы (после чего при их запросе они берутся с сервера). При выполнении функции не производится обращение на сервер.

Низкоуровневые функции

Функции общего назначения

IC_reg(host: c_char_p, port: c_char_p, arm: c_char, username: c_char_p, password: c_char_p, answer: POINTER(c_char_p), answer_size: c_int) -> c_int

Регистрация клиента на сервере.

  • host - адрес сервера в числовом виде (например 192.168.5.140).

  • port - рабочий порт сервера (6666).

  • arm - тип клиента.

  • username - имя пользователя, зарегистрированного на сервере.

  • password - пароль пользователя.

  • answer - выходной буфер для возвращаемых данных.

  • answer_size - размер выходного буфера в байтах.

IC_unreg(username: c_char_p) -> c_int

Раз-регистрация клиента на сервере (сигнал об окончании работы).

  • username - имя пользователя, использованное при регистрации на сервере.

IC_set_client_time_live(interval: c_int) -> c_int

Установка интервала подтверждения.

  • interval - интервал в минутах.

IC_set_show_waiting(interval: c_int) -> c_int

Установка времени появления заставки ожидания.

  • interval - интервал в секундах.

IC_set_webserver(option: c_int) -> c_int

Установка режима работы через Web-шлюз.

  • option - включение (1) или выключение (0) режима работы через Web-шлюз.

IC_set_webcgi(cgi: c_char_p) -> c_int

Установка имени шлюза при работе через Web-шлюз.

  • cgi - имя шлюза (по умолчанию - /cgi-bin/wwwirbis.exe).

IC_set_blocksocket(opt: c_int) -> c_int

Установка режима ожидания ответа от сервера.

  • opt - включение (1) или выключение (0) режима блокирующего ожидания ответа от сервера. По умолчанию блокирующий режим выключен.

IC_isbusy() -> c_int

Определение завершения очередного обращения к серверу.

Код возврата: 1 - выполняется запрос к серверу, 0 - обращение к серверу завершено.

Функции для работы с ресурсами

IC_update_ini(ini_file: c_char_p) -> c_int

Обновление INI-файла – профиля пользователя на сервере.

  • ini_file - набор измененных строк в виде структуры INI-файла (в ANSI-кодировке).

IC_getresourse

Чтение текстового ресурса (файла).

IC_clearresourse

Очистка памяти кэша.

В результате выполнения функции очищается кэш, в котором сохраняются запрошенные текстовые ресурсы (после чего при их запросе они берутся с сервера). При выполнении функции не производится обращение на сервер.

IC_getresoursegroup

Групповое чтение текстовых ресурсов.

IC_getbinaryresourse

Чтение двоичного ресурса.

IC_putresourse

Запись текстового ресурса на сервер.

Функции для работы с мастер-файлом базы данных

IC_read

Чтение записи.

IC_readformat

Чтение записи с расформатированием.

IC_update

Сохранение/обновление записи в базе данных.

IC_updategroup

Групповое сохранение/обновление записей в базе данных.

IC_runlock

Разблокирование записи на сервере.

IC_ifupdate

Актуализация записи.

IC_maxmfn

Получение максимального MFN базы данных.

Функции для работы с записью

IC_fieldn

Определение порядкового номера поля в записи.

IC_field

Чтение заданного поля/подполя.

IC_fldadd

Добавление поля в запись.

IC_fldrep

Замена поля.

IC_nfields

Определение количества полей в записи.

IC_nocc

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

IC_fldtag

Определение метки поля с заданным порядковым номером.

IC_fldempty

Опустошение записи (локально).

IC_changemfn

Изменение MFN записи (локально).

IC_recdel

Установка признака логически удаленной записи (локально).

IC_recundel

Снятие признака логически удаленной записи (локально).

IC_recunlock

Снятие признака блокировки записи (локально).

IC_getmfn

Чтение MFN записи.

IC_recdummy

Создание пустую запись (локально).

IC_isactualized

Чтение в статусе записи признака актуализации.

IC_islocked

Чтение в статусе записи признака блокировки.

IC_isdeleted

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

Функции для работы со словарем базы данных

IC_nexttrm

Получение списка терминов словаря, начиная с заданного.

IC_nexttrmgroup

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

IC_prevtrm

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

IC_prevtrmgroup

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

IC_posting

Получение списка ссылок для заданного термина.

IC_postinggroup

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

IC_postingformat

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

Функции поиска

IC_search

Прямой (по словарю) поиск записей по заданному поисковому выражению.

IC_searchscan

Последовательный поиск по результату прямого поиска и/или по заданному диапазону записей.

Функции форматирования

IC_sformat

Расформатирование записи, заданной по номеру (mfn).

IC_record_sformat

Расформатирование записи в клиентском представлении.

IC_sformatgroup

Расформатирование группы записей.

Функции пакетной обработки

IC_print

Формирование выходной табличной формы.

IC_stat

Формирование выходной формы в виде статистических распределений.

IC_gbl

Выполнение задания на глобальную корректировку.

Функции администратора

IC_adm_restartserver

Перезапуск сервера ИРБИС64.

IC_adm_getdeletedlist

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

IC_adm_getalldeletedlists

Получение общих сведений о базе данных: списки удаленных/заблокированных/неактуализированных записей, максимальный MFN и признак монопольной блокировки базы.

IC_adm_dbempty

Опустошение базы данных.

IC_adm_dbdelete

Удаление базы данных.

IC_adm_newdb

Создание новой базы данных электронного каталога.

IC_adm_dbunlock

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

IC_adm_dbunlockmfn

Снятие блокировки заданных записей.

IC_adm_dbstartcreatedictionry

Создание словаря базы данных заново.

IC_adm_dbstartreorgdictionry

Реорганизация словаря базы данных.

IC_adm_dbstartreorgmaster

Реорганизация файла документов базы данных.

IC_adm_getclientlist

Получение списка зарегистрированных (текущих) клиентов.

IC_adm_getclientslist

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

IC_adm_getprocesslist

Получение списка запущенных процессов на сервере.

IC_adm_setclientslist

Обновление списка клиентов для доступа к серверу.

Вспомогательные функции

IC_nooperation() -> c_int

Подтверждение регистрации.

IC_getposting(c_char_p, c_int) -> c_int

Получить элемент исходной ссылки.

IC_reset_delim(c_char_p) -> c_char_p

Заменить реальные разделители строк $0D0A на псевдоразделители $3130.

IC_delim_reset(c_char_p) -> c_char_p

Заменить псевдоразделители $3130 на реальные разделители строк $0D0A.

Служебные функции

from_ansi(buffer: Optional[bytes]) -> str

Конвертация буфера ctypes в обычную строку.

from_utf(buffer: Optional[bytes]) -> str

Конвертация буфера ctypes в обычную строку.

to_ansi(text: Optional[str]) -> bytes

Конвертация строки в байты в кодировке ANSI.

to_utf(text: Optional[str]) -> bytes

Конвертация строки в байты в кодировке UTF-8.

from_irbis(text: bytes) -> bytes

Замена псевдоразделителей строк на настоящие разделители.

to_irbis(text: bytes) -> bytes

Замена разделителей строк на псевдоразделители.

def error_to_string(ret_code: int) -> str

Получение текстового сообщения об ошибке по ее коду.