📊 Word Statistics API

Сервис для частотного анализа слов в текстовых файлах. Загрузите текстовый файл любого размера (до 1 ГБ) и получите детальную статистику по словоформам в формате Excel.

🚀 Возможности

• Обработка больших файлов – потоковое чтение файлов размером до 1 ГБ без перегрузки памяти.
• Умная нормализация – приводит слова к единой словоформе (например, «житель» и «жителем» считаются одним словом).
• Детальная статистика – результат содержит:
  • Словоформу
  • Общее количество вхождений в документе
  • Количество вхождений в каждой строке (в виде строки: 0,11,32,0,0,3)
• Асинхронная обработка – не блокирует систему при одновременной работе нескольких пользователей.
• Docker‑ready – простое развертывание с помощью Docker Compose.

🛠 Технологии

Компонент	Назначение
FastAPI	Веб-фреймворк для API
Uvicorn	ASGI-сервер для асинхронной обработки
OpenPyXL	Генерация Excel-файлов без MS Office
Aiofiles	Асинхронная работа с файлами
Python‑Multipart	Обработка загружаемых файлов
Docker	Контейнеризация приложения

📦 Установка и запуск

1️⃣ Клонирование репозитория

git clone https://github.com/kite-house/testwork_kaspersky.git
cd testwork_kaspersky

2️⃣ Запуск с помощью Docker (рекомендуется)

docker-compose up -d --build

После запуска API будет доступно по адресу: http://localhost:8000

3️⃣ Локальный запуск (без Docker)

1. Создайте виртуальное окружение:

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   .\venv\Scripts\activate   # Windows

2. Установите зависимости:

   pip install -r requirements.txt

3. Запустите сервер:

   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

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

Эндпоинт

POST /public/report/export

Параметры

Параметр	Тип	Описание
file	UploadFile	Текстовый файл (.txt) для анализа

Пример запроса (curl)

curl -X POST "http://localhost:8000/public/report/export" \
  -F "file=@/path/to/your/file.txt" \
  --output statistics.xlsx

Пример ответа

Успешный ответ – Excel-файл (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) с тремя колонками:

Словоформа	Кол-во во всем документе	Кол-во в каждой строке
привет	5	2,0,1,2,0
мир	3	1,1,0,0,1

🏗 Структура проекта

testwork_kaspersky/
├── application/          # Слой бизнес-логики
│   └── services.py       # Сервис обработки статистики
├── core/                 # Конфигурация
│   └── config.py         # Настройки приложения
├── domain/               # Доменный слой
│   └── entities.py       # Сущности и нормализатор слов
├── infrastructure/       # Инфраструктурный слой
│   ├── excel_generator.py # Генерация Excel
│   └── file_handler.py   # Потоковое чтение файлов
├── presentation/         # Слой представления
│   └── routes.py         # API маршруты
├── .dockerignore
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── main.py               # Точка входа
└── requirements.txt

🧪 Тестирование

Для проверки работоспособности используйте тестовый файл:

echo "привет мир" > test.txt
echo "привет мир мир" >> test.txt
curl -X POST "http://localhost:8000/public/report/export" \
  -F "file=@test.txt" \
  --output result.xlsx

Проверка состояния сервиса:

curl http://localhost:8000/health

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

Переменная	Значение по умолчанию	Описание
MAX_FILE_SIZE_MB	1024	Максимальный размер файла (МБ)
MAX_CONCURRENT_TASKS	5	Максимальное число одновременных задач
TMP_DIR	/tmp/fastapi	Директория для временных файлов

Разработано в рамках тестового задания для Kaspersky.