Создание собственного репозитория плагинов QGIS

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

Менеджер плагинов

В QGIS для работы с плагинами есть специальный инструмент — менеджер плагинов. Он позволяет искать плагины, устанавливать и удалять их, отслеживать появление новых версий установленных плагинов, подключать сторонние репозитории и т.д. Для каждого плагина менеджер плагинов предоставляет окно с информацией о плагине. Существует три сценария заполнения этой информации:

1. Плагин находится в репозитории, но не установлен на вашем компьютере. В этом случае вся информация для менеджера плагинов извлекается из описания плагина в файле plugins.xml.
2. Плагин установлен на вашем компьютере и есть связь с репозиторием. В этом случае часть информации по-прежнему извлекается из описания плагина в файле plugins.xml, а часть из файла метаданных metadata.txt
3. Плагин установлен на вашем компьютере и связи с репозиторием нет. В этом случае вся информация для менеджера плагинов извлекается из файла метаданных metadata.txt.

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

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

Каждый плагин в репозитории должен быть упакован в отдельный zip-архив, в котором обязательно должна присутствовать корневая папка, а в ней — файлы вашего плагина вместе с файлом metadata.txt. По названию корневой папки менеджер плагинов QGIS будет сопоставлять установленные локально плагины с плагинами, доступными в репозитории. Особенности такого сопоставления будут рассмотрены ниже в разделе Связь между локальным плагином и плагином в репозитории.

Работоспособный плагин QGIS должен содержать в своем каталоге всего два обязательных файла:
 

• __init__.py – начальная точка плагина. Файл должен содержать метод classFactory().
• metadata.txt – содержит общую информацию оплагине.

Пример плагина, с минимальным набором файлов, можно изучить по ссылке.

Более подробно изучить структуру плагинов можно в официальной документации.

Файл метаданных

Как уже было отмечено, в каталоге каждого плагина должен быть файл metadata.txt, содержащий общую информацию о плагине. Информация из него используется для отображения в менеджере плагинов QGIS, поиска плагина и т.д.

Структура файла метаданных должна быть следующей:

[general]
Parameter1_Name: Parameter1_Value
Parameter2_Name: Parameter2_Value
…
ParameterN_Name: ParameterN_Value

Либо:

[general]
Parameter1_Name= Parameter1_Value
Parameter2_Name= Parameter2_Value
…
ParameterN_Name= ParameterN_Value

В качестве разделителя имени параметра и его значения можно использовать как двоеточие, так и символ "=". При этом не обязательно, чтобы в одном файле метаданных был только один тип разделителя. Пробелы до и после разделителя не влияют на считывание данных из metadata.txt, поэтому могут быть в любом количестве, либо отсутствовать вовсе. Обратите также внимание, что ключевое слово "[general]" в начале файла метаданных обязательно.

Обязательные параметры, без наличия которых работа плагина может быть нарушена, следующие:

• name – название плагина,
• version – версия плагина,
• qgisMinimumVersion – минимальная версия QGIS, подходящая для работы с данным плагином.

Информацию об остальных параметрах вы можете узнать по ссылке.

plugins.xml

Каждый репозиторий должен содержать файл plugins.xml, предоставляющий общую информацию для менеджера плагинов обо всех плагинах доступных в репозитории.


Структура plugins.xml должна быть следующей:

<plugins>
    <pyqgis_plugin name="Plugin1_Name" version="Plugin1_Version">                 
        <Plugin1_Parameter1_Name>Plugin1_Parameter1_Value</Plugin1_Parameter1_Name>
        <Plugin1_Parameter2_Name>Plugin1_Parameter2_Value</Plugin1_Parameter2_Name>
        ....
        <Plugin1_ParameterN_Name>Plugin1_ParameterN_Value</Plugin1_ParameterN_Name>
    </pyqgis_plugin>
    ...
    <pyqgis_plugin name="PluginN_Name" version="PluginN_Version">
       <PluginN_Parameter1_Name>PluginN_Parameter1_Value</PluginN_Parameter1_Name>
       <PluginN_Parameter2_Name>PluginN_Parameter2_Value</PluginN_Parameter2_Name>
        ....
       <PluginN_ParameterN_Name>PluginN_ParameterN_Value</PluginN_ParameterN_Name>
    </pyqgis_plugin>
</plugins>

Обязательные параметры, без которых работа репозитория может быть нарушена, следующие:

• name – название плагина (указывается как параметр тега pyqgis_plugin),
• version – версия плагина (указывается как параметр тега pyqgis_plugin),
• qgis_minimum_version – минимальная версия QGIS, подходящая для работы с данным плагином,
• download_url – url по которому расположен zip-архив с вашим плагином.

Рекомендуется изучить пример файла plugins.xml из официального репозитория QGIS (цифры в конце ссылки заменить на версию установленного у вас QGIS).

Связь между локальным плагином и плагином в репозитории

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

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

Иными словами, если в описании плагина из plugins.xml, присутствует тег file_name, то из него будет извлечена часть до первой точки (выделена жирным), которая должна быть в точности равна названию корневой папки установленного плагина, чтобы менеджер плагинов QGIS посчитал их одним и тем же плагином.

<file_name>PluginName.2.1.0.zip</file_name>

Если тег file_name отсутствует, то аналогичным образом будет разобран последний элемент пути из тега download_url. Извлеченная из него часть до первой точки (выделена жирным), также должна быть в точности равна названию корневой папки установленного плагина, чтобы менеджер плагинов QGIS посчитал их одним и тем же плагином.

<download_url>YourRepositoryURL/PluginName.2.1.0.zip</download_url>

Если совпадения названия корневой папки и извлеченной части из file_name, либо (если file_name отсутствует) из download_url, не произошло, то плагины считаются разными плагинами.

Учитывая это правило, рекомендуется в описание плагина в файле plugins.xml добавить тег file_name, в котором указать не название вашего zip-архива, а название корневой папки вашего плагина, к которому можно при желании добавить версию или другую информацию, разделив их точкой. В таком случае вы сможете назвать zip-архив с плагином как угодно, в том числе, разделяя название плагина и его версию дефисом, как принято в официальном репозитории.

Примеры корректно оформленных плагинов

Пример 1

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

FolderName.SomeInfo.zip
---FolderName
------__init__.py
------metadata.txt

Файл metadata.txt

[general]
name: PluginName
version: 2.1.0
qgisMinimumVersion: 3.0

Файл plugins.xml

<plugins> 
   <pyqgis_plugin name="PluginName" version="2.1.0">
       <qgis_minimum_version>3.0.0</qgis_minimum_version>
        <download_url>YourRepositoryURL/FolderName.SomeInfo.zip</download_url>
   </pyqgis_plugin>
</plugins>

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

Пример 2

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

ArchiveName.SomeInfo.zip
---FolderName
------__init__.py
------metadata.txt

Файл metadata.txt

[general]
name: PluginName
version: 2.1.0
qgisMinimumVersion: 3.0

Файл plugins.xml

<plugins>
   <pyqgis_plugin name="PluginName" version="2.1.0">
       <qgis_minimum_version>3.0.0</qgis_minimum_version>
        <file_name>FolderName.SomeInfo</file_name>
        <download_url>YourRepositoryURL/ArchiveName.SomeInfo.zip</download_url>
   </pyqgis_plugin>
</plugins>

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

Создание репозитория

Репозиторий плагинов QGIS должен состоять из файла plugins.xml, предоставляющего общую информацию для менеджера плагинов обо всех плагинах, доступных в репозитории и zip-архивах, содержащих сами плагины. Репозиторий может быть размещен на таких веб-сервисах, как GitHub или Bitbucket.

Важным требованием для того, чтобы QGIS распознал такой репозиторий, является доступ к файлам по прямой ссылке. Сделать это можно, к примеру, с помощью Github Pages или Bitbucket Pages. Google Drive или DropBox для этих целей не подойдут, т.к. они не позволяют получить прямую ссылку на файл вида …/filename.extension.

Инструкция, по использованию GitHub для размещения статического веб-сайта, расположена по ссылке.

Инструкция, как использовать Bitbucket для размещения статического веб-сайта, расположена по ссылке.

Как правило, вам всего лишь нужно переименовать ваш репозиторий в соответствии с шаблоном:

username.github.io (для GitHub)
или
username.bitbucket.io (для Bitbucket)

После необходимых настроек ссылка на ваш репозиторий QGIS будет выглядеть следующим образом:

username.github.io/plugins.xml (для GitHub)
или
username.bitbucket.io/plugins.xml (для Bitbucket)

Эту ссылку необходимо указать в поле URL в менеджере плагинов QGIS при подключении нового репозитория. Если подключение к репозиторию пройдет успешно, то статус репозитория примет значение «connected», а в списке доступных плагинов появятся плагины, описанные в файле plugins.xml.