OInt CLI - приложение Открытого пакета интеграций для командной строки

Если вы не слышали ранее об Открытом Пакете Интеграций (что вполне вероятно), то небольшая вводная часть ниже, под катом. Для тех, кто уже знаком с ОПИ, данный раздел можно пропустить.

В прошлом большом обновлении для Открытого пакета интеграций появилась версия для OneScript. Текущий релиз это логическое продолжение данной идеи - реализация библиотеки в еще более интуитивном формате и с еще меньшим количеством необходимых действий для начала работы

В самом деле, большинство разработчиков, использующих OS, применяют его как инструмент для своих повседневных задач, но не для создания универсальных продуктов. И это вовсе не плохо. OneScript - хороший инструмент, который поможет выпутаться из многих непростых ситуации, когда дело касается выхода за пределы уютного 1С

Но тем острее становится вопрос соотношения гибкости и сложности. Без широкого горизонта возможностей не получится заниматься разработкой программного продукта, но нужно ли это разработчику, который уже использует этот самый программный продукт по прямому, утилитарному назначению? Для использования, например, любого пакета в качестве законченного решения, новому пользователю потребуется как минимум:

• Иметь OneScript на машине
• Иметь необходимый пакет
• Знать методы и особенности этого пакета (а это возможно только при наличии хотя бы мало-мальской документации)
• Написать некоторое окружение для работы: вызовы, заполнение параметров, обработку ответа и пр.

Это открывает большие возможности по тонкой настройке, но подобная свобода не всегда необходима, а главное - сопряжена со множеством трудностей.

Применительно к проекту ОПИ, это и было основной мыслью при создания CLI версии - конвертировать пакет в конкретную утилиту без необходимости думать обо всем вышеперечисленном

Что из себя представляет?

OInt CLI - практически полный перенос функционала Открытого пакета интеграций на рельсы единого исполняемого файла для терминала/командной строки. Для его создания использованы версия ОПИ под OneScript (которая OInt), библиотека cmdline для работы с опциями и аргументами, ну и, конечно же, возможность OneScript собирать скрипты в готовое приложение.

Список доступных команд:

• telegram - методы работы с Telegram Bot API 
• vk - методы работы с VK API
• viber - методы работы с Viber API
• twitter - методы работы с Twitter/X API
• notion - методы работы с Notion API
• yandex - методы работы с API Yandex ID
• yadisk - методы работы с Yandex.Disk API
• google - методы работы с API Google Workspace
• gcalendar - методы работы с Google Calendar API
• gdrive - методы работы с Google Drive API
• tools - пара небольших инструментов общего пользования

Целью было создать максимально простое в использовании ПО - простое как для людей, которые уже используют оригинальный пакет, так и для совсем новых пользователей. Что еще интересного мы можем там найти?

Встроенная справка

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

Имена методов полностью соответствуют таковым в родительской библиотеке, имена же самих библиотек - сокращены для удобства. Но они все равно говорящие: думаю, ни у кого не возникнет проблем с тем, что gdrive - это OPI_GoogleDrive, библиотека для работы с Google Drive-ом

Была обновлена и онлайн справка на opi.neocities.org - каждый раздел был дополнен списком опций для CLI и примерами возможных команд

Про ввод и вывод данных

Для ввода сообщений используются опции. Аргументы - нет.

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

Зачастую, передаваемые в опции значения - строки. Однако в ОПИ полно и тех функций, которые принимают коллекции (структуры или массивы), а бывает и даты. Решено это было следующим образом:

• Массивы передаются как ['Элемент1','Элемент2','Элемент3']
• Структуры и соответствия передаются как JSON (в качестве строки или как путь к файлу)
• Даты передаются как строки в формате ISO 8601

Но запоминать это не обязательно: во всех случаях, когда методы принимают подобные типы параметров, встроенная справка дополняется соответствующей подсказкой

Само преобразование строк в необходимые типы данных - не отдельный функционал CLI версии (хотя создавался именно для нее), но работает и в остальных вариантах библиотеки: обработчики вызываются уже непосредственно в основных методах, так что передавать JSON, массивы в квадратных скобках и ISO-даты теперь можно вне зависимости от используемой версии - 1С, OneScript или CLI

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

Инструменты и утилиты

Помимо общих методов ОПИ, специально для CLI был выделен отдельный набор с инструментами и утилитами под командой tools. Пока он не может похвастаться разнообразием, но это дело наживное. В данный момент я бы хотел заострить внимание на одном из существующих методов, так как он оказался действительно крайне полезным в реальной работе.

При использовании любого API частой является ситуация, при которой выполнение определенного действия требует отправки нескольких связанных запросов. Так, например, для работы с любыми сервисами Google Workspace необходимо периодически обновлять токен, так как старый сгорает через определенное время. Т.е. нам сначала необходимо отправить запрос на обновление токена, получить его, а уже только потом работать с необходимыми методами. Небольшой инструмент, о котором я сейчас расскажу, как раз и поможет нам вытаскивать данные из JSON ответов и передавать полученную информацию для дальнейшего использования

Рассмотрим на примере все того же Google Workspace: мы отправляем запрос на обновление токена, после чего получаем ответ с новым его значением. Как теперь достать это значение и передать в новый запрос? Для этого мы используем метод команды tools - РазложитьJSON

Данная функция имеет два режима работы: если опция --name указана, то возвращаются чистые данные поля с именем, равным её значению. Если же нет - возвращается список всех доступных полей, полученных из JSON. 

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

Требования и ограничения

OInt CLI делит свое единственное (найденное на данный момент) ограничение со своим "старшим братом" - пакетом для OS. Насколько я понимаю, OneScript не может записывать в поток двоичные данные размером > 2 GB

Масштаб проблемы, честно говоря, оценить сложно: API соц. сетей и мессенджеров, вроде VK, Telegram, Viber или Twitter, так и так не дадут вам загружать настолько большие файлы. Для Google Drive это проблемой не является, так для него в ОПИ реализована отдельная ветка загрузки больших файлов - все, что больше 256 МБ дробится на части и отправляется в особом режиме самого API от Google. Это могло быть проблемой разве что для API Yandex, но при загрузке чего-то большого на Яндекс.Диск его API не отвечает и при загрузке из 1С, где такой проблемы с размером файла нет

Скажем так: для большинства покрываемых задач это ограничение не играет роли

Системные требования - системные требования самого OneScript: .NET Framework 4.8 или Mono совместимой версии

Поставка

На данный момент есть четыре варианта поставки OInt:

• Исполняемый файл (бинарник, .exe). Он одинаково работает и на Windows и на Linux - лишь бы был .NET Framework
• Небольшой установщик для Windows (Временное решение: запускать необходимо от имени администратора, PATH пропишется после перезагрузки)
• Deb-пакет для Debian/Ubuntu
• RPM-пакет для Fedora/CentOS

Пакеты для Linux содержат в себе список необходимых зависимостей, которые будут установлены автоматически при установке OInt (собственно, mono)

Установка была опробована на текущей LTS версии Ubuntu (deb) и (внезапно) на RED OS (rpm). На обеих чистых системах OInt встал без проблем и дополнительных действий, автоматически дополучив необходимые пакеты через apt/dnf

Ссылка на релиз, где можно скачать данные файлы, будет в конце статьи. При возникновении ошибок или нахождении багов, огромная просьба написать об этом в Issues на GitHub! Это будет самая большая возможная поддержка данному проекту, особенно сейчас - на старте запуска новой версии.

В принципе, про CLI версию у меня пока все

В заключении

«Автоматизируйте все что можно с самого начала — тестирование, сборку, публикацию версий, документирование. Эти вещи проще всего отложить на потом, но «потом» уже не будет времени все это автоматизировать»

Андрей Овсянкин, EvilBeaver

Конкретика в данной статье закончилась - остались только рассуждения

Дело в том, что Открытый пакет интеграций уже существует некоторое время и, я должен сказать - это было интересно. Проект сравнительно не такой уж старый или большой, но тем не мене, в качестве послесловия сегодня, мне бы хотелось поделится некоторыми выводами и размышлениями, которые я делал в процессе работы над ним - рассказать о своем скромном опыте. 

Вообще, через все эти мысли трудно протянуть какую-то единую нить повествования, так что будет лучше разбить их на отдельные пункты. Все они, тем не менее, будут связаны с вопросами ведения и разработки open-source проекта. Возможно, это сможет помочь тем, кто начинает или еще только планирует начать вести свой собственный открытый репозиторий:
 

• Во-первых - про эпиграф (взят из этой статьи). Это чистая правда. Автоматизировать надо все и нет такого количества времени, которое было бы для этого "слишком большим". Лично у меня есть два примера для сравнения: автоматизированная конвертация ОПИ (1С) в OInt (OneScript) с запуском тестирования и вовсе даже неавтоматизированное создание документации. Надо ли говорит, какой механизм я ощущаю как воздух в легких, а какой вынуждает меня страдать каждый новый релиз? 
  
  Автоматизация пугает поначалу: ладно писать в VSCode при работе с OneScript, но разбираться в автотестах, Github Actions или Jenkins ради своего open-source проекта? Я нашел два момента, которые лично меня смотивировали этим заниматься:
  
  Во-первых, даже  если вы забросите свой проект спустя два дня - опыт останется с вами. Опыт это вообще, на мой взгляд, основной ориентир, которым необходимо руководствоваться при занятии подобными вещами - его вы получите гарантировано, в отличии от всего остального
  
  Во-вторых - ни что так не ломает мотивацию, как занятие рутиной. Освоив минимальные методы автоматизации своей работы, вы будете получать от ее реализации удовольствие, не меньшее чем от любых других видов написания кода. Я могу часами увлеченно писать OS-скрипт, который будет собирать yml для Github Actions, который будет запускать OS-скрипт для обработки исходников, но меня начинает тошнить спустя 20 минут после начала написания документации к новым методам, ей богу!
  
  Кстати, герой статьи, OInt CLI - это вообще плод исключительно процесса автоматизации. Вся его оснастка со списком методов - результат парсинга стандартных документирующих комментариев с небольшой доработкой 
  
  
   
• Автоматизированное тестирование - это база. Данный пункт, конечно, тоже можно было бы отнести к автоматизации, но дело тут в другом. Если вас не ломает нудная работа и проект ваш разрабатывается в режиме "дзен", то можно ничего не автоматизировать. Ничего, кроме тестирования
  
  Это бывает странно осознавать, но если в вашей программе/пакете/расширении будет ошибка - не только лишь все, но очень немногие вам об этом скажут. Особенно на первых парах. Если ваш свежий, пытающийся набрать некоторую начальную популярность, проект у пользователя не запускается - его просто выкинут и пойдут искать новый. Большие репозитории могут себе позволить быть местами поломанными. Во-первых они большие, во-вторых они уже имеют базу пользователей, заинтересованных в починке больше, чем в переходе на нечто другое. Маленьким проектам в такой роскоши отказано. Они должны нормально работать и автотесты, вызываемые постоянно при изменениях в коде - единственны инструмент, который позволит вам в этом убедится (хотя бы на приемлемый %)
   
• Документация важна. Это - достаточно очевидная мысль, я понимаю. Но, думаю, не у одного меня бывали моменты, когда при использовании какой-нибудь %ИмяПрограммы% приходилось искать ответы по случайным форумам и профильным порталам, так как сторонние люди, по всей видимости, лучше знают и яснее излагают тонкости работы с продуктом, чем это делают его разработчики
  
  Пусть это и не всегда справедливо - документация не обязана охватывать моменты конкретного применения, которые любят описывать в статьях и заметках. Но ни чуть не реже оказывается, что документации просто нет вовсе или использовать её будучи человеком с чувством прекрасного очень сложно. Все таки, нормальная цель для любого мейнтейнера - чтобы его продуктом было комфортно пользоваться, а не чтобы он, в принципе, работал. Читать же мысли разработчика, к сожалению, пока никакой возможности нет
   
• Соблюдайте стандарты - они не просто так сделаны. Вообще, постарайтесь по мере сил сделать свой open-source проект местом сбора максимального количества best practice. В нем вы - хозяин-барин, и никакой заказчик не спросит у вас о целесообразности использования SonarQube или EDT. А используя хорошие инструменты на первых парах, вы очень быстро заметите, как сами неосознанно начинаете писать правильно - даже без подсказок
  
  Побочный эффект: сильно вырастет процент кода, который будет казаться вам отвратительным непотребством. В том числе и вашего кода. Во многой мудрости много печали
  
  
• Не пренебрегайте красивостью и брендингом
  
  Опять же - просто рабочего продукта недостаточно, для того, чтобы его использовали. Да тот же ОПИ не собрал бы и половины из тех пользователей, что у него есть, если бы не альпака Виталий! Я до сих пор уверен, что люди на Github просто ему звезды ставят, за то что он такой желтый красивый! 
  
  Все мы человеки, а любой человек любит, когда красиво и прикольно, когда проект выглядит забавно и не угрожающе, будто бы несерьезно. Большинство продуктов, которыми вы пользуетесь каждый день, имеют маскота или, как минимум, узнаваемый логотип. Серьезные люди не считают это чем-то неважным - вот и вы не считайте. Тем более-то при возможностях сегодняшних нейросетей
   

Это то, что я хотел сегодня рассказать. Все же остальное, скорее всего, будет слишком персональным - опытом, который каждый должен прожить сам. Так что пока это все. И огромное спасибо за вашу поддержку - у проекта ОПИ без 2-х минут 100 звезд на GitHub, как ни как!
 

Спасибо за внимание!

Репозиторий ОПИ: github.com/Bayselonarrend/OpenIntegrations

Последний релиз: github.com/Bayselonarrend/OpenIntegrations/releases/tag/1.6.0

Другие статьи про Открытый пакет интеграций на Инфостарт:

• Открытый пакет интеграций для популярных API: Telegram, VK, Viber, Twitter

• Работа с Notion API | Обновление Открытого пакета интеграций

• Библиотека работы с Яндекс Диском (Open-source) 

• Открываем свою лавку на платформе VK Market

• Библиотека для работы с Google Calendar API (open-source) 

• Telegram в режиме форума: делаем чаты комфортными

• Открытый пакет интеграций для OneScript

 

 Мой GitHub:     https://gitub.com/Bayselonarrend 
 Лицензия MIT:   https://mit-license.org