Metadata-Version: 2.4
Name: pymrs
Version: 0.3.6
Summary: Python SDK for MRS.
Author-email: Artyom Tyurin <arty@search-centric.ru>
Maintainer-email: Artyom Tyurin <arty@search-centric.ru>
License: BSD Zero Clause License
        
        Copyright (c) 2024 Search Centric LLC
        
        Permission to use, copy, modify, and/or distribute this software for any
        purpose with or without fee is hereby granted.
        
        THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
        REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
        AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
        INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
        LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
        OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
        PERFORMANCE OF THIS SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Проект библиотеки MRS REST API для Python.

## Установка

Данный пакет устанавливается через PIP. 

```shell
pip install pymrs
```

## Назначение:

Библиотека на языке Python для унифицированного использования REST API программного комплекса Memoza Rest Server (MRS). Основное применение - это создание программ и скриптов для обслуживания данных MRS, учитывая особености и требования многочисленных пользователей.
Для возможности работы с WRS в рамках модуля имплементированы классы AsyncMRSClient, MRSClient, Query и DataIterator. Все классы имеют возможность использования при мэнеджменте контекста.

## Класс AsyncMRSClient

AsyncMRSClient это основной класс, предназначенный для создания клиентской сессии и отправления запросов на сервер. При помощи него отправляются запросы во всех классах, реализованных в данном модуле. Инициализируется именем хоста (URL сервера MRS, на который будут отправляться запросы), токеном, именем пользователя и либо паролем, либо уже выданным тикетом.

### Методы класса

| Имя метода | Описание метода |
|-----------------------|-------------|
| `_authenticate()` | Аутентифицирует пользователя при помощи данных, заданных при инициализации, получая тикет для дальнейших запросов. |
| `validate_ticket()` | Проверяет валидность тикета, при необходимости запрашивает новый. |
| `close()` | Отправляет запрос на сервер для прекращения связи. |
| `_handle_error()` | Метод используется для обработки ошибок при отправлении запросов, поднимает ошибку `MRSClientError` с кодом ошибки и сообщением, полученным от сервера. |
| `request()` | Метод, при помощи которого отправляются запросы. |
| `get_all_namespaces()` | Метод, который возвращает список всех пространств имен, хранимых на сервере. |
| `get_namespace()` | Метод, который возвращает данные о метаклассах, хранящихся в рамках конкретного пространства имен. |
| `get_datatype()` | Метод, который возвращает данные о метаклассе, хранящегося в рамках конкретного пространства имен. |
| `es_request()` | Метод для отправки запроса Elasticsearch с возможностью фильтрации по ролям при необходимости. |
| `get_user_roles()` | Метод для получения информации о ролях пользователей в рамках конкретного пространства имен. |
| `upload_file()` | Метод для загрузки файлов на сервер. |

### Свойства класса

| Имя свойства | Описание |
|--------------|-------------|
| `headers` | При вызове данное свойство возвращает HTTP заголовки, хранящиеся в существующей сессии. |
| `ticket` | При вызове данное свойство возвращает тикет, хранящийся в существующей сессии. |
---

## Класс MRSClient

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

## Класс Query

Класс Query является классом, который используется для сборки и отправки поисковых запросов. Иницииализируется сессией AsyncMRSClient и пространством имен, в котором будет производиться поиск.

### Методы класса

| Имя метода | Описание метода |
|-----------------------|-------------|
| `assemble_query()` | Собирает запрос, на основании параметров для поисках, заданных в качестве атрибутов класса. |
| `close_scroll()` | Метод, который используется для закрытия скроллинга. |
| `get_records()` | Метод, используемый для получения результатов поискового запроса с возможностью получения результа запроса в виде итератора. |
| `get_entities()` | Возвращает список сущностей, хранимых в рамках конкретного класса. |
| `get_content()` | Возвращает содержимое конкретной сущности. |
| `register_entities()` | Регистрирует список новых сущностей в указанном пространстве имен. Позволяет автоматически генерировать URI, если они не предоставлены. Обрабатывает сущности пакетами. |
| `patch_entities()` | Обновляет указанные свойства для списка существующих сущностей в указанном пространстве имен. Требует URI для каждой сущности. Обрабатывает сущности пакетами. |

### Свойства класса

| Имя свойства | Описание |
|-----------------------|-------------|
| `url` | При вызове данное свойство возвращает ссылку для отправки запроса. |
| `data` | При вызове данное свойство возвращает собранный поисковый запрос. |

## Класс DataIterator

Данный класс является итерируемым контейнером данных, полученных в результате поискового запроса метода Query.get_records().
