DOCS.md

Для разработчиков

Этот документ предназначен для разработчиков, которые:

• форкают проект под себя
• добавляют свою бизнес-логику
• интегрируют новые источники / экспорты
• хотят внести свои изменения через pull request

Общая концепция

Проект построен вокруг конфигурационного подхода:

• поведение определяется конфигом
• добавление нового типа уведомления не требует изменения ядра
• добавление нового типа сохранения не требует изменения ядра
• добавление нового типа обхода блокировок не требует изменения ядра

Примерный упрощенный алгоритм работы (зависит от выбранных настроек)

1. Получили cookies и прокси
2. Сделали запрос
3. Если ок - отправили уведомление и сохранили (отправляем уведомления по одному, сохраняем пачками)
4. Если не ок - сменили\разблокировали cookies, сменили ip
5. Повторили запрос

Принципы реализации

1. Все настройки содержатся в config.toml
2. Графический интерфейс основан на Flet (AvitoParser.py)
3. Код самого парсера в parser_cls.py и может запускаться независимо от gui
4. Есть docker и make команды для удобного запуска
5. Уведомления и сохранения вынесены в абстракцию, т.е. самому парсеру неизвестно куда он шлет уведомления и как сохраняет результаты (с версии 3.2.0)
6. БД sqlite (database.db) не вынесена в абстракцию, т.к. используется только для памяти уже просмотренных объявлений. SQLite используется намеренно и только как локальное хранилище просмотренных объявлений (не является частью расширяемой логики)
7. Клиент для запросов парсера и уведомлений используется намеренно разный (httpx и requests соответственно)
8. Для обхода блокировок используются разные варианты, основанные на изменении ip и\или использовании готовых cookies

Точки расширения

➕ Добавление нового типа уведомлений

Папка: integrations/notifications/

Что нужно реализовать (к примеру добавляем WA):

• класс WANotifier(Notifier) в отдельном файле:
• обрати внимание, что класс обязательно наследуется от Notifier
• в классе должен быть обязательно реализован метод notify(ad, message), где:

1. ad - Само объявление, модель смотри в dto.py
2. message - простая строка, для отправки уведомление типа "Это тестовое сообщение"

• подключить новый тип в integrations/notifications/factory.py Всё на этом, в код парсера вмешиваться не стоит. Если изменения будут вливаться в данный репозиторий, то нужно добавить этого провайдера в графический интерфейс (AvitoParser.py), по образце других уведомлений. Если изменения только для себя - дело Ваше.

➕ Добавление нового типа сохранения

Папка: parser/export/

Что нужно реализовать:

• создать файл с классом MyNewExport(ResultStorage), опять обрати внимание на родителя ResultStorage
• обязательно реализовать метод save(ads: list) - где ads - список! объявлений, модель смотреть здесь dto.py
• подключить новый тип сохранения в parser/export/factory.py
• в настройках есть опция "сохранять каждую ссылку в свой файл" - поэтому нужно реализовать еще функцию получения пути, смотри пример _build_excel_path
• если делаешь для PR, внеси новые изменения и в графический интерфейс AvitoParser.py

➕ Добавление нового способа работы с cookies

Папка: parser/cookies/

Что нужно реализовать:

• создать файл с классом MyNewCookiesProvider(CookiesProvider)
• реализовать метод get - получение cookies
• реализовать метод handle_block - что делать при блокировке cookies
• добавить опцию выбора в gui

Что не рекомендуется делать

❌ Добавлять бизнес-логику в GUI
❌ Делать сетевые запросы в save()
❌ Использовать глобальное состояние в Notifier
❌ Менять сигнатуры базовых абстракций

PR приветствуются, но пару моментов для делающих PR. Если хочется внести какие-то большие изменения, которые:

• переделывают половину кода (затрагивают core-логику)
• меняют алгоритм парсинга
• изменяют список зависимостей или их версии
• влияют на стабильность

То лучше создайте issue для обсуждения этого момента перед написанием кода - иначе есть риск пустой траты времени