Metadata-Version: 2.4
Name: json-2-postgres
Version: 0.5.0
Summary: Набор утилит для конвертации таблиц postges в json формат и обратно
Author-email: Denis Maslennиков <ktotom7@yandex.ru>
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.17.3
Requires-Dist: psycopg2-binary>=2.9.9

# Утилиты для работы с системой импорт/экспорта классификаторов в едином формате.

## Модуль table_to_file предлагает набор функций для импорта/экспорта таблиц из БД в формат json и обратно.

Структура json'а описана в [документации к протоколу передачи классификаторов](https://docs.google.com/document/d/1XU7UtD5oosbDpONwQqgiNW-qEnEAXwVVloymeKhN6uA/edit?usp=sharing) см раздел "2. Классификатор".

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

### Ограничения:

* Последовательности (Sequences) должны быть в той же схеме, что и таблица их использующая

### Документация

Руководство пользователя для разработчика-бэкендера:

* [Быстрый старт](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/quick_start.md) — установка, минимальные примеры экспорта/импорта, выбор режима импорта.
* [Справочник API](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/api_reference.md) — сигнатуры, параметры, исключения, формат статистики и квитанции ФЛК.
* [Формат JSON классификатора](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/json_format.md) — структура файла, допустимые типы, правила ФЛК.
* [Типовые сценарии на flask-restx](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/recipes_flask_restx.md) — готовые эндпоинты импорта/экспорта, обработка ошибок, рекомендации по эксплуатации.

### Интерфейс взаимодействия с модулем.

Модуль представляет API состоящее из 4х методов:

#### `export_table_to_dict` - Преобразует таблицу из бд в словарь содержащий структуру и данные таблицы.

Параметры:

* `table_name` - Имя таблицы в базе данных.
* `dbname` - Имя базы данных.
* `user` - Пользователь БД.
* `password` - Пароль пользователя.
* `host` - Адрес сервера баз данных.
* `port` - Порт сервера баз данных.

Возвращаемое значение:

* Словарь со структурой и данными таблицы. Структура словаря соответствует описанной структуре классификатора в документации к протоколу.

#### `import_table_from_dict` - Импортирует данные из словаря подходящей структуры в базу данных.

Поведение зависит от параметра `import_mode`: если он равен `None` (по умолчанию), таблица не должна существовать в БД — она будет создана и заполнена данными из словаря. Если он равен `update`, таблица должна существовать в БД — её данные будут обновлены. В случае нарушения условий существования таблицы, а также при несоответствии структуры описанной в словаре таблице существующей в базе данных поднимается исключение ValueError.

Параметры:

* `table` - Структура таблицы и данные для импорта в виде словаря.
* `table_name` - Имя таблицы в базе данных.
* `dbname` - Имя базы данных.
* `user` - Пользователь БД.
* `password` - Пароль пользователя.
* `host` - Адрес сервера баз данных.
* `port` - Порт сервера баз данных.
* `foreign_tables_mapping` Словарь соответствия имен связанных таблиц в словаре и в базе данных. Ключи и значения словаря кортежи состоящие из пары значений ('имя_схемы', 'имя_таблицы') ключ - имена в структуре данных, значения - имена в базе данных. Пример {('имя_схемы_в_структуре', 'имя_таблицы_в_структуре'): ('имя_схемы_в_бд', 'имя_таблицы_в_бд')}
* `import_mode` Режим импорта. `None` - создание новой таблицы (таблица не должна существовать), `update` - обновление существующей таблицы (таблица должна существовать). По умолчанию `None`.
* `load_data` Загружать ли данные при создании новой таблицы (`import_mode=None`). `True` - структура и данные, `False` - только структура. По умолчанию `False`.

Возвращаемое значение:

* нет

#### `dict_as_json` - Сохраняет словарь с таблицей в виде json в BytesIO объект

Параметры:

* `table` - Словарь содержащий структуру таблицы для сохранения в json формате.

Возвращаемое значение:

* Объект BytesIO содержащий "файл" с переданной структурой в json формате.

#### `json_to_table` - Принимает или путь к файлу с json или BytesIO объект из которого

Параметры:

* `data_source` - Имя файла в системе или объект BytesIO содержащий в себе json соответствующего формата.
* `table_name` - Имя таблицы в базе данных.
* `dbname` - Имя базы данных.
* `user` - Пользователь БД.
* `password` - Пароль пользователя.
* `host` - Адрес сервера баз данных.
* `port` - Порт сервера баз данных.
* `foreign_tables_mapping` Словарь соответствия имен связанных таблиц в словаре и в базе данных.
* `import_mode` Режим импорта. `None` - создание новой таблицы (таблица не должна существовать), `update` - обновление существующей таблицы (таблица должна существовать). По умолчанию `None`.
* `load_data` Загружать ли данные при создании новой таблицы (`import_mode=None`). `True` - структура и данные, `False` - только структура. По умолчанию `False`.

Возвращаемое значение:

* нет

### Установка и использование

Этот проект использует [uv](https://github.com/astral-sh/uv) для управления зависимостями.

#### Установка зависимостей

```bash
uv sync
```

#### Активация виртуального окружения

```bash
uv shell
```

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

```bash
uv sync --group dev
```

### Запуск тестов.

Для запуска тестов необходимо установленный в системе Docker.
Тесты запускаются из директории проекта командой

```bash
docker-compose -f docker-compose.pytest.yml run --build --rm tests
```

Также для запуска можно использовать вариант с двумя последовательными командами

```bash
docker-compose -f docker-compose.pytest.yml build --no-cache
docker-compose -f docker-compose.pytest.yml run --rm tests
```

После тестов желательно удалить созданные контейнеры

```bash
docker-compose -f docker-compose.pytest.yml down -v
```

Альтернатива если в системе установлен make [Make for Windows](https://gnuwin32.sourceforge.net/packages/make.htm), [How to install and use &#34;make&#34; in Windows?](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows)

```bash
make test
```

### Последние изменения

### [0.5.0] - 2026-10-15

#### Добавлено:

- Импорт/экспорт и ФЛК переведены на формат классификатора с обёрткой `payload` (структура и данные внутри `payload.structure` / `payload.data`).
- Расширенный форматно-логический контроль (`FLKValidator`): семантические проверки структуры таблицы, ограничений, последовательностей и значений данных; защита от SQL-инъекций в `default`/`check_clause`; лимит размера JSON (`max_size_bytes`).
- Параметры `return_stats` (статистика импорта: вставлено/обновлено) и `excluded_columns` (колонки, значения которых не изменяются) в функциях `json_to_table` и `import_table_from_dict`.
- Модуль `settings` с константой `DEFAULT_SCHEMA`; нормализация DEFAULT-значений с `nextval` под целевую схему и таблицу.
- Руководство для разработчика-бэкендера: [Быстрый старт](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/quick_start.md), [Справочник API](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/api_reference.md), [Формат JSON](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/json_format.md), [Типовые сценарии на flask-restx](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/docs/recipes_flask_restx.md).

#### Внимание (совместимость):

- Импорт принимает только формат с `payload` — старый формат (structure/data на верхнем уровне) убран.
- Схема по умолчанию — `public` (ранее жёстко заданная `classification`); задаётся параметром `schema_name`.

### [0.4.0] - 2026-09-11

#### Добавлено:

- Параметр `import_mode` в функциях `import_table_from_dict` и `json_to_table`: `None` (по умолчанию) - создание новой таблицы (таблица не должна существовать), `update` - обновление существующей таблицы (таблица должна существовать).
- Параметр `load_data` в функциях `import_table_from_dict` и `json_to_table`: при создании новой таблицы (`import_mode=None`) позволяет загружать только структуру (`False`, по умолчанию) или структуру вместе с данными (`True`).

### Полная история изменений

Смотрите полную историю всех изменений в файле [CHANGELOG.md](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/CHANGELOG.md) или [на странице проекта](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/CHANGELOG.md)
