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

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

Структура json'а описана в документации к протоколу передачи классификаторов см раздел "2. Классификатор".

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

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

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

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

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

• Быстрый старт — установка, минимальные примеры экспорта/импорта, выбор режима импорта.
• Справочник API — сигнатуры, параметры, исключения, формат статистики и квитанции ФЛК.
• Формат JSON классификатора — структура файла, допустимые типы, правила ФЛК.
• Типовые сценарии на flask-restx — готовые эндпоинты импорта/экспорта, обработка ошибок, рекомендации по эксплуатации.

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

Модуль представляет 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 для управления зависимостями.

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

uv sync

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

uv shell

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

uv sync --group dev

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

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

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

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

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

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

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

Альтернатива если в системе установлен make Make for Windows, How to install and use "make" in Windows?

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 под целевую схему и таблицу.
• Руководство для разработчика-бэкендера: Быстрый старт, Справочник API, Формат JSON, Типовые сценарии на flask-restx.

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

• Импорт принимает только формат с 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 или на странице проекта