Как стать автором
Обновить

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

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

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

https://plugins.qgis.org/publish/

Releasing your plugin

Примечание 2
Информация, приведенная в статье, актуальна для версии QGIS 3.10.5 LTR.

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


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

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

Ниже приведена таблица, описывающая откуда берутся параметры в окне с информацией о плагине, в каждом из трех случаев:
Параметр в окне с информацией о плагине в менеджере плагинов QGIS
Источник, из которого берется параметр до установки из репозитория
Источник, из которого берется параметр, когда плагин установлен на вашем компьютере и есть связь с репозиторием
Источник, из которого берется параметр, когда плагин установлен на вашем компьютере и связи с репозиторием нет
Name
plugins.xml (свойство name тега pyqgis_plugin)
plugins.xml (свойство name тега pyqgis_plugin)
metadata.txt
Description
plugins.xml
metadata.txt
metadata.txt
About
plugins.xml
metadata.txt
metadata.txt
Installed version
metadata.txt (параметр version)
metadata.txt (параметр version)
Available version
plugins.xml (свойство version тега pyqgis_plugin)
plugins.xml (свойство version тега pyqgis_plugin)
Download url
plugins.xml
plugins.xml
Changelog
metadata.txt
metadata.txt
Tags
plugins.xml
metadata.txt
metadata.txt
Author
plugins.xml
plugins.xml
metadata.txt
Email
metadata.txt
metadata.txt
Homepage
plugins.xml
plugins.xml
metadata.txt
Bug tracker
plugins.xml
plugins.xml
metadata.txt
Code repository
plugins.xml
plugins.xml
metadata.txt
QgisMinimumVersion
plugins.xml
metadata.txt
metadata.txt
QgisMaximumVersion
plugins.xml
metadata.txt
metadata.txt
Experimental
plugins.xml
metadata.txt
metadata.txt
Deprecated
plugins.xml
metadata.txt
metadata.txt
Icon
plugins.xml
metadata.txt
metadata.txt
Category
plugins.xml
plugins.xml
metadata.txt
Дополнительная информация
  • На название, иконку и размещение плагина в меню QGIS, информация из metadata.txt и plugins.xml не влияет. Эти данные указываются в методе initGui() класса вашего плагина.
  • Если Installed version меньше Available version, то QGIS предложит обновить плагин. Если Installed version больше Available version, то QGIS выдаст предупреждение «Installed version of this plugin is higher than any version found in repository». В обоих случаях можно будет обновить плагин, до версии, доступной в репозитории.
  • Перед загрузкой плагина в репозиторий рекомендуется проследить за тем, чтобы версии плагина в metadata.txt и plugins.xml совпадали. В противном случае плагин будет постоянно предлагать обновиться.
  • Параметр Available version берется из plugins.xml из свойства version тега pyqgis_plugin, а не из тега version.
  • Если в metadata.txt и plugins.xml не указать параметры Experimental и Deprecated, то по умолчанию плагин будет считаться не экспериментальным и не устаревшим.
  • Версия вашего экземпляра QGIS должна быть между минимальной (QgisMinimumVersion) и максимальной (QgisMaximumVersion) версиями, указанными в metadata.txt и plugins.xml.
  • Если минимальная версия не указана, то по умолчанию она принимается равной нулю. Если максимальная версия не указана, то за максимальную версию принимается QgisMinimumVersion + 0.99.


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


Каждый плагин в репозитории должен быть упакован в отдельный 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).

Совет
Чтобы получить plugins.xml, сохраните страницу по указанной ссылке у себя на компьютере. Страница сохранится как файл формата xml.

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


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

Не вдаваясь в технические подробности, правило связи плагинов таково: локальный плагин и плагин в репозитории считаются менеджером плагинов 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-архив с плагином как угодно, в том числе, разделяя название плагина и его версию дефисом, как принято в официальном репозитории.

Примечание
В официальном репозитории QGIS именно тег file_name служит для связи локальных плагинов и плагинов в репозитории.

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


Пример 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.
Теги:
Хабы:
Всего голосов 3: ↑3 и ↓0+3
Комментарии0

Публикации

Истории

Ближайшие события

12 – 13 июля
Геймтон DatsDefense
Онлайн
14 июля
Фестиваль Selectel Day Off
Санкт-ПетербургОнлайн
19 сентября
CDI Conf 2024
Москва
24 сентября
Конференция Fin.Bot 2024
МоскваОнлайн