ep_report_generator

Библиотека для создания отчетов для плат типа Board из библиотеки epcore.elements.

Применение

1. Установите библиотеки ep_report_generator, epcore и ivviewer:

   python -m pip install --upgrade pip
   python -m pip install git+https://github.com/EPC-MSU/ep_report_generator
   python -m pip install git+https://github.com/EPC-MSU/[email protected] git+https://github.com/EPC-MSU/[email protected]

2. В вашем python-скрипте импортируйте из библиотеки следующие классы:

   from report_generator import ConfigAttributes, ObjectsForReport, ReportGenerator, ScalingTypes

3. С помощью библиотеки epcore.elements создайте плату типа Board, для которой будет сгенерирован отчет:

   board = функция_которая_каким-то_образом_создает_плату()

4. Библиотека ep_report_generator может создать отчет как для всей платы целиком, так и для некоторых элементов и/или пинов на плате. Если вам нужно создать отчет только для некоторых элементов и/или пинов на плате, каким-либо образом определите индексы требуемых элементов и/или пинов.

   С определением индексов требуемых элементов не должно возникнуть проблем: в плате типа Board имеется атрибут elements, представляющий собой список элементов платы. Вам нужно определить индексы требуемых элементов в этом списке. Каждый элемент - это объект типа Element, у которого есть атрибут pins - список пинов на элементе. Индексы требуемых пинов нужно определить относительно одного общего списка пинов, объединяющего все пины на плате. Список всех пинов на плате получается последовательным объединением списков пинов на каждом элементе платы.

5. Создайте словарь-конфиг, по которому будет создан отчет. Для задания полей словаря-конфига используйте класс ConfigAttributes. Для задания объектов, которые должны быть включены в отчет, используйте класс ObjectsForReport. Для выбора типа масштабирования графиков сигнатур используйте класс ScalingTypes. Пример словаря-конфига:

   config = {ConfigAttributes.BOARD: board,
   		  ConfigAttributes.DIRECTORY: путь к папке, в которой нужно сохранить отчет,
             ConfigAttributes.OBJECTS: {ObjectsForReport.BOARD: нужно ли создать отчет для всей платы целиком True или False,
                                        ObjectsForReport.ELEMENT: [индексы элементов, которые должны быть включены в отчет],
                                        ObjectsForReport.PIN: [индексы пинов, которые должны быть включены в отчет]},
             ConfigAttributes.TOLERANCE: допуск,
             ConfigAttributes.PIN_SIZE: высота изображения пина в пикселях для отчета,
             ConfigAttributes.OPEN_REPORT_AT_FINISH: если True, то по завершении создания отчета отчет будет открыт,
             ConfigAttributes.REPORTS_TO_OPEN: список отчетов, которые нужно открыть в браузере по завершении создания отчетов,
             ConfigAttributes.APP_NAME: название приложения (например, EyePoint P10), которое использует генератор отчетов,
             ConfigAttributes.APP_VERSION: версия приложения, которое использует генератор отчетов,
             ConfigAttributes.TEST_DURATION: длительность тестирования (тип значения datetime.timedelta),
             ConfigAttributes.NOISE_AMPLITUDES: список с амлитудами шумов графиков сигнатур,
             ConfigAttributes.SCALING_TYPE: тип масштабирования графиков сигнатур (например, ScalingTypes.EYEPOINT_P10),
             ConfigAttributes.USER_DEFINED_SCALES: список с масштабами графиков сигнатур, если ConfigAttributes.SCALING_TYPE == ScalingTypes.USER_DEFINED,
             ConfigAttributes.ENGLISH: если True, то отчет будет создан на английском языке}

6. Создайте объект типа ReportGenerator и запустите его, передав в качестве аргумента словарь-конфиг:

   report_generator = ReportGenerator()
   report_generator.run(config)

7. После окончания работы в указанной вами папке появится отчет.

Запуск примера

1. Склонируйте репозиторий и перейдите в папку репозитория ep_report_generator:

   git clone https://github.com/EPC-MSU/ep_report_generator
   cd ep_report_generator

2. Установите необходимые зависимости, перейдя в папку scripts и выполнив скрипт:

   • install.bat, если Вы работаете в Windows;

   • install.sh, если Вы работаете в Linux:

     bash install.sh

3. Перейдите в папку scripts и запустите скрипт:

   • run_example.bat, если Вы работаете в Windows;

   • run_example.sh, если Вы работаете в Linux:

     bash run_example.sh

   В папке репозитория появится папка examples, в которой будут находиться четыре новые папки report_for_empty_board, report_for_manual_board, report_for_manual_board_with_user_defined_scales и report_for_p10_board с отчетами для соответствующих плат.

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

1. Установите необходимые зависимости, перейдя в папку scripts и выполнив скрипт:

   • install.bat, если Вы работаете в Windows;

   • install.sh, если Вы работаете в Linux:

     bash install.sh

2. Перейдите в папку scripts и запустите скрипт:

   • run_tests.bat, если Вы работаете в Windows;

   • run_tests.sh, если Вы работаете в Linux:

     bash run_tests.sh

Выпуск релиза

1. Задайте версию X.X.X выпускаемого релиза в файле report_generator/version.py.
2. Запушьте соответствующий коммит.
3. Повесьте тег vX.X.X на коммит.

Добавление перевода

1. Добавьте перевод в файл report_generator/locales/en/LC_MESSAGES/translation.po.

2. В Ubuntu 18 скомпилируйте бинарный файл с переводом. Для этого перейдите в папку report_generator/locales/en/LC_MESSAGES и выполните команду:

   msgfmt ./translation.po -o ./translation.mo

3. Добавьте новый бинарный файл в репозиторий и запушьте изменения.

Дополнение

1. Тестирование утечки памяти

Можно проверить, утекает ли память при генерации отчетов. Чтобы запустить тест:

1. Установите необходимые зависимости из файла requirements.txt, а также дополнительный модуль psutil.

2. Перейдите в корень репозитория и выполните в терминале команду:

   • если Вы работаете в Windows:

     venv\Scripts\python additional_tests\memoryleakstest.py REPORTS_NUMBER

   • если Вы работаете в Linux:

     venv/bin/python additional_tests/memoryleakstest.py REPORTS_NUMBER

   Здесь REPORTS_NUMBER - количество ответов, которые нужно сгенерировать при тестировании утечки памяти.

После завершения тестирования можно посмотреть на графике, как менялась память, выделенная генератору отчетов. Для этого перейдите в корень репозитория и выполните в терминале команду:

• если Вы работаете в Windows:

  venv\Scripts\python additional_tests\memoryleakanalyzer.py --log_files log_file_1 log_file_2

• если Вы работаете в Linux:

  venv/bin/python additional_tests/memoryleakanalyzer.py --log_files log_file_1 log_file_2

Здесь после флага log_files нужно перечислить названия файлов с логами тестирования утечки памяти, которые нужно визуализировать.

2. Время генерации отчета

Можно посмотреть, как распределяется время генерации отчета по разным этапам. Для этого:

1. Запустите генерацию отчетов для примеров.

2. После генерации отчетов для примеров в корне репозитория появится файл log.txt.

3. Перейдите в корень репозитория и выполните в терминале команду:

   • если Вы работаете в Windows:

     venv\Scripts\python additional_tests\timeanalyzer.py --log_file LOG_FILE

   • если Вы работаете в Linux:

     venv/bin/python additional_tests/timeanalyzer.py --log_file LOG_FILE

   Здесь после флага log_file нужно указать название файла с логами, который появился при генерации примеров.