redmine-reporter

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

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

Лицензия: MIT.

Возможности

• Получение time entries текущего или указанного пользователя из Redmine.
• Авторизация через Redmine API token или логин/пароль.
• Группировка задач по проекту и версии.
• Перевод статусов задач на русский язык.
• Разбивка по типам активности (--by-activity).
• Вывод в консоль (таблица / компактный вид).
• Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
• Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
• Сводка по времени (--summary).
• YAML-конфиг (~/.config/redmine-reporter/config.yml): шаблон имени файла, путь по умолчанию, период, SMTP.
• Умное разрешение --output: bare-формат (xlsx) → путь по шаблону, без расширения → автодописывание.
• --commit: автосохранение отчёта в файл + фиксация периода в YAML-конфиге для следующего запуска.
• Понятные сообщения об ошибках 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]"

Настройка

Источники конфигурации (от высшего приоритета к низшему):

CLI-флаги  >  переменные окружения  >  .env  >  YAML-конфиг  >  кодовые дефолты

YAML-конфиг (основной способ)

# Сгенерировать YAML из текущего .env
redmine-reporter --init-config

# Редактировать под себя
vim ~/.config/redmine-reporter/config.yml

Структура:

redmine:
  url: https://red.eltex.loc
  api_key: ${REDMINE_API_KEY}
  author: "Кокос А.А."
  verify_ssl: true

period:
  precision: date                   # date | datetime
  default_from: "2026-06-01"
  default_to: "2026-06-30"
  dynamic: false
  # last_used заполняется --commit (см. docs/CONFIG.md)

output:
  dir: ~/reports
  filename: "{author}_{from}_{to}.{ext}"
  default_format: xlsx

email:
  smtp:
    host: smtp.example.com
    port: 587
    user: bot@example.com
    password: ${SMTP_PASSWORD}
    tls: true
  from: bot@example.com
  to:
    - boss@example.com
  subject: "Отчёт {author} за {period}"

Шаблон output.filename поддерживает {author}, {from}, {to}, {date} (DD_MM_YYYY), {ext}.

Подробнее: docs/CONFIG.md.

.env (legacy)

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	Да	URL Redmine.
REDMINE_API_KEY	Да, если нет логина и пароля	Redmine API token.
REDMINE_USER	Да, если нет токена	Логин Redmine.
REDMINE_PASSWORD	Да, если нет токена	Пароль Redmine.
REDMINE_AUTHOR	Нет	Имя автора для отчёта.
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 "Иванов И.И."

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

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

Альтернативный .env:

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

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

redmine-reporter --compact
redmine-reporter --debug

Экспорт с явным путём:

redmine-reporter --output report.xlsx
redmine-reporter --output /path/to/report.odt

Экспорт — только формат (путь и имя берутся из YAML-шаблона):

redmine-reporter --output xlsx          # → output.dir/отчёт_01_07_2026.xlsx
redmine-reporter --output odt           # → output.dir/отчёт_01_07_2026.odt

Экспорт — путь без расширения (дописывается default_format из конфига):

redmine-reporter --output /tmp/report   # → /tmp/report.xlsx (если default_format: xlsx)

Без времени / с разбивкой по активностям:

redmine-reporter --no-time
redmine-reporter --by-activity
redmine-reporter --by-activity --summary

Сводка:

redmine-reporter --summary

Фиксация периода (--commit):

# Сгенерировать, сохранить в файл по шаблону, запомнить период
redmine-reporter --commit

# С явным путём
redmine-reporter --commit --output report.xlsx

# Следующий запуск (без --date) возьмёт следующий период автоматически
redmine-reporter

# При precision=datetime запоминает момент времени
# (предотвращает дублирование записей внутри дня)
redmine-reporter --commit

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

Формат	Особенности
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, пароль или логин.
• YAML-конфиг имеет права 0600, директория — 0700.
• Рекомендуется хранить секреты через ${VAR}, а не plaintext.
• Используйте аккаунт с минимальными правами, достаточными для чтения time entries и задач.
• Инструмент работает только в режиме чтения и не изменяет данные в Redmine.