redmine-reporter

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

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

Лицензия: MIT.

Возможности

• Получение time entries текущего или указанного пользователя из Redmine.
• Авторизация через Redmine API token или логин/пароль.
• Группировка задач по проекту и версии.
• Перевод статусов задач на русский язык.
• Вывод в консоль (таблица / компактный вид).
• Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
• Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
• Сводка по времени (--summary).
• Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть).
• Загрузка альтернативного .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 .

Для разработки:

pip install -e ".[dev]"

Настройка

Создайте файл .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_URL=https://red.eltex.loc/
REDMINE_USER=ваш.логин
REDMINE_PASSWORD=ваш_пароль
REDMINE_AUTHOR=Иванов Иван Иванович

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

Переменная	Обязательность	Описание
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-проверка: true / false / путь к CA bundle.

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

source .venv/bin/activate

Отчёт за период по умолчанию:

redmine-reporter

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

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

Отчёт по другому пользователю:

redmine-reporter --user-id 42
redmine-reporter --user-login ivanov
redmine-reporter --user-name "Иванов И.И."

--user-name требует точного совпадения; если найдено несколько пользователей, CLI сообщает об ошибке и просит использовать --user-id.

Переопределить URL/API-ключ из .env:

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

Альтернативный конфигурационный файл:

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

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

redmine-reporter --compact

Отладочный вывод:

redmine-reporter --debug

Экспорт:

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

Отчёт без затраченного времени (работает для всех форматов):

redmine-reporter --no-time
redmine-reporter --no-time --output report.xlsx

Сводка по времени:

redmine-reporter --summary

Форматы вывода

Формат	Особенности
ODT	Заголовок с автором и месяцем, группировка по проекту/версии.
CSV	UTF-8 с BOM, полные значения project/version в каждой строке.
Markdown	Компактная таблица, повторяющиеся группы скрыты.
HTML	Полноценный HTML-документ с meta charset="utf-8".
JSON	Массив объектов: project, version, issue_id, subject, status, time.
Excel (.xlsx)	Merge cells, колонки Hours/Spent Time, итоги, автоширина, автофильтр, freeze panes.

Разработка

Проверки перед коммитом:

pytest
ruff check redmine_reporter tests
black --check redmine_reporter tests
isort --check-only redmine_reporter tests
mypy redmine_reporter

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

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