**Dynamix Python SDK** предоставляет удобный интерфейс для интеграции взаимодействия с API **Dynamix Enterprise** в программный код на языке Python.
**Примечание:** проект находится в стадии активной разработки, [доступный функционал](#доступный-функционал) будет расширяться с каждой новой версией.
## Системные требования
### Соответствие версий платформы версиям SDK
| Версия платформы | Версия SDK |
| --- | --- |
| 4.2.0 | 1.0.x |
### Зависимости
Зависимости указаны в конфигурационном файле проекта [pyproject.toml](/pyproject.toml):
- версия Python: раздел `[project]`, ключ `requires-python`
- библиотеки: раздел `[project]`, ключ `dependencies`
**Важно:** использование более поздних версий Python и/или библиотек допустимо, но работоспособность не гарантируется, так как зависит от обратной совместимости с указанными версиями.
## Установка
Установка с помощью системы управления пакетами Python (pip), где `version` - тег с номером версии SDK (см. доступные теги в репозитории):
**Важно:** отключение проверки сертификата SSL даёт возможность произвести атаку типа MitM, поэтому пользоваться данной возможостью допустимо только в защищённой среде.
```python
import urllib3
from dynamix_sdk import Dynamix, DECS3OAuth, BVSAuth
urllib3.disable_warnings() # отключение вывода предупреждений безопасности SSL
Тип данных, возвращаемый функцией API SDK зависит от типа данных, возвращаемого соответствующей функцией API платформы.
Если функция API платформы возвращает структуру данных в виде набора пар ключ/значение (с заранее известными ключами), то функция API SDK возвращает модель Pydantic, которая описывает эту структуру.
Некоторые поля моделей автоматически генерируются на основе полученных данных от API платформы.<br>
Например, при наличии в модели поля, содержащего временную метку (timestamp), для удобства генерируется поле, содержащее дату и время в виде `datetime`.
Если функция API платформы возвращает примитивный тип данных (строка, число), то функция API SDK возвращает экземпляр класса, наследуемый от класса этого типа данных.
<details><summary>Класс, наследуемый от примитивного типа данных</summary>
Исключением является булев тип данных. Так как наследование от класса `bool` в Python недопустимо, функция API SDK возвращает экземпляр класса, который обладает функциональностью для использования в булевых выражениях (реализован метод `__bool__`), но само булево значение хранится в атрибуте `value`:
<details><summary>Класс с булевым значением</summary>
Все объекты, возвращаемые функциями API SDK, обладают общими специальными атрибутами:
| Атрибут | Описание |
| --- | --- |
| `_api_params` | Модель Pydantic, описывающая параметры, переданные в функцию. |
| `_http_response` | HTTP-ответ API платформы в виде экземпляра класса `requests.Response`. |
#### Соответствие названий
В SDK названия из API платформы приведены к стилю "snake_case", принятому в Python, а в некоторых случаях имеют иные отличия, при этом сохраняя смысл исходного названия в API платформы.
Для соответствия названий в SDK используются таблицы соответствия, с помощью которых можно узнать исходное название в API платформы.
<br>Каждая такая таблица хранится в виде словаря в файле YAML:
- [api/path_mapping.yml](/src/dynamix_sdk/api/path_mapping.yml) - таблица соответствия названий частей маршрута (URL path) к функции API.
<br>Данная таблица содержит только те названия, которые отличаются от названий в API платформы.
- [api/name_mapping.yml](/src/dynamix_sdk/api/name_mapping.yml) - таблица соответствия названий параметров функций и полей возвращаемых данных.
<br>Данная таблица содержит все названия, в том числе и те, которые совпадают с названиями в API платформы.
<br>Кроме общих соответствий, данная таблица также содержит индивидуальные соответствия, которые применяются только к классу модели, указанному в формате `sdk_name__model_class_name`.
### Типы данных SDK
Все типы данных (классы) SDK, которые могут пригодиться при разработке ПО с использованием SDK, доступны через модуль `dynamix_sdk.types`.
### Ошибки и исключения (exceptions)
SDK может вызывать исключения, которые должны быть обработаны в соответствии с требованиями к разрабатываемому вами ПО.
#### Ошибки валидации данных
SDK производит валидацию параметров функций API с помощью библиотеки **Pydantic**.<br>
Поэтому, при ошибке валидации, будет вызвано исключение `pydantic.ValidationError`.
Таким же образом валидируются данные HTTP-ответов API платформы. Причиной ошибки валидации данных HTTP-ответа API платформы может быть:
1. Несоответствие версии SDK и версии платформы.
1. Программная ошибка, допущенная при разработке SDK или платформы. Получить подтверждение наличия такой ошибки, а также ускорить её устранение, можно сообщив о ней.
Получить подробную информацию об исключении `pydantic.ValidationError` можно [в соответствующем разделе официальной документации Pydantic](https://docs.pydantic.dev/latest/errors/errors/) (ссылка ведёт на документацию для последней версии, поэтому важно выбрать версию, соответствующую используемой в SDK).
#### Ошибки HTTP
SDK для выполнения HTTP-запросов использует библиотеку **Requests**.<br>
Поэтому, при ошибке HTTP-подключения, будет вызвано соответствующее исключение библиотеки **Requests**.
Для проверки соответствует ли код ответа успешному выполнению запроса, SDK вызывает метод `requests.Response.raise_for_status()`, поэтому при неуспешном HTTP-запросе также будет вызвано исключение библиотеки **Requests**.
**Примечание:** если код ответа 503, то SDK предпримет несколько повторных попыток. Подробнее в разделе [Конфигурация](#конфигурация).
<details><summary>Обработка ошибок HTTP</summary>
```python
from requests.exceptions import RequestException, HTTPError
Подробную информацию об исключениях библиотеки **Requests** можно получить в [соответствующем разделе официальной документации Requests](https://requests.readthedocs.io/en/latest/user/quickstart/#errors-and-exceptions).
## Доступный функционал
### Способы авторизации
-с JWT
- через DECS3O
- через BVS
Подробнее в разделе [Конфигурация](#конфигурация).
