docs: update README, CONFIG and pyproject.toml for --send feature

- README: add --send flag to features, usage examples, full flag list;
  replace black/isort with ruff in dev section; add email config
  template variables docs
- CONFIG: new email section with all fields documented, --send usage
  examples, error handling and flag compatibility table
- pyproject.toml: remove unused black and isort from dev dependencies
  and their tool configs (project uses ruff for both lint and format)
This commit is contained in:
Кокос Артем Николаевич
2026-07-10 12:46:46 +07:00
parent 0968560090
commit 5e1c366a60
3 changed files with 186 additions and 27 deletions

View File

@@ -17,10 +17,11 @@ CLI-инструмент для генерации отчётов по зада
- Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
- Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
- Сводка по времени (`--summary`).
- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, SMTP.
- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, email.
- Умное разрешение `--output`: bare-формат (`xlsx`) → путь по шаблону, без расширения → автодописывание.
- `--commit`: автосохранение отчёта в файл + фиксация периода в YAML-конфиге для следующего запуска.
- Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть).
- `--send`: отправка отчёта по email через SMTP сразу после генерации.
- Понятные сообщения об ошибках Redmine API, SMTP и файловой системы.
- Загрузка альтернативного `.env` через `--config`.
## Установка
@@ -89,11 +90,17 @@ email:
from: bot@example.com
to:
- boss@example.com
cc: []
bcc: []
subject: "Отчёт {author} за {period}"
body_text: "Во вложении отчёт."
attach: true
```
Шаблон `output.filename` поддерживает `{author}`, `{from}`, `{to}`, `{date}` (DD_MM_YYYY), `{ext}`.
Шаблоны `email.subject` и `email.body_text` поддерживают `{author}`, `{period}` (строка диапазона, например `2026-06-01--2026-06-30`).
Подробнее: [docs/CONFIG.md](docs/CONFIG.md).
### `.env` (legacy)
@@ -125,6 +132,8 @@ DEFAULT_TO_DATE=2026-01-31
source .venv/bin/activate
```
### Основные сценарии
Отчёт за период по умолчанию:
```bash
@@ -164,41 +173,46 @@ redmine-reporter --compact
redmine-reporter --debug
```
Экспорт с явным путём:
### Экспорт в файл
Явный путь:
```bash
redmine-reporter --output report.xlsx
redmine-reporter --output /path/to/report.odt
```
Экспорт — только формат (путь и имя берутся из YAML-шаблона):
Только формат (путь и имя берутся из YAML-шаблона):
```bash
redmine-reporter --output xlsx # → output.dir/отчёт_01_07_2026.xlsx
redmine-reporter --output odt # → output.dir/отчёт_01_07_2026.odt
```
Экспорт — путь без расширения (дописывается `default_format` из конфига):
Путь без расширения (дописывается `default_format` из конфига):
```bash
redmine-reporter --output /tmp/report # → /tmp/report.xlsx (если default_format: xlsx)
```
Без времени / с разбивкой по активностям:
### Отправка по email (`--send`)
Отправить отчёт на email, указанный в YAML-конфиге (секция `email`):
```bash
redmine-reporter --no-time
redmine-reporter --by-activity
redmine-reporter --by-activity --summary
# Сохранить по шаблону и отправить
redmine-reporter --date 2026-06-01--2026-06-30 --send
# С явным путём
redmine-reporter --date 2026-06-01--2026-06-30 --output ~/report.xlsx --send
# Вместе с фиксацией периода
redmine-reporter --date 2026-06-01--2026-06-30 --send --commit
```
Сводка:
Если секция `email` не настроена — ошибка с пояснением. При ошибке SMTP файл отчёта остаётся на диске, данные не теряются. Поддерживаются `to`, `cc`, `bcc`, TLS, отключение вложения (`attach: false`).
```bash
redmine-reporter --summary
```
Фиксация периода (`--commit`):
### Фиксация периода (`--commit`)
```bash
# Сгенерировать, сохранить в файл по шаблону, запомнить период
@@ -215,6 +229,22 @@ redmine-reporter
redmine-reporter --commit
```
### Сводка и опции
Без времени / с разбивкой по активностям:
```bash
redmine-reporter --no-time
redmine-reporter --by-activity
redmine-reporter --by-activity --summary
```
Сводка:
```bash
redmine-reporter --summary
```
## Форматы вывода
| Формат | Особенности |
@@ -226,6 +256,33 @@ redmine-reporter --commit
| **JSON** | Массив объектов: `project`, `version`, `issue_id`, `subject`, `status`, `time`. |
| **Excel (.xlsx)** | Merge cells, колонки `Hours`/`Spent Time`, итоги, автоширина, автофильтр, freeze panes. |
## Полный список флагов
```
--date DATE Диапазон дат: YYYY-MM-DD--YYYY-MM-DD
--compact Компактный текстовый вывод вместо таблицы
--output PATH/FMT Путь к файлу (.odt/.csv/.md/.html/.json/.xlsx)
или bare-формат (xlsx/odt/...) — путь из конфига
--author NAME Переопределить имя автора
--no-time Не включать затраченное время в таблицу
--url URL Переопределить Redmine URL
--api-key KEY Переопределить Redmine API key
--config PATH Путь к альтернативному .env-файлу
--verbose Подробный вывод
--debug Отладочный вывод
--version Показать версию и выйти
--summary Вывести сводку по времени в stderr
--user-id ID Redmine ID пользователя для отчёта
--user-login LOGIN Логин пользователя Redmine
--user-name NAME Полное имя пользователя Redmine
--by-activity Разбить время по типам активности
--init-config Сгенерировать YAML-конфиг и выйти
--force Перезаписать существующий конфиг (с --init-config)
--config-path PATH Путь к YAML-конфигу (по умолчанию ~/.config/redmine-reporter/config.yml)
--commit Сохранить отчёт в файл и зафиксировать период в конфиге
--send Отправить отчёт по email после сохранения
```
## Разработка
Проверки перед коммитом:
@@ -233,8 +290,7 @@ redmine-reporter --commit
```bash
pytest
ruff check redmine_reporter tests
black --check redmine_reporter tests
isort --check-only redmine_reporter tests
ruff format --check redmine_reporter tests
mypy redmine_reporter
```