From 67b5d093d95f92c5dbee1a8f884658e88141ac00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9A=D0=BE=D0=BA=D0=BE=D1=81=20=D0=90=D1=80=D1=82=D0=B5?= =?UTF-8?q?=D0=BC=20=D0=9D=D0=B8=D0=BA=D0=BE=D0=BB=D0=B0=D0=B5=D0=B2=D0=B8?= =?UTF-8?q?=D1=87?= Date: Mon, 29 Jun 2026 15:02:31 +0700 Subject: [PATCH] docs(readme): update README and bump version to 1.6.1 - Remove duplicated --config bullet. - Update Excel section to reflect production-grade XLSX features. - Add --no-time note for file formats. - Add readable API error messaging to feature list. - Fix development commands: use --check flags and add mypy. - Replace verbose per-format sections with a summary table. - Bump pyproject.toml version to 1.6.1. --- README.md | 116 ++++++++++++++++--------------------------------- pyproject.toml | 2 +- 2 files changed, 39 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 2bb1d30..5cfcb34 100644 --- a/README.md +++ b/README.md @@ -9,17 +9,14 @@ CLI-инструмент для генерации отчётов по зада ## Возможности - Получение time entries текущего пользователя из Redmine. -- Авторизация через Redmine API token. -- Резервная авторизация через логин и пароль для обратной совместимости. +- Авторизация через Redmine API token или логин/пароль. - Группировка задач по проекту и версии. - Перевод статусов задач на русский язык. -- Вывод в консоль в табличном или компактном виде. +- Вывод в консоль (таблица / компактный вид). - Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx). -- Сводка по затраченному времени (итоги и разбивка по проектам/версиям). -- Автоматическое определение месяца ODT-отчёта по конечной дате периода. -- Настройка периода отчёта по умолчанию через `.env` (или автоматически — текущий месяц). -- Переопределение URL и API-ключа через CLI. -- Загрузка альтернативного `.env` через `--config`. +- Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой. +- Сводка по времени (`--summary`). +- Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть). - Загрузка альтернативного `.env` через `--config`. ## Установка @@ -33,9 +30,15 @@ pip install --upgrade pip pip install . ``` +Для разработки: + +```bash +pip install -e ".[dev]" +``` + ## Настройка -Создайте файл `.env` в корне проекта. Файл не должен попадать в git. +Создайте файл `.env` в корне проекта. Он не должен попадать в git. Рекомендуемый вариант авторизации: @@ -48,18 +51,13 @@ DEFAULT_FROM_DATE=2026-01-01 DEFAULT_TO_DATE=2026-01-31 ``` -Если задан `REDMINE_API_KEY`, он используется в первую очередь. Значения из `.env` можно переопределить через CLI: `--url`, `--api-key`, `--author`, а также загрузить другой файл конфигурации через `--config`. - -Резервный вариант авторизации: +Резервный вариант: ```ini REDMINE_URL=https://red.eltex.loc/ REDMINE_USER=ваш.логин REDMINE_PASSWORD=ваш_пароль REDMINE_AUTHOR=Иванов Иван Иванович - -DEFAULT_FROM_DATE=2026-01-01 -DEFAULT_TO_DATE=2026-01-31 ``` Переменные окружения: @@ -71,18 +69,9 @@ DEFAULT_TO_DATE=2026-01-31 | `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. - -Отключать проверку сертификатов не рекомендуется. +| `DEFAULT_FROM_DATE` | Нет | Начальная дата периода по умолчанию (`YYYY-MM-DD`). | +| `DEFAULT_TO_DATE` | Нет | Конечная дата периода по умолчанию (`YYYY-MM-DD`). | +| `REDMINE_VERIFY` | Нет | TLS-проверка: `true` / `false` / путь к CA bundle. | ## Использование @@ -90,7 +79,7 @@ DEFAULT_TO_DATE=2026-01-31 source .venv/bin/activate ``` -Отчёт за период по умолчанию (текущий месяц или из `.env`): +Отчёт за период по умолчанию: ```bash redmine-reporter @@ -102,15 +91,13 @@ redmine-reporter redmine-reporter --date 2026-02-01--2026-02-28 ``` -Период должен быть задан в формате `YYYY-MM-DD--YYYY-MM-DD`. Начальная дата не может быть позже конечной. - -Переопределение URL и API-ключа из `.env`: +Переопределить URL/API-ключ из `.env`: ```bash redmine-reporter --url https://red.example.com --api-key ваш_токен ``` -Использование альтернативного конфигурационного файла: +Альтернативный конфигурационный файл: ```bash redmine-reporter --config /path/to/.env @@ -122,19 +109,12 @@ redmine-reporter --config /path/to/.env redmine-reporter --compact ``` -Подробный или отладочный вывод: +Отладочный вывод: ```bash -redmine-reporter --verbose redmine-reporter --debug ``` -Вывод версии: - -```bash -redmine-reporter --version -``` - Экспорт: ```bash @@ -146,60 +126,40 @@ 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-документ с ``; -- корректно отображается в браузере и почтовых клиентах. - -ODT-отчёт: - -- месяц в заголовке определяется по `to_date`; -- имя автора берётся из `--author`, затем из `REDMINE_AUTHOR`; -- если автор не задан, поле автора остаётся пустым. - -Вывод без затраченного времени: +Отчёт без затраченного времени (работает для всех форматов): ```bash redmine-reporter --no-time +redmine-reporter --no-time --output report.xlsx ``` -Сводка по времени (итоги и разбивка по проектам): +Сводка по времени: ```bash 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. | + ## Разработка -Установка зависимостей для разработки: - -```bash -pip install -e ".[dev]" -``` - -Проверки: +Проверки перед коммитом: ```bash pytest ruff check redmine_reporter tests -black redmine_reporter tests -isort redmine_reporter tests +black --check redmine_reporter tests +isort --check-only redmine_reporter tests +mypy redmine_reporter ``` ## Безопасность diff --git a/pyproject.toml b/pyproject.toml index 7686e61..d937082 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "redmine-reporter" -version = "1.6.0" +version = "1.6.1" description = "Redmine time-entry based issue reporter for internal use" readme = "README.md" authors = [{ name = "Artem Kokos", email = "artem-kokos@mail.ru" }]