Nicotine+ Plugin Core

The “Nicotine+ Plugin Core” is a library that provides a set of tools to help you develop plugins for the Nicotine+ client.

Nicotine+ is written in Python and uses GTK+. It has built-in plugin support, but it’s not very well documented and not very user-friendly. This library aims to make it easier to develop plugins for Nicotine+.

Note

It’s noteworthy that this module will sit in your plugin code. It’s not possible to install packages into Nicotine+ itself. This is a limitation of the client. Follow the installation guide to see how to install this package into your plugin.

Notable Features

  • Easy to use

  • Fully typed

  • Configuration management

  • Automatic update checks

  • Reloadable

  • Easy command system

  • Fully documented

Example

Here is a small example of how to use the library to create a plugin:

from npc import BasePlugin, TextArea, command

class Plugin(BasePlugin):
   class Config(BasePlugin.Config):
      hello_text = TextArea("Hello World!")

   @command
   def hello(self) -> None:
      """Say hello to the world."""
      self.window_log(self.config.hello_text)

With this code, you already have a working plugin that will open a window and print “Hello World!” in it when running /hello in the chat.

As you can also see, I added an ease-of-use class npc.BaseConfig that will help you to manage your configuration. This class will automatically create the corresponding settings and metasettings configurations needed for Nicotine+. It’s also typed, so while you use npc.TextArea(), npc.Int(), or any other field, you get the correct type such as str, int in this case.

Warning

It’s important to note that if you want to change the configuration programmatically, you must use npc.BaseConfig.apply() to persist the changes. By default, Nicotine+ will ignore configuration changes made through code. npc.BaseConfig.apply() will make sure that the changes are updated behind the scenes in Nicotine+.

I strongly recommend that you type your code using mypy. This will help you avoid many errors and make your code more robust. Of course, this package is fully typed.

Check out npc.BasePlugin for more information on how to create a plugin and npc.command() for more information on how to create commands.

Update Feature

In addition to the default PLUGININFO file information that Nicotine+ requires from you (that would be the name, version, author, description), you can also provide prefix and repository. The prefix will be added to all commands of the plugin to prevent conflicts with other plugins.

The repository is a link to the repository of the plugin. If this is given, the plugin will automatically check and notify the user if there is a new version available.

Note

As of now, this library only supports GitHub repositories. It will not check other resources such as GitLab or Bitbucket for updates.

Requirements

This package requires Python 3.9 or higher.