Plugin Base¶

This module provides the base class for plugins

This module provides a base class for plugins to inherit from. It provides a few helper functions and properties to make plugin development easier. The plugin class should inherit from this class.

Some default functionality that is provided by the BasePlugin class:

Check for updates
Logging with the plugin name
Settings change detection
Automatic command setup
Plugin reloading with /reload

class npc.BasePlugin(*args, **kwargs)¶

Base class for plugins

To set the settings for the plugin, you can use the provided BaseConfig class. It’s best to inherit from the BasePlugins existing BasePlugin.Config, to ensure that default configuration, such as the update check and interval, is available. You can also add custom settings to the configuration class.

Note

BasePlugin.metasettings and BasePlugin.settings are built automatically from the given BasePlugin.Config. They should not be overridden.

Example

from npc import BasePlugin, Bool, Int, command

class Plugin(BasePlugin):
    class Config(BasePlugin.Config):
        setting1 = Bool("Setting 1", True)
        setting2 = Int("Setting 2", 10)

    @command(parameters=["<name>", "<age>"])
    def hello(self, name: str, age: int) -> None:
        """Hello command"""
        self.window(f"Hello {name}, you are {age} years old", title="Welcome")

Removed in version 0.2.0: Removed npc.BasePlugin.vlog() in favour of the npc.BasePlugin.log logger instance. Use self.log.debug(...) instead.

Removed in version 0.4.1: Removed npc.BasePlugin.__name__() in favour of npc.BasePlugin.plugin_name.

settings¶

Plugin settings dictionary. Don’t override this by yourself. It’s automatically built from the settings in the BasePlugin.Config.

Type:: npc.types.Settings

metasettings¶

Plugin meta settings dictionary. Don’t override this by yourself. It’s automatically built from the settings in the BasePlugin.Config.

Type:: npc.types.MetaSettings

config¶

Plugin configuration instance of the class BasePlugin.Config.

Type:: BaseConfig

plugin_config¶

Information about the plugin itself, such as the name, version and authors.

Type:: npc.types.PluginConfig

auto_update¶

Periodic job for checking if the plugin is up to date. It runs the BasePlugin._automatic_update_check() function every BasePlugin.Config.check_update_interval seconds.

Type:: npc.PeriodicJob

settings_watcher¶

Periodic job for watching changes in the settings. It runs the BasePlugin.detect_settings_change() function every second.

Type:: npc.PeriodicJob

commands¶

Dictionary of commands. Don’t override this it is built automatically. Use the npc.command() decorator to add commands to the plugin.

Type:: npc.types.Commands

__publiccommands__¶

Deprecated: Legacy list of public commands. Use BasePlugin.commands instead.

Type:: npc.types.LegacyCommands

__privatecommands__¶

Deprecated: Legacy list of private commands. Use BasePlugin.commands instead.

Type:: npc.types.LegacyCommands

log¶

Logger instance for the plugin. It’s named after the plugin name.

Changed in version 0.2.0: Replaced npc.BasePlugin.log() function with npc.BasePlugin.log logger instance. Use self.log.info(...) instead of self.log(...).

Type:: logging.Logger

class Config(plugin)¶

Default configuration for plugins made with BasePlugin

The default configuration includes settings for checking for updates and the update check interval. You can add your own settings by inheriting from this class and adding your own settings.

check_update¶

Check for updates

Type:: Bool

check_update_interval¶

Update check interval in minutes

Type:: Int

preview_versions¶

Check for preview versions

Type:: Bool

verbose¶

Verbose logging

Type:: Bool

init()¶

Init after loading user settings

This function is called after the user settings are loaded. It’s a good place to do any setup that requires the user settings to be loaded.

help()¶

Show help for the plugin commands

_setup_commands()¶

Setup commands from methods decorated with @command

Changed in version 0.3.5: Add support for Nicotine+ < 3.3.0 legacy command system

property plugin_identifier: str¶

Return the plugin path name which is the internal identifier

Added in version 0.4.1: Added plugin identifier

Returns:: Plugin identifier
Return type:: str

property plugin_name: str¶: Return the plugin name

verbose()¶

Toggle verbose logging

reload()¶

Reload the plugin

check_update()¶

Check for updates

Changed in version 0.3.6: Show window if no updates are available

Changed in version 0.5.0: Always show the update window not only on the first run

update_available(old_version, new_version, context={})¶

Override this function to handle an available update

Note

This is run before any window is shown to the user about the update.

Added in version 0.5.0: Hook to handle available updates for plugins that need it

Parameters:

old_version (Version) – Current version
new_version (Version) – New version
context (dict, optional) – Additional information about the update

_gh_user_repo()¶

Return the GitHub user and repository

Returns:: GitHub user and repository
Return type:: tuple of str
Raises:: ValueError – If the repository URL is invalid or not set

_gh_api_releases_url()¶

Return the GitHub release URL for a version

Returns:: GitHub release URL
Return type:: str
Raises:: ValueError – If the repository URL is invalid or not set

_automatic_update_check_delay()¶

Return the delay for the automatic update check

Changed in version 0.4.2: Fix automatic update delay not reflected when changing the interval

Returns:: Delay in seconds
Return type:: int

_automatic_update_check()¶

Automatic update check function

This function is called by the BasePlugin.auto_update job to check for updates. It calls the BasePlugin._check_update() function and shows a window if an update is available.

_show_update_window(old_version, new_version)¶

Show a window with the available update

Parameters:

old_version (Version) – Current version
new_version (Version, optional) – New version or None if no update is available

_check_update(check_prerelease=False, context={})¶

Actual update check implementation

Parameters:

check_prerelease (bool, optional) – Check for pre releases versions. Defaults to False.
context (dict, optional) – Additional information to pass to the update hook

Returns:

Current version and new version if available

Return type:

tuple of Version, Version

stop()¶

Stop the plugin and clean up

Changed in version 0.4.1: Fix unloading of modules

Changed in version 0.5.0: Stop all running periodic jobs (incl. ones not created by the base plugin)

shutdown_notification()¶

Notification that the plugin is being shutdown

disable()¶

Disable the plugin

_settings_to_set(settings)¶

Convert settings to a set of tuples

Note

List values are converted to tuples to be hashable and comparable

Parameters:: settings (npc.types.Settings) – Settings to convert (before or after)
Returns:: Set of tuples of settings key-value pairs
Return type:: set of tuple

_set_to_settings(set_)¶

Convert a set of tuples to settings

Note

Tuples are converted to lists to match the settings format

Parameters:: set_ (set of tuple) – Set of tuples of settings key-value pairs
Returns:: Settings dictionary
Return type:: npc.types.Settings

detect_settings_change()¶

Detect changes in settings and call settings_changed if there are any

Note

This function is called periodically to detect changes in settings. If there are any changes, the settings_changed function is called with the before and after settings and the changes.

set_log_level(level)¶

Set plugin and adjacent logging levels

Parameters:: level (str | int) – Logging level to set

settings_changed(before, after, change)¶

Called when settings are changed

This function is called when settings are changed. It’s a good place to react to settings changes. The default implementation logs the changes and updates the log level if the verbose setting is changed.

Changed in version 0.3.4: Fixed still logging debug messages when verbose is disabled

Changed in version 0.5.0: Also adjust logging for periodic jobs

Parameters:

before (npc.types.Settings) – Complete settings before the change
after (npc.types.Settings) – Complete settings after the change
change (npc.types.SettingsDiff) – Dictionary of changes in the settings

window(message, title=None)¶

Open a window with a message

Changed in version 0.2.0: Renamed from npc.BasePlugin.window_log() to npc.BasePlugin.window()

The title will be prefixed with the plugin name or if not provided, the plugin name will be used as the title.

Parameters:

message (str) – Message to be shown in the window
title (str, optional) – Title of the window. Defaults to the plugin name.