redmine-reporter/README.md

redmine-reporter

CLI-инструмент для генерации отчётов по задачам Redmine на основе записей о затраченном времени.

Проект предназначен для внутреннего использования с https://red.eltex.loc/.

Лицензия: MIT.

Возможности

• Получение time entries текущего пользователя из Redmine.
• Авторизация через Redmine API token.
• Резервная авторизация через логин и пароль для обратной совместимости.
• Группировка задач по проекту и версии.
• Перевод статусов задач на русский язык.
• Вывод в консоль в табличном или компактном виде.
• Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
• Сводка по затраченному времени (итоги и разбивка по проектам/версиям).
• Автоматическое определение месяца ODT-отчёта по конечной дате периода.
• Настройка периода отчёта по умолчанию через .env (или автоматически — текущий месяц).
• Переопределение URL и API-ключа через CLI.
• Загрузка альтернативного .env через --config.
• Загрузка альтернативного .env через --config.

Установка

git clone https://git.akokos.ru/artem.kokos/redmine-reporter.git
cd redmine-reporter
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .

Настройка

Создайте файл .env в корне проекта. Файл не должен попадать в git.

Рекомендуемый вариант авторизации:

REDMINE_URL=https://red.eltex.loc/
REDMINE_API_KEY=ваш_api_token
REDMINE_AUTHOR=Иванов Иван Иванович

DEFAULT_FROM_DATE=2026-01-01
DEFAULT_TO_DATE=2026-01-31

Если задан REDMINE_API_KEY, он используется в первую очередь. Значения из .env можно переопределить через CLI: --url, --api-key, --author, а также загрузить другой файл конфигурации через --config.

Резервный вариант авторизации:

REDMINE_URL=https://red.eltex.loc/
REDMINE_USER=ваш.логин
REDMINE_PASSWORD=ваш_пароль
REDMINE_AUTHOR=Иванов Иван Иванович

DEFAULT_FROM_DATE=2026-01-01
DEFAULT_TO_DATE=2026-01-31

Переменные окружения:

Переменная	Обязательность	Описание
REDMINE_URL	Да	URL Redmine.
REDMINE_API_KEY	Да, если нет логина и пароля	Redmine API token.
REDMINE_USER	Да, если нет токена	Логин Redmine.
REDMINE_PASSWORD	Да, если нет токена	Пароль Redmine.
REDMINE_AUTHOR	Нет	Имя автора для ODT-отчёта.
DEFAULT_FROM_DATE	Нет	Начальная дата периода по умолчанию в формате YYYY-MM-DD.
DEFAULT_TO_DATE	Нет	Конечная дата периода по умолчанию в формате YYYY-MM-DD.
REDMINE_VERIFY	Нет	Настройка TLS-проверки для Redmine API.

REDMINE_VERIFY поддерживает значения:

• пустое значение или отсутствие переменной: /etc/ssl/certs/ca-certificates.crt;
• true, 1, yes, on: стандартная проверка сертификатов requests;
• false, 0, no, off: отключить проверку сертификатов;
• любой другой текст: путь к CA bundle.

Отключать проверку сертификатов не рекомендуется.

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

source .venv/bin/activate

Отчёт за период по умолчанию (текущий месяц или из .env):

redmine-reporter

Отчёт за произвольный период:

redmine-reporter --date 2026-02-01--2026-02-28

Период должен быть задан в формате YYYY-MM-DD--YYYY-MM-DD. Начальная дата не может быть позже конечной.

Переопределение URL и API-ключа из .env:

redmine-reporter --url https://red.example.com --api-key ваш_токен

Использование альтернативного конфигурационного файла:

redmine-reporter --config /path/to/.env

Компактный вывод:

redmine-reporter --compact

Подробный или отладочный вывод:

redmine-reporter --verbose
redmine-reporter --debug

Вывод версии:

redmine-reporter --version

Экспорт:

redmine-reporter --output report.odt
redmine-reporter --output report.csv
redmine-reporter --output report.md
redmine-reporter --output report.html
redmine-reporter --output report.json
redmine-reporter --output report.xlsx

JSON-отчёт:

• массив объектов с полями project, version, issue_id, subject, status, time;
• UTF-8, читаемый машиной.

Excel-отчёт (.xlsx):

• одна таблица с заголовками и строками данных;
• шапка выделена жирным;
• каждая строка содержит полные значения проекта и версии.

CSV-отчёт:

• файл сохраняется в UTF-8 с BOM (utf-8-sig) для корректного отображения кириллицы в Microsoft Excel;
• каждая строка содержит полные значения проекта и версии (в отличие от консольного и Markdown-вывода, где повторяющиеся значения скрыты для компактности).

HTML-отчёт:

• полноценный HTML-документ с <meta charset="utf-8">;
• корректно отображается в браузере и почтовых клиентах.

ODT-отчёт:

• месяц в заголовке определяется по to_date;
• имя автора берётся из --author, затем из REDMINE_AUTHOR;
• если автор не задан, поле автора остаётся пустым.

Вывод без затраченного времени:

redmine-reporter --no-time

Сводка по времени (итоги и разбивка по проектам):

redmine-reporter --summary

Разработка

Установка зависимостей для разработки:

pip install -e ".[dev]"

Проверки:

pytest
ruff check redmine_reporter tests
black redmine_reporter tests
isort redmine_reporter tests

Безопасность

• Не коммитьте .env, API token, пароль или логин.
• Используйте аккаунт с минимальными правами, достаточными для чтения time entries и задач.
• Инструмент работает только в режиме чтения и не изменяет данные в Redmine.