Py_RuTracker

English | Русский

Py_RuTracker — это Python-библиотека для работы с RuTracker, популярным российским торрент-трекером. Библиотека предоставляет удобный и простой в использовании API для поиска раздач, получения информации о торрентах и их скачивания.

Основные возможности

• 🔍 Поиск раздач — поиск по названию с поддержкой пагинации и фильтрации
• ⬇️ Скачивание торрентов — автоматическое сохранение .torrent файлов или получение байтов для обработки
• 📋 Работа с формой поиска — получение разделов форума, опций сортировки и фильтров по времени
• ⚡ Синхронный и асинхронный API — выбор подходящего варианта для вашего проекта
• 🚀 Производительность — асинхронный клиент выполняет запросы параллельно для максимальной скорости
• 💾 Кеширование — автоматическое кеширование данных формы поиска для уменьшения нагрузки на сервер
• 📝 Логирование — настраиваемое логирование для отладки и мониторинга
• 🛡️ Обработка ошибок — детальные исключения для всех типов ошибок
• 🔐 Поддержка прокси — работа через прокси-серверы

Содержание

• Установка
• Быстрый старт
• Основные возможности
• Документация
• Примеры
• Логирование
• Технологии
• Внесение вклада
• Примечания

Установка

Вы можете установить библиотеку несколькими способами.

Установка с PyPI

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

pip install py-rutracker-client

Установка из исходников

Вариант 1: Использование Poetry (рекомендуется)

Проект использует Poetry для управления зависимостями. После клонирования репозитория:

1. Клонируйте репозиторий:

   git clone https://github.com/GvozdevAD/py_rutracker
   cd py_rutracker

2. Установите зависимости с помощью Poetry:

   poetry install --no-root

3. Активируйте виртуальное окружение Poetry:

   poetry shell

Вариант 2: Использование venv и pip

1. Клонируйте репозиторий:

   git clone https://github.com/GvozdevAD/py_rutracker
   cd py_rutracker

2. Создайте виртуальное окружение с помощью venv:

   python -m venv env

3. Активируйте виртуальное окружение:

   • На Windows:

     env\Scripts\activate

   • На macOS и Linux:

     source env/bin/activate

4. Установите зависимости из requirements.txt:

   pip install -r requirements.txt

Быстрый старт

Синхронный клиент

from py_rutracker import RuTrackerClient

# Создание клиента
client = RuTrackerClient("your_login", "your_password")

# Поиск раздач
results = client.search_all_pages("Static-X")

# Вывод результатов
for torrent in results:
    print(torrent)

# Скачивание первого торрента
if results:
    file_path = client.download(results[0].topic_id, save_path="./torrents")
    print(f"Торрент сохранен: {file_path}")

Асинхронный клиент

import asyncio
from py_rutracker import AsyncRuTrackerClient

async def main():
    async with AsyncRuTrackerClient("your_login", "your_password") as client:
        results = await client.search_all_pages("rammstein")
        if results:
            file_path = await client.download(
                results[0].topic_id,
                save_path="./torrents"
            )
            print(f"Торрент сохранен: {file_path}")

asyncio.run(main())

Логирование

Библиотека использует централизованное логирование. По умолчанию логируются только сообщения уровня WARNING и выше, чтобы не засорять вывод. Для отладки можно включить более подробное логирование.

Настройка уровня логирования

Вариант 1: Использование функции configure_logger

import logging
from py_rutracker import RuTrackerClient, configure_logger

# Установить уровень INFO
configure_logger(level='INFO')

# Или использовать константы из модуля logging
configure_logger(level=logging.DEBUG)

# С записью в файл
configure_logger(
    level='DEBUG',
    log_to_file=True,
    log_file_path="rutracker.log"
)

client = RuTrackerClient("your_login", "your_password")

Вариант 2: Использование переменной окружения

Установите переменную окружения перед запуском:

export PY_RUTRACKER_LOG_LEVEL=DEBUG

Или в Windows:

set PY_RUTRACKER_LOG_LEVEL=DEBUG

Доступные уровни: DEBUG, INFO, WARNING, ERROR, CRITICAL

Что логируется

• DEBUG: Детальная информация о всех операциях (HTTP-запросы, параметры поиска, закрытие сессий)
• INFO: Успешные операции (инициализация клиента, аутентификация, результаты поиска, загрузка торрентов)
• WARNING: Предупреждения (неожиданные статус-коды, ошибки на отдельных страницах)
• ERROR: Ошибки (ошибки аутентификации, парсинга, загрузки файлов)

Технологии

Библиотека использует современные технологии и лучшие практики:

• Pydantic — для валидации данных и моделей. Все модели данных (SearchResult) используют Pydantic для автоматической валидации типов и значений.
• aiohttp — для асинхронных HTTP-запросов
• requests — для синхронных HTTP-запросов
• BeautifulSoup4 — для парсинга HTML
• Централизованное логирование — для удобной отладки и мониторинга

Преимущества использования Pydantic

• Автоматическая валидация типов данных
• Преобразование типов (например, строки в числа)
• Валидация значений (проверка диапазонов, форматов)
• Удобная сериализация в JSON
• Подробные сообщения об ошибках при валидации

Документация

Полная документация по API доступна в файле docs/DOCUMENTATION.md (на русском) или docs/DOCUMENTATION_EN.md (in English).

Документация включает:

• Подробное описание всех методов RuTrackerClient и AsyncRuTrackerClient
• Описание моделей данных (SearchResult, SearchFormData и др.)
• Описание исключений и их обработки
• Дополнительную информацию о кешировании и работе библиотеки

Примеры

Подробные примеры использования библиотеки доступны в файле docs/EXAMPLES.md (на русском) или docs/EXAMPLES_EN.md (in English).

В папке examples/ находятся готовые примеры кода:

• basic_usage.py — базовое использование синхронного клиента
• async_usage.py — пример использования асинхронного клиента
• get_search_form.py — работа с формой поиска (синхронный клиент)
• get_search_form_async.py — работа с формой поиска (асинхронный клиент)
• logging_example.py — примеры настройки логирования

Вы можете запустить любой пример:

# Установите переменные окружения перед запуском
export LOGIN="your_login"
export PASSWORD="your_password"
export PROXY="http://proxy:8080"  # Опционально

# Запуск примеров
python examples/basic_usage.py
python examples/async_usage.py
python examples/get_search_form.py
python examples/get_search_form_async.py
python examples/logging_example.py

Внесение вклада

Вклад в развитие проекта приветствуется! Если вы хотите помочь проекту:

1. Создайте отдельную ветку от develop:

   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature-name

2. Внесите изменения и убедитесь, что код соответствует стилю проекта

3. Создайте Merge Request (MR) в ветку develop:

   • Убедитесь, что ваши изменения не ломают существующий функционал
   • Добавьте описание изменений в MR
   • Укажите связанные issues (если есть)

4. Дождитесь ревью — я рассмотрю ваш MR и при необходимости предложу улучшения

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

py_rutracker/
├── clients/          # Клиенты (sync, async)
├── core/             # Ядро библиотеки (базовый класс, константы)
├── models/           # Модели данных (Pydantic)
├── parsers/          # Парсеры HTML
├── utils/            # Утилиты (валидация, хелперы)
├── logger.py         # Централизованное логирование
├── exceptions.py     # Исключения
└── enums.py          # Перечисления

Примечания

• Замените "your_login" и "your_password" на ваши действительные учетные данные RuTracker.
• Укажите прокси в словаре, если ваш запрос требует использования прокси. Если прокси не требуется, вы можете не указывать этот параметр.
• Библиотека использует неофициальный API RuTracker и может не работать в случае изменений на сайте.