Для авторов новых плагинов

Про эту инструкцию

Т.к. пока желающих писать собственные плагины не сказать что очень много мне в большинстве случаев на вопросы по написанию плагинов проще ответить лично, чем заниматься написанием серьезной инструкции. По тем же причинам я пока не обдумывал серьезно как быть если плагинов и авторов будет слишком много и нужно будет это как-то аккуратно разрешать от конфликтов. Появиться такая проблема - будем думать. Пока решаем это в виде pull request от авторов в ветку dev
Эту инструкцию пишу пока для старта.

Структура плагинов

Плагины - это программа на питоне - файл, расположенный в папке mbplugin/plugin, содержащий функцию:

def get_balance(login, password, storename=None, **kwargs):
    result = {'Balance': 124.45}
    return result

Простые плагины

Пример простого плагина и возвращаемые параметры можно посмотреть в файле mbplugin/plugin/test1.py
Если Вы хотите получить какие-то данные с веб страницы и вариант просто воспользоваться библиотеками типа request, примеры такого использования можно найти например в плагинах megafon или avtodor-tr

Плагины для получения данных через браузер, использующие Playwright

Если Вы хотите получить какие-то данные с веб страницы и вариант просто воспользоваться библиотеками типа request Вам по каким-то причинам не подходят, то можно воспользоваться playwright. В принципе никто не мешает пользоваться им напрямую, но я реализовал основную часть рутины в классе BrowserController, для упрощения использования на типичных сайтах, что позволяет в большинстве случаев написать плагин буквально за 10 строчек кода. Пример такого плагина смотрите в mbplugin/plugin/test1.py

Логон

Т.к. в основном все страницы в окне логона довольно похожи, то для того чтобы понять куда писать логин и пароль хватит универсальных тэгов.
Они описаны в структуре default_logon_selectors в файле mbplugin/plugin/browsercontroller.py
Все уточнения проводим открыв окно логона в браузере и запустив отладчик.
Если какие-либо из них не подходят (самыя распространенная причина - поле логина не находится по type=text или кнопка submit как то замысловато обнаруживается) - то создаем словарь user_selectors с теми значениями, которые должны перекрыть значения по умолчанию.
Для логона используем do_logon передавая в user_selectors изменения значений по умолчанию
self.do_logon(url=login_url, user_selectors=user_selectors)

Сбор данных

В большинстве случаев интересующая информация приходит в json сразу после нажатия submit, так что в простом случае просто пытаемся после логона получить из приходящих json данные с помощью вызова метода

self.wait_params(params=[{
            'name': 'Balance', 'url_tag': ['object/meters'], 'jsformula': "data.data.sensors[0].meters.length",
        }])

В self.wait_params можно указать несколько параметров в одном выхове. Подробное описание смотрите так же в файле mbplugin/plugin/browsercontroller.py
В данном примере мы получаем значение параметра Balance со страницы url или POST запрос которой содержит 'object/meters' для получения берем содержимое запроса как переменную data и выполняем data.data.sensors[0].meters.length.
Для отладки удобно в консоли браузера присваивать переменной data полученный json и дальше прямо в отладчике пытаться написать выражение, дающее требуемый результат. Если же обработку полученного json необходимо провести на python то вместо jsformula пишем код на python в параметре pformula
В случае если данные необходимо просто получить со страницы указываем пустой url_tag и просто пишем выражение для анализа данных со страницы, отладить его можно точно также в отладчике.
В любот случае можно посмотреть плагины других провайдеров и скорее всего найдуться похожие на Ваш случаи.

Диагностика.

В ходе разработки естественно возникают ошибки, для того чтобы понять что идет не так я запускаю проверку командой mbp check-plugin p_pluginname login password И затем смотрю в файле mbplugin/log/mbplugin.log ошибки. (еще удобнее через tail -f)
Также в таком варианте можно воспользоваться и breakpoint(), главое не забудьте их убрать перед реальным использованием.

Иконка для плагина

Для полноты картины иконку, которая будет видна в MobileBalance, можно сделать с помощью утилиты mbplugin/plugin/get_icon.py](https://github.com/artyl/mbplugin/blob/master/plugin/get_icon.py) указав ей либо url либо скачанный файл favicon.ico или его аналог. иконка - это переменная icon в теле модуля.