Перейти к содержанию

Разработка плагинов

Руководство по разработке плагинов

Только начинаете работу с плагинами? Ознакомьтесь с нашим Руководством по плагинам NetBox на GitHub! Это углублённое руководство проведёт вас через процесс создания полноценного плагина с нуля. Оно даже включает сопутствующий репозиторий демо-плагина, чтобы вы могли присоединиться на любом этапе. Это поможет вам быстро начать работу с плагинами!

Программа сертификации плагинов

NetBox Labs предлагает Программу сертификации плагинов для разработчиков плагинов, заинтересованных в установлении отношений со-мейнтейнера. Программа направлена на обеспечение постоянной совместимости, поддерживаемости и коммерческой поддержки ключевых плагинов.

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

Разработка на Django

Django — это Python-фреймворк, на котором построен InfraVision. Поскольку сам Django очень хорошо документирован, эта документация охватывает только аспекты разработки плагинов, уникальные для InfraVision.

Плагины могут делать многое, включая:

  • Создавать модели Django для хранения данных в базе данных
  • Предоставлять собственные "страницы" (представления) в веб-интерфейсе
  • Внедрять контент шаблонов и ссылки навигации
  • Расширять REST и GraphQL API InfraVision
  • Загружать дополнительные приложения Django
  • Добавлять пользовательское middleware запросов/ответов

Однако имейте в виду, что каждая часть функциональности полностью опциональна. Например, если ваш плагин просто добавляет middleware или точку API для существующих данных, нет необходимости определять какие-либо новые модели.

Внимание

Хотя API плагинов InfraVision очень мощный, он обязательно ограничен в своей области. API плагинов обсуждается здесь полностью: любая часть кодовой базы InfraVision, не задокументированная здесь, не является частью поддерживаемого API плагинов и не должна использоваться плагином. Внутренние элементы InfraVision могут изменяться в любое время и без предупреждения. Авторам плагинов настоятельно рекомендуется разрабатывать плагины, используя только официально поддерживаемые компоненты, обсуждаемые здесь, и те, что предоставлены базовым фреймворком Django, чтобы избежать критических изменений в будущих релизах.

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

Хотя конкретная структура плагина в значительной степени оставлена на усмотрение его авторов, типичный плагин InfraVision может выглядеть примерно так:

project-name/
  - plugin_name/
    - api/
      - __init__.py
      - serializers.py
      - urls.py
      - views.py
    - migrations/
      - __init__.py
      - 0001_initial.py
      - ...
    - templates/
      - plugin_name/
        - *.html
    - __init__.py
    - filtersets.py
    - graphql.py
    - jobs.py
    - models.py
    - middleware.py
    - navigation.py
    - signals.py
    - tables.py
    - template_content.py
    - urls.py
    - views.py
  - pyproject.toml
  - README.md

Верхний уровень — это корень проекта, который может иметь любое имя, которое вам нравится. Непосредственно внутри корня должны находиться несколько элементов:

  • pyproject.toml — стандартный файл конфигурации, используемый для установки пакета плагина в среду Python.
  • README.md — краткое введение в ваш плагин, как его установить и настроить, где найти помощь и любую другую релевантную информацию. Рекомендуется писать файлы README, используя язык разметки, такой как Markdown, для удобного отображения.
  • Каталог исходного кода плагина. Это должно быть допустимое имя пакета Python, обычно состоящее только из строчных букв, цифр и подчёркиваний.

Каталог исходного кода плагина содержит весь фактический код Python и другие ресурсы, используемые вашим плагином. Его структура оставлена на усмотрение автора; однако рекомендуется следовать лучшим практикам, изложенным в документации Django. Как минимум, этот каталог должен содержать файл __init__.py, содержащий экземпляр класса PluginConfig InfraVision, обсуждаемый ниже.

Примечание: Cookiecutter NetBox Plugin может использоваться для автоматической генерации всех необходимых каталогов и файлов для нового плагина.

PluginConfig

Класс PluginConfig — это специфичная для InfraVision обёртка вокруг встроенного класса Django AppConfig. Он используется для объявления функциональности плагина InfraVision внутри пакета Python. Каждый плагин должен предоставить собственный подкласс, определяющий его имя, метаданные, а также параметры конфигурации по умолчанию и обязательные параметры. Пример приведён ниже:

from netbox.plugins import PluginConfig

class FooBarConfig(PluginConfig):
    name = 'foo_bar'
    verbose_name = 'Foo Bar'
    description = 'Пример плагина InfraVision'
    version = '0.1'
    author = 'Jeremy Stretch'
    author_email = 'author@example.com'
    base_url = 'foo-bar'
    required_settings = []
    default_settings = {
        'baz': True
    }
    django_apps = ["foo", "bar", "baz"]

config = FooBarConfig

InfraVision ищет переменную config в файле __init__.py плагина для загрузки его конфигурации. Обычно она устанавливается в подкласс PluginConfig, но вы можете захотеть динамически генерировать класс PluginConfig на основе переменных окружения или других факторов.

Атрибуты PluginConfig

Имя Описание
name Исходное имя плагина; совпадает с каталогом исходного кода плагина
verbose_name Человекочитаемое имя плагина
version Текущий релиз (семантическое версионирование рекомендуется)
release_track Альтернативный трек релиза (например, dev или beta), к которому принадлежит релиз
description Краткое описание назначения плагина
author Имя автора плагина
author_email Публичный email автора
base_url Базовый путь для URL плагина (опционально). Если не указан, будет использоваться name проекта.
required_settings Список параметров конфигурации, которые должны быть определены пользователем
default_settings Словарь параметров конфигурации и их значений по умолчанию
django_apps Список дополнительных приложений Django для загрузки вместе с плагином
min_version Минимальная версия InfraVision, с которой плагин совместим
max_version Максимальная версия InfraVision, с которой плагин совместим
middleware Список классов middleware для добавления после встроенного middleware InfraVision
queues Список пользовательских очередей фоновых задач для создания
events_pipeline Список обработчиков для добавления в EVENTS_PIPELINE, указанных путями с точками
search_extensions Путь с точками к списку классов индексов поиска (по умолчанию: search.indexes)
data_backends Путь с точками к списку классов бэкендов источников данных (по умолчанию: data_backends.backends)
template_extensions Путь с точками к списку классов расширений шаблонов (по умолчанию: template_content.template_extensions)
menu_items Путь с точками к списку пунктов меню, предоставляемых плагином (по умолчанию: navigation.menu_items)
graphql_schema Путь с точками к классу схемы GraphQL плагина, если есть (по умолчанию: graphql.schema)
user_preferences Путь с точками к словарю сопоставления пользовательских предпочтений, определённых плагином (по умолчанию: preferences.preferences)

Все обязательные настройки должны быть настроены пользователем. Если параметр конфигурации указан как в required_settings, так и в default_settings, настройка по умолчанию будет проигнорирована.

Доступ к параметрам конфигурации

К параметрам конфигурации плагина можно получить доступ с помощью функции get_plugin_config(). Например:

from netbox.plugins import get_plugin_config
get_plugin_config('my_plugin', 'verbose_name')

Важные примечания о django_apps

Загрузка дополнительных приложений может принести больше вреда, чем пользы, и может затруднить выявление проблем в самом InfraVision. Атрибут django_apps предназначен только для продвинутых случаев использования, требующих более глубокой интеграции с Django.

Приложения из этого списка вставляются перед PluginConfig плагина в определённом порядке. Добавление модуля PluginConfig плагина в этот список меняет это поведение и позволяет загружать приложения после плагина.

Любые дополнительные приложения должны быть установлены в той же среде Python, что и InfraVision, иначе при загрузке плагина будут возникать исключения ImproperlyConfigured.

Создание pyproject.toml

pyproject.toml — это файл конфигурации, используемый для упаковки и установки нашего плагина после его завершения. Он используется инструментами упаковки, а также другими инструментами. Основная функция этого файла — вызвать систему сборки для создания дистрибутивного пакета Python. Мы можем передать ряд именованных аргументов для управления созданием пакета, а также для предоставления метаданных о плагине. В этом файле возможны три TOML-таблицы:

  • [build-system] позволяет объявить, какой бэкенд сборки вы используете и какие другие зависимости (если есть) необходимы для сборки вашего проекта.
  • [project] — формат, который большинство бэкендов сборки используют для указания базовых метаданных вашего проекта, таких как имя автора, URL проекта и т.д.
  • [tool] имеет подтаблицы для конкретных инструментов, например, [tool.black], [tool.mypy]. Обратитесь к документации конкретного инструмента для справки.

Пример pyproject.toml приведён ниже:

# См. PEP 518 для спецификации этого файла
# https://www.python.org/dev/peps/pep-0518/

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name =  "my-example-plugin"
version = "0.1.0"
authors = [
    {name = "John Doe", email = "test@netboxlabs.com"},
]
description = "Пример плагина InfraVision."
readme = "README.md"

classifiers=[
    'Development Status :: 3 - Alpha',
    'Intended Audience :: Developers',
    'Natural Language :: English',
    "Programming Language :: Python :: 3 :: Only",
    'Programming Language :: Python :: 3.10',
    'Programming Language :: Python :: 3.11',
    'Programming Language :: Python :: 3.12',
]

requires-python = ">=3.10.0"

Многие из них самоочевидны, но для получения дополнительной информации см. документацию pyproject.toml.

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

Настоятельно рекомендуется создать Python виртуальное окружение для разработки вашего плагина, в отличие от использования общесистемных пакетов. Это даст вам полный контроль над установленными версиями всех зависимостей и позволит избежать конфликтов с системными пакетами. Это окружение может находиться где угодно; однако оно должно быть исключено из системы контроля версий. (Популярное соглашение — хранить все виртуальные окружения в домашнем каталоге пользователя, например, ~/.virtualenvs/.)

python3 -m venv ~/.virtualenvs/my_plugin

Вы можете сделать InfraVision доступным в этом окружении, создав файл пути, указывающий на его расположение. Это добавит InfraVision в путь Python при активации. (Обязательно настройте команду ниже, указав фактический путь к виртуальному окружению, версию Python и установку InfraVision.)

echo /opt/netbox/netbox > $VENV/lib/python3.10/site-packages/netbox.pth

Установка для разработки

Для облегчения разработки рекомендуется установить плагин на этом этапе, используя режим develop setuptools. Это создаст символические ссылки в вашей среде Python на каталог разработки плагина. Вызовите pip из корневого каталога плагина с флагом -e:

$ pip install -e .

Больше информации о редактируемых сборках можно найти в Editable installs for pyproject.toml.

Настройка InfraVision

Чтобы включить плагин в InfraVision, добавьте его в параметр PLUGINS в configuration.py:

PLUGINS = [
    'my_plugin',
]