Types¶

This module contains all the types used by this plugin system. It also provides some enums and typeddict that define undocumdent Nicotine+ features. As they are undocumented in by Nicotine+ itself, they may be subject to change in the future.

enum npc.types.LogLevel(value)¶

“Log Levels” for the logger. They just prefix the message with [LEVEL]

DOWNLOAD¶: Log level for download messages

UPLOAD¶: Log level for upload messages

SEARCH¶: Log level for search messages

CHAT¶: Log level for chat messages

CONNECTION¶: Log level for connection messages

MESSAGE¶: Log level for message messages

TRANSFER¶: Log level for transfer messages

MISCELLANEOUS¶: Log level for miscellaneous messages

Member Type:: str

Valid values are as follows:

DEFAULT = <LogLevel.DEFAULT: 'default'>¶

DOWNLOAD = <LogLevel.DOWNLOAD: 'download'>¶

UPLOAD = <LogLevel.UPLOAD: 'upload'>¶

SEARCH = <LogLevel.SEARCH: 'search'>¶

CHAT = <LogLevel.CHAT: 'chat'>¶

CONNECTION = <LogLevel.CONNECTION: 'connection'>¶

MESSAGE = <LogLevel.MESSAGE: 'message'>¶

TRANSFER = <LogLevel.TRANSFER: 'transfer'>¶

MISCELLANEOUS = <LogLevel.MISCELLANEOUS: 'miscellaneous'>¶

The Enum and its members also have the following methods:

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

enum npc.types.LegacyLogLevel(value)¶

Legacy “Log Levels” for the logger of N+ below 3.3.0

Added in version 0.3.6: Fix windowed messages on Nicotine+ < 3.3.0

MESSAGE¶: Log level for message messages

IMPORTANT_INFO¶: Log level for window dialogue messages (always shown)

IMPORTANT_ERROR¶: Log level for window dialogue error messages (always shown)

WINDOW¶: Alias for IMPORTANT_INFO

WINDOW_ERROR¶: Alias for IMPORTANT_ERROR

DOWNLOAD¶: Log level for download messages

UPLOAD¶: Log level for upload messages

SEARCH¶: Log level for search messages

CHAT¶: Log level for chat messages

CONNECTION¶: Log level for connection

Member Type:: str

Valid values are as follows:

MESSAGE = <LegacyLogLevel.MESSAGE: 'message'>¶

IMPORTANT_INFO = <LegacyLogLevel.IMPORTANT_INFO: 'important_info'>¶

IMPORTANT_ERROR = <LegacyLogLevel.IMPORTANT_ERROR: 'important_error'>¶

DOWNLOAD = <LegacyLogLevel.DOWNLOAD: 'download'>¶

UPLOAD = <LegacyLogLevel.UPLOAD: 'upload'>¶

SEARCH = <LegacyLogLevel.SEARCH: 'search'>¶

CHAT = <LegacyLogLevel.CHAT: 'chat'>¶

CONNECTION = <LegacyLogLevel.CONNECTION: 'connection'>¶

TRANSFER = <LegacyLogLevel.TRANSFER: 'transfer'>¶

MISCELLANEOUS = <LegacyLogLevel.MISCELLANEOUS: 'miscellaneous'>¶

The Enum and its members also have the following methods:

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

class npc.types.PluginConfig¶

Plugin configuration via PLUGININFO file

name¶

Name of the plugin

Type:: str

version¶

Version of the plugin

Type:: str

author¶

List of authors of the plugin

Type:: list of str

description¶

Description of the plugin

Type:: str

prefix¶

Prefix for the plugin commands. Not required

Type:: str

repository¶

GitHub repository of the plugin either as a URL or in the format “user/repo”

Type:: str

class npc.types.Readable(*args, **kwargs)¶

Protocol for objects that can be read from.

read(size=-1)¶

Read from the object

Parameters:: size (int) – Number of bytes to read. If not provided, the whole object is read.
Returns:: Read data
Return type:: T

classmethod __subclasshook__(other)¶

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

class npc.types.SettingsDiff¶

Difference between two settings

before¶

Old settings

Type:: Dict

after¶

New settings

Type:: Dict

enum npc.types.SettingType(value)¶

Plugin settings types

INT¶: Text input that only accepts integers Accepts additional parameters: minimum, maximum, stepsize

FLOAT¶: Text input that only accepts floats (2 decimal places) Accepts additional parameters: minimum, maximum, stepsize

BOOL¶: Checkbox input

RADIO¶: Radio button input Accepts additional parameters: options

DROPDOWN¶: Dropdown menu input Accepts additional parameters: options

STR¶: Text input that accepts any string

TEXTVIEW¶: Text input for multiline text

LIST_STRING¶: Extendable list of strings

FILE¶: File input Accepts additional parameters: chooser

Member Type:: str

Valid values are as follows:

INT = <SettingType.INT: 'int'>¶

FLOAT = <SettingType.FLOAT: 'float'>¶

BOOL = <SettingType.BOOL: 'bool'>¶

RADIO = <SettingType.RADIO: 'radio'>¶

DROPDOWN = <SettingType.DROPDOWN: 'dropdown'>¶

STR = <SettingType.STR: 'str'>¶

TEXTVIEW = <SettingType.TEXTVIEW: 'textview'>¶

LIST_STRING = <SettingType.LIST_STRING: 'list string'>¶

FILE = <SettingType.FILE: 'file'>¶

The Enum and its members also have the following methods:

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

npc.types.SettingTypes¶

Union of all setting types

alias of str | int | float | bool | List[str]

npc.types.Settings¶

Dictionary of settings with their names as keys and their values as values.

alias of Dict[str, str | int | float | bool | List[str]]

enum npc.types.FileChooser(value)¶

File chooser types

FILE¶: File chooser for selecting a single file

FOLDER¶: File chooser for selecting a folder

IMAGE¶: File chooser for selecting an image

Member Type:: str

Valid values are as follows:

FILE = <FileChooser.FILE: 'file'>¶

FOLDER = <FileChooser.FOLDER: 'folder'>¶

IMAGE = <FileChooser.IMAGE: 'image'>¶

The Enum and its members also have the following methods:

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

class npc.types.RequiredMetaSetting¶

Required field definition for a setting

description¶

Description of the setting

Type:: str

type¶

Type of the setting

Type:: SettingType

class npc.types.MetaSetting¶

Field definition for a setting

description¶

Description of the setting

Type:: str

type¶

Type of the setting

Type:: SettingType

options¶

Options for SettingType.RADIO and SettingType.DROPDOWN

Type:: list of str

minimum¶

Minimum value for SettingType.INT and SettingType.FLOAT

Type:: int | float

maximum¶

Maximum value for SettingType.INT and SettingType.FLOAT

Type:: int | float

stepsize¶

Step size for SettingType.INT and SettingType.FLOAT

Type:: int | float

chooser¶

File chooser type for SettingType.FILE

Type:: FileChooser

npc.types.MetaSettings¶

Dictionary of settings with their names as keys and their definitions as values.

alias of dict[str, MetaSetting]

npc.types.AnyInputCallback¶

Callback for commands where args get autoparsed

alias of Callable[[…], ReturnCode | None]

npc.types.DefaultCallback¶

Callback function for a command.

Parameters:

args (str) – List of arguments passed to the command as a single string
room (str, optional) – Room name where the command was called
user (str, optional) – User name who called the command

Returns:

ReturnCode or None which is equivalent to ReturnCode.PASS

alias of Callable[[str, str | None, str | None], ReturnCode | None]

enum npc.types.ReturnCode(value)¶

Return codes for command callbacks.

BREAK¶: Don’t give other plugins the event, do let Nicotine+ process it further

ZAP¶: Don’t give other plugins the event, don’t let Nicotine+ process it further

PASS¶: Do give other plugins the event, do let Nicotine+ process it further

Valid values are as follows:

BREAK = <ReturnCode.BREAK: 0>¶

ZAP = <ReturnCode.ZAP: 1>¶

PASS = <ReturnCode.PASS: 2>¶

enum npc.types.CommandGroup(value)¶

Existing command groups.

Command groups are used to group commands together in the command help window (via /help or the ? button).

CHAT¶: Chat commands (e.g. /away)

CHAT_ROOMS¶: Chat room commands (e.g. /join <room>)

PRIVATE_CHAT¶: Private chat commands (e.g. /pm <user>)

USERS¶: User commands (e.g. /buddy <user>)

NETWORK_FILTERS¶: Network filter commands (e.g. /ban <user or ip>)

SHARES¶: Commands for managing shared files / folders (e.g. /rescan [force|rebuild])

SEARCH_FILES¶: Search files commands (e.g. /search <query>)

Member Type:: str

Valid values are as follows:

CHAT = <CommandGroup.CHAT: 'CHAT'>¶

CHAT_ROOMS = <CommandGroup.CHAT_ROOMS: 'CHAT_ROOMS'>¶

PRIVATE_CHAT = <CommandGroup.PRIVATE_CHAT: 'PRIVATE_CHAT'>¶

USERS = <CommandGroup.USERS: 'USERS'>¶

NETWORK_FILTERS = <CommandGroup.NETWORK_FILTERS: 'NETWORK_FILTERS'>¶

SHARES = <CommandGroup.SHARES: 'SHARES'>¶

SEARCH_FILES = <CommandGroup.SEARCH_FILES: 'SEARCH_FILES'>¶

The Enum and its members also have the following methods:

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

enum npc.types.CommandInterface(value)¶

Command interfaces.

Command interfaces are used to specify where a command can be used.

CHATROOM¶: Command can be used in a chatroom.

PRIVATE_CHAT¶: Command can be used in a private chat.

CLI¶: Command can be used in the command line interface.

Member Type:: str

Valid values are as follows:

CHATROOM = <CommandInterface.CHATROOM: 'chatroom'>¶

PRIVATE_CHAT = <CommandInterface.PRIVATE_CHAT: 'private_chat'>¶

CLI = <CommandInterface.CLI: 'cli'>¶

The Enum and its members also have the following methods:

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

class npc.types.CommandRequired¶

Required command fields.

callback¶

Callback function that is called when the command is executed.

Type:: Callback

description¶

Description of the command. Shown in the command help window

Type:: str

class npc.types.Command¶

Command fields.

Note

Parameters are checked for if you use this syntax:

/command <argument> <choice 1|choice 2>

as in the following example:

@command(parameters = ["<argument>", "<choice 1|choice 2>"])
def do_something(self, argument: str, choice: str) -> None:
    ...

Where < indicates that an argument is required and | indicate choices. If | is present and the user didn’t enter one of the choices, he will receive and error message. The same goes for not providing the required amount of arguments (as counted by <).

Note

It’s possible to define a callback for each interface separately. Same as it’s possible to define parameters for each interface separately.

callback¶

Callback function that is called when the command is executed.

Type:: Callback

description¶

Description of the command. Shown in the command help window

Type:: str

aliases¶

List of aliases that can be used to call the command

Type:: list of str

disable¶

List of CommandInterfaces that the command should be disabled for

Type:: list of CommandInterface

group¶

Group used to group the command in the command help window

Type:: str | CommandGroup

parameters¶

List of parameters that are required to call the command in a chatroom. Shown in the command help window

Type:: list of str

parameters_chatroom¶

List of parameters that are required to call the command in a chatroom. Shown in the command help window

Type:: list of str

parameters_private_chat¶

List of parameters that are required to call the command in a private chat. Shown in the command help window

Type:: list of str

parameters_cli¶

List of parameters that are required to call the command in the command line interface. Shown in the command help window

Type:: list of str

callback_chatroom¶

Callback function that is called when the command is executed in a chatroom

Type:: Callback

callback_private_chat¶

Callback function that is called when the command is executed in a private chat

Type:: Callback

callback_cli¶

Callback function that is called when the command is executed in the command line interface

Type:: Callback

npc.types.Commands¶

Dictionary of commands with their names as keys and their definitions as values.

alias of dict[str, Command]

npc.types.LegacyCommands¶

List of tuples with the command name and the callback function for commands.

Type:: Deprecated

alias of List[Tuple[str, Callable[[…], Any]]]

npc.types.Callback¶: alias of Callable[[…], ReturnCode | None] | Callable[[str, str | None, str | None], ReturnCode | None]

npc.types.T = +T¶: Type variable for the return type of the read method.