treport 0.0.6

Library for generating tabular reports with results output in MS Excel format

Библиотека treport

Назначение библиотеки

Библиотека treport предназначена для формирования отчетов, имеющих исключительно табличное представление и фиксированное количество колонок. Результат формирования отчета выводится в формате MS Excel.

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

Для работы библиотеки требуется установить следующие пакеты:

• lxml >= 4.8.0
• Jinja2 >= 3.1.2
• openpyxl >= 3.0.10
• postgres >= 4.0

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

pip install -r requirements.txt

Установка библиотеки

Установить библиотеку можно, выполнив команду

pip install treport

Или скачать проект с GitHub.

Использование библиотеки

Подготовительные мероприятия

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

Пример, демонстрирующий работу библиотеки

Пример, демонстрирующий работу библиотеки, можно увидеть, перейдя по ссылке. В качестве примера рабочего каталога был создан каталог treport_example. Внутри него были размещены следующие файлы:

• run_report.xml- декларативное описание параметров формирования отчетных форм;
• run_report.ini - ini-файл, в котором прописаны параметры подклбчения к базе данных и путь к файлу run_report.xml
• run_report.py - программа на языке программирования Python, демонстрирующая использование библиотеки.

Внутри каталога treport_example размещаются следующие каталоги:

• sql - каталог для хранения файлов с SQL-запросами, которые формируют контент отчета;
• templates - каталог для хранения файлов шаблонов отчетных форм;
• out - каталог для хранения файлов сформированных отчетов.

Для демонстрации работы библиотеки необходимо иметь возможность подключения к базе данных PostgreSQL. Необходимо создать таблицу documents.

-- documents definition

CREATE TABLE documents (
	id int8 NOT NULL GENERATED ALWAYS AS IDENTITY,
	docnum varchar NOT NULL,
	docdate date NOT NULL,
	docsum numeric NOT NULL,
	docsum2 numeric NOT NULL
);

Содержимое таблицы представлено в файле documents.csv. Для импорта данных из CSV-файла необходимо выполнить команду

copy documents(docnum, docdate, docsum, docsum2) from '/path/to/documents.csv' delimiter ';' csv header;

Подготовка шаблона отчета

Шаблон отчета- это файл в формате xlsx. Отчет может состоять из нескольких листов. Нужно иметь в виду, что данная библиотека позволяет формировать отчетные формы, которые имеют исключительно табличный вид. Отчет может содержать формулы MS Excel. В этом случае необходимо в SQL-запросе предусмотреть выводить в данной колонке пустого значения, а XML-файле, описывающем свойства отчета, указать номера колонок, которые необходимо игнорировать при формировании отчета.

Подготовка SQL-файла

Для получения данных из БД необходимо подготовить файл с SQL-запросом. Для каждого листа отчета необходимо подготовить свой файл. Если требуется формировать отчет по заданным параметрам, то необходимо чтобы значения этих параметров были переданы в SQL-запрос. Для этого в тексте SQL-запроса параметры обрамляются двойными фигурными скобками (например {{ p_start_date }}).

Подготовка ini-файла

Необходимо подготовить ini-файл, в котором описываются параметры подключение к базе данных и путь к декларативному описанию свойств отчетов.

Пример ini-файла.

[database]
login = sergejnovikov
password =
port = 5432
host = localhost
database = postgres

[report]
params_reports = run_report.xml

Секция database- описываются параметры подключения к БД.

Список параметров:

• login - имя пользователя для подключения к БД;
• password - пароль пользователя для подключения к БД;
• port - порт, по которому происходит подключение к БД;
• host - адрес хоста, на котором размещается СУБД PostgreSQL;
• database - наименование БД.

Секция report - описывает параметры отчетных форм.

В данной секции пока только один параметр- params_reports. Значение параметра- путь к файлу, в котором приведено описание свойств отчетных форм.

Декларативное описание отчета

Отчет состоит из двух основных частей- SQL-запроса к базе данных и шаблона, описывающего его внешний вид.

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

Свойства отчета описываются в файле в формате XML. Правило описания свойства отчетов приведено в документации. Файл с XSD-схемой можно скачать со страницы проекта.

Формирование отчета

С использованием программы на Pythonn

После того как подключение к БД настроено, разработаны SQL-запросы, подготовлен шаблон отчета, можно приступить к написанию скрипта, который вызовет библиотеку и сформирует отчет.

from treport.report import Report, get_config

if __name__ == '__main__':
    parameters = {'p_start_date': '01.05.2022', 'p_end_date': '31.05.2022'}
    db_url, path_to_params_reports_file = get_config('run_report.ini')
    report = Report('treport_example', path_to_params_reports_file, parameters, db_url)

    if report.isCorrect:
        report.contentReport.save(report.outDir + report.report_file_name)
        report.logger.info(f'Файл {report.outDir + report.report_file_name} сохранен')

В переменной parameters хранятся параметры формирования отчета и их значения.

db_url, path_to_params_reports_file = get_config('run_report.ini') - вызывается функция get_config, аргумент функции- путь к ini-файлу, возвращается URL подключения к БД и путь к XML-файлу, описывающему свойства отчетов.

Далее создается объект ```report``. В конструктор класса передаются код формируемого отчета, путь к XML-файлу, описывающему свойства отчетов, параметры формирования отчета и URL подключения к БД.

Далее происходит проверка на предмет того соответствует ли XML-файл XSD-схеме. Если соответствует, то происходит сохранение файла отчета на файловую систему.

Из командной строки

Для формирования отчета из командной строки необходимо выолнить команду

python -m treport --report <код отчета> --config <ini-файл> --parameters-file <файл с параметрами отчета> --parameters <параметры отчета>

Аргументы командной строки:

--help - выводит помощь с описанием списка аргументов;
--report - код отчета, который необходимо сформировать;
--config - наименование конфигурационного файла, если параметр не указан, то в текущем каталоге ищется файл treport.ini;
--parameters-file - имя файла, в котором хранятся значения, в качестве разделителя используется символ "=";
--parameters - список передаваемых параметров, указывается в кавычках, в качестве разделителя используется символ ":".

Пример 1

python -m treport --report treport_example --parameters "p_start_date:01.04.2022;p_end_date:31.05.2022"

Будет сформирован отчет treport_example за период с 01.04.2022 по 31.05.2022, параметры подключения к базе данных и имя XML-файла будут прочитаны из файла treport.ini. Если такой файл в рабочем каталоге будет отсутствовать, то формирование отчета будет прервано.

Пример 2

python -m treport --report treport_example --config run_report.ini --parameters "p_start_date:01.04.2022;p_end_date:31.05.2022"

Параметры формирование отчета аналогичные параметрам в Примере 1, параметры подключения к базе данных и имя XML-файла будут прочитаны из файла run_report.ini.

Пример 3

python -m treport --report treport_example --parameters-file run_report_params.txt

Параметры подключения к базе данных и имя XML-файла будут прочитаны из файла treport.ini, параметры формирования отчета - из файла run_report_params.txt.

Пример 4

python -m treport --report treport_example --parameters-file run_report_params.txt --parameters "p_end_date:31.05.2022"

Параметры подключения к базе данных и имя XML-файла будут прочитаны из файла treport.ini, параметры формирования отчета - из файла run_report_params.txt, но более приоритетным значением будет значение, указанное в качестве значения параметра --parameters (дата окончания условий отбора будет установлена "31.05.2022", вне зависимости от того, какой значенние этого параметра указано в файле).

Пример 5

python -m treport --help

В результате выполннения команды бужет отображена следующая информация

usage: __main__.py [-h] [-c CONFIG] [-r REPORT] [-pf PARAMETERS_FILE] [-p PARAMETERS]

Программа предназначена для формирования отчетов, имеющих табличное представление

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Указывается путь конфигурационному файлу
  -r REPORT, --report REPORT
                        Код формируемого отчета
  -pf PARAMETERS_FILE, --parameters-file PARAMETERS_FILE
                        Файл с параметрами отчета
  -p PARAMETERS, --parameters PARAMETERS
                        Параметры отчета. Например: "param_name1:value_param1;param_name2:value_param2"