Readeck импортирует материалы по URL. Приложение подготавливает контент, временно публикует его по доступному в локальной сети адресу и создаёт закладку через Readeck API. Поэтому в библиотеку можно отправлять и локальные файлы.

Возможности

Импорт статьи по URL с извлечением основного содержания (trafilatura).
Загрузка файлов .txt, .html, .htm, .md, .markdown, включая drag & drop.
Автоопределение UTF-8 и Windows-1251 для локальных файлов.
Форматы содержимого: HTML, Markdown и простой текст.
Перевод через Google Translate с разбиением длинного текста на безопасные части.
Автозаполнение метаданных: заголовок, автор, описание, дата и сайт.
Предпросмотр итоговой статьи перед отправкой.
Санитизация HTML перед публикацией (bleach).
Проверка соединения с Readeck в настройках.
Локальная библиотека: отдельное окно для просмотра файлов из выбранной папки.
Отправка открытого в Локальной библиотеке файла в основное окно для последующей отправки в Readeck.
Светлая и тёмная темы, автосохранение черновика, счётчики символов и слов.
Интерфейс на русском, английском и казахском языках.

Требования

Python 3.9+ (проект проверялся на Python 3.12).
Доступный сервер Readeck и API-токен.
Сетевой доступ Readeck к машине с этим приложением, если Readeck расположен на другом хосте.

Установка

Windows: быстрый запуск

В каталоге проекта есть run.bat. Он запускает приложение через .venv\Scripts\python.exe и очищает унаследованные PYTHONPATH / PYTHONHOME.

Перед первым запуском создайте виртуальное окружение и установите зависимости:

py -3.12 -m venv .venv
.venv\Scripts\python -m pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura python-multipart
run.bat

Универсальный запуск

python -m pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura python-multipart
python main.py

Сервис слушает 0.0.0.0:8142, а браузер автоматически открывает http://127.0.0.1:8142.

Первоначальная настройка

При первом запуске откроется окно Настройки. Укажите:

Readeck URL — адрес Readeck, например http://192.168.1.10:8000.
API Токен — токен Readeck; приложение передаёт его в заголовке Authorization: Bearer ….
Ваш LAN IP — IP машины с приложением, доступный для Readeck. Он используется в callback-ссылке с материалом.
Папка локальной библиотеки — папка, в которой нужно искать файлы для чтения.
Язык интерфейса.

Нажмите Проверить подключение, затем Сохранить. Настройки записываются в config.json.

Работа с материалами

В основном окне вставьте текст, загрузите файл или введите URL статьи.
При необходимости выберите формат и переведите содержимое.
Заполните метаданные вручную либо используйте Автозаполнение.
Добавьте теги и нужные флаги Readeck.
Откройте предпросмотр и нажмите Создать закладку.

Локальная библиотека

Откройте Локальная библиотека в шапке основного окна.
В отдельном окне появится список поддерживаемых файлов из выбранной папки и всех её подпапок.
Нажмите Открыть, чтобы перейти в режим чтения. Файлы не загружаются целиком на странице списка, поэтому библиотека остаётся отзывчивой и с крупными каталогами.
На странице чтения используйте Отправить в Readeck. Содержимое и заголовок будут переданы в главное окно приложения.
Проверьте метаданные и создайте закладку обычным способом.

Поддерживаются .txt, .md, .markdown, .html и .htm. Переход за пределы выбранной директории заблокирован.

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

Регрессионные тесты не требуют сети или настоящего Readeck:

# Windows Git Bash / POSIX shell
PYTHONPATH= PYTHONHOME= .venv/Scripts/python.exe -m unittest tests.test_reader -v

# Windows cmd.exe
set PYTHONPATH=
set PYTHONHOME=
.venv\Scripts\python.exe -m unittest tests.test_reader -v

Проверяются настройки Локальной библиотеки, безопасное открытие файлов, передача текста в основное окно и наличие общей дизайн-системы интерфейса.

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

main.py — FastAPI-бэкенд, API и встроенный интерфейс Vue 3 / Tailwind.
run.bat — запуск приложения в Windows.
config.json — локальные настройки подключения и Локальной библиотеки. Не храните здесь рабочие токены в репозитории.
lang/ — локализации интерфейса.
tests/test_reader.py — автоматические тесты Локальной библиотеки и UI.
LOCALIZATION.md — сведения о локализации.

Локализация

Доступны:

English
Русский
Қазақша

Чтобы добавить язык, создайте lang/<код>.json, скопируйте структуру lang/en.json или lang/ru.json, переведите значения без изменения ключей и перезапустите приложение.

Подробнее: lang/README.md и LOCALIZATION.md.

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

config.json содержит API-токен в открытом виде. Не публикуйте реальный токен и перевыпустите его при утечке.
Сервис доступен в локальной сети на порту 8142, без собственной аутентификации.
Импорт по URL загружает произвольный адрес, то есть потенциально допускает SSRF. Не публикуйте приложение в интернете без ограничения доступа и дополнительной защиты.
Readeck должен иметь возможность обратиться по callback-адресу к указанному LAN IP и порту 8142.