Skip to content

Latest commit

 

History

History
121 lines (95 loc) · 14.6 KB

DEVELOPMENT.md

File metadata and controls

121 lines (95 loc) · 14.6 KB
Raw

Разработка парсера

Разработка модуля парсера для Melon максимально упрощена, унифицирована и абстрагирована. Пройдите этот путь вместе с данным мануалом.

Инструкция

0. Определения

Для лучшего понимания терминологии Melon рекомендуется ознакомиться с основными определениями, введёнными в процесс разработки.

Термин Определение
Временный каталог парсера Директория с относительным путём Temp/[PARSER_NAME]. Используется для хранения временных файлов, необходимых парсеру, или загрузки изображений без спецификации пути.
Домашний каталог парсера Директория с относительным путём Parsers/[PARSER_NAME]. Также под этим может пониматься корень подмодуля Git.
Дополнение контента Процесс получения и записи в структуры описания глав контента (слайдов или абзацев).
Формат описательного файла Набор правил о ключах и типах их значений в описательном файле JSON. Подробнее здесь.
Коллекция Текстовый файл Collection.txt во временном каталоге парсера, содержащий список алиасов тайтлов, разделённых символом новой строки.
Описательный файл Файл с расширением JSON, содержащий в себе все данные о конкретном тайтле в соответствии с одним из поддерживаемых форматов.
Прародитель парсера Парсер, работающий с родственным источником и предоставляющий свои методы для потомка.

1. Базовые файлы

Домашний каталог парсера обязан содержать следующие файлы:

  • main.py – главный модуль и точка входа в парсер;
  • README.md – описание дополнительных настроек парсера и особенностей использования;
  • requirements.txt – если парсер имеет специфические зависимости PyPI, не определённые в dublib или Melon, укажите их здесь.

Опциональны следующие файлы:

  • .gitignore – игнорируйте кэш Python и другие временные файлы Runtime и разработки;
  • LICENSE или LICENSE.txt – поставляйте лицензию для вашего Open Source модуля, чтобы явно указать все аспекты использования;
  • settings.json – при необходимости, укажите определите по умолчанию и дополнительные параметры;

2. Выбор типа парсера

Melon поддерживает два типа контента: манга и ранобэ.

Воспользуйтесь командой init от Melon для автоматической генерации всех необходимых файлов парсера выбранного типа контента. Подробнее: help init.

В main.py появится класс Parser, у наследованный от соответствующего типа, а также несколько констант. Определите их самостоятельно при необходимости.

# Версия парсера.
VERSION = "1.0.0"
# Уникальное название парсера. Не должно содержать небуквенных символов.
NAME = "site"
# Домен источника без указания протокола.
SITE = "site.com"
# Тип контента. Определяется автоматически.
TYPE = Manga

В файле settings.json можно указать стандартные параметры или определить дополнительные в секции custom. Пожалуйста, не забывайте описывать их в README.md.

3. Внедрение функционала

Для базового функционирования вам необходимо переопределить методы amend и parse из родительского класса (также можно переопределить image в качестве кастомного загрузчика изображений). Не изменяйте список принимаемых аргументов! Опционально вы можете имплементировать метод collect для сборки алиасов тайтлов в файл по шаблону:

collect

def collect(self, period: int | None = None, filters: str | None = None, pages: int | None = None) -> list[str]:
	"""
	Собирает список тайтлов по заданным параметрам.
		period – количество часов до текущего момента, составляющее период получения данных;\n
		filters – строка, описывающая фильтрацию (подробнее в README.md);\n
		pages – количество запрашиваемых страниц каталога.
	"""

	Collection = list()

	return Collection

Хранение данных внутри парсера происходит при помощи абстракции над строго задокументированным форматом JSON соответствующего типа, информацию о котором можно найти здесь. Доступ осуществляется через наследуемую переменную self._Title.

Для выполнения запросов рекомендуется использовать библиотеку dublib и её модуль WebRequestor. Вы можете определить собственные параметры запросчика через наследуемый метод self._InitializeRequestor по примеру из родительского объекта

4. Порталы

Для работы с CLI, логами, временными файлами и настройками предоставляются так называемые порталы и объектные имплементации, позволяющие выводить и использовать данные в унифицированном формате. Каждый парсер на разных этапах своей работы может использовать самодокументируемые порталы, определённые в объекте self._Portals.

Порталы совмещают вывод в консоль и доступ к логам, что позволяет обрабатывать их при помощи файлов конфигурации (см. Настройка логов).

В некоторых случаях парсер также обязан выбрасывать исключения, которые используются Melon для корректной обработки процесса получения контента. Порталы ошибок по умолчанию выбрасывают соответствующие исключения.

Порталы временных файлов

Парсеру может понадобиться хранить какие-либо сторонние файлы, тебующиеся обработчику контента (например Collection.txt), и, чтобы не засорять домашний каталог, доступен портал для лёгкого получения доступа к директории Temp. Для каждого парсера внутри данной директории создаётся свой подраздел.

from Source.Core.ImagesDownloader import ImagesDownloader

# Получение пути к каталогу временных файлов парсера.
Path = self._Temper.parser_temp
# Скачивание изображения во временный каталог парсера.
Filename = ImagesDownloader(self._SystemObjects).temp_image("https://link_to_image")
# Очистка каталога временных файлов парсера.
self._Temper.clear_parser_temp()

Настройки

Доступ к настройкам парсера рекомендуется осуществлять через абстракцию ParserSettings, однако классический режим также доступен.

# Классический небезопасный режим.
self._Settings["common"]["delay"]
self._Settings["proxy"]["enabled"]
self._Settings["custom"]["key"]
# Доступ через абстракцию.
self._Settings.common.delay
self._Settings.proxy.enabled
self._Settings.custom["key"]

5. Рекомендации

Как и любой хороший Open Source проект, Melon имеет ряд рекомендаций по чистоте кода парсеров, а также взаимодействию модулей и их структуре. Следуя им, вы однозначно повысите качество интеграции своего парсера с системой.

Номер Описание
1 Парсер должен выполнять все файловые операции внутри своих рабочих директорий, определённых настройками, а также во временном каталоге.
2 Все сетевые запросы парсера должны поддерживать проброс через прокси-сервер. Это позволяет обходить региональные ограничения.
3 Следует использовать только порталы CLI/логов для общения с пользователем и унификации интерфейса.
4 Ограничивайте частоту запросов к серверу: это позволяет не только избежать блокировок, но и не создаёт избыточную нагрузку на источник контента, что является хорошим тоном.
5 Всегда указывайте в описательных файлах авторов и переводчиков, если таковые известны. Уважайте чужой труд.
6 Парсер должен опираться на предоставляемые Melon методы, порталы, имплементации и абстракции. Это избавляет вас от изобретения велосипеда и позволяет длительное время поддерживать парсер в актуальном состоянии.
7 Домашний каталог парсера должен являться неизменяемым. Все настройки определяются в Configs/[PARSER_NAME], а временные файлы в Temp/[PARSER_NAME]. Поддерживайте чистоту.

6. Работа с парсером

Такие вещи, как CLI, логи, а также работа с данными ложатся на плечи Melon. Он следит за валидностью, стилистикой и иногда корректностью рабочего процесса и выходных данных. Предоставив парсер и правильно его настроив, вы можете использовать его так же непринуждённо, как и встроенные модули.

В случае возникновения вопросов свяжитесь с разработчиком: @DUB1401.