Metadata-Version: 2.4
Name: json-2-postgres
Version: 0.4.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) должны быть в той же схеме, что и таблица их использующая

### Интерфейс взаимодействия с модулем.
Модуль представляет 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 "make" in Windows?](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows)
```bash
make test
```
### Последние изменения
### [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](CHANGELOG.md) или [на странице проекта](https://git.lab.nexus/military_developer/unified_reference_book/-/blob/main/CHANGELOG.md)
