Plugin

endstone.plugin

Classes relating to loading and managing plugins.

Modules:

Name	Description
plugin_loader

Classes:

Name	Description
Plugin	Represents a Plugin
PluginCommand	Represents a Command belonging to a Plugin.
PluginDescription	Represents the basic information about a plugin that the plugin loader needs to know.
PluginLoadOrder	Represents the order in which a plugin should be initialized and enabled.
PluginLoader	Represents a plugin loader, which handles direct access to specific types of plugins.
PluginManager	Represents a plugin manager that handles all plugins from the Server.
Service	Services represent a list of methods.
ServiceManager	Represent a service manager that manages services and service providers.
ServicePriority	Represents various priorities of a provider.

Plugin

Plugin()

Bases: Plugin

Represents a Plugin

Methods:

Name	Description
get_command	Gets the command with the given name, specific to this plugin.
on_disable	Called when this plugin is disabled
on_enable	Called when this plugin is enabled
on_load	Called after a plugin is loaded but before it has been enabled.
register_events	Registers all events defined in the given listener instance.
reload_config	Returns the plugin's configuration loaded from config.toml.
save_config	Saves the current configuration to the config.toml file.
save_default_config	Saves the default config.toml file to the plugin's data folder.
save_resources	Saves a packaged resource from the plugin module to the data folder.

Attributes:

Name	Type	Description
api_version	str | None
authors	list[str] | None
commands	dict | None
config	dict	Returns the plugin's configuration loaded from config.toml.
contributors	list[str] | None
data_folder	Path	Returns the folder that the plugin data's files are located in.
default_permission	PermissionDefault | None
depend	list[str] | None
description	str | None
is_enabled	bool	Returns a value indicating whether this plugin is currently enabled
load	PluginLoadOrder | None
load_before	list[str] | None
logger	Logger	Returns the plugin logger associated with this server's logger.
name	str	Returns the name of the plugin.
permissions	dict | None
plugin_loader	PluginLoader	Gets the associated PluginLoader responsible for this plugin
prefix	str | None
provides	list[str] | None
server	Server	Returns the Server instance currently running this plugin
soft_depend	list[str] | None
version	str | None
website	str | None

api_version class-attribute instance-attribute

api_version: str | None = None

authors class-attribute instance-attribute

authors: list[str] | None = None

commands class-attribute instance-attribute

commands: dict | None = None

config property

config: dict

Returns the plugin's configuration loaded from config.toml.

Loads and returns the plugin’s configuration data from config.toml. If the configuration has not been loaded yet, it is automatically reloaded using reload_config().

Returns:

Name	Type	Description
dict	dict	The plugin's configuration data.

contributors class-attribute instance-attribute

contributors: list[str] | None = None

data_folder property

data_folder: Path

Returns the folder that the plugin data's files are located in.

default_permission class-attribute instance-attribute

default_permission: PermissionDefault | None = None

depend class-attribute instance-attribute

depend: list[str] | None = None

description class-attribute instance-attribute

description: str | None = None

is_enabled property

is_enabled: bool

Returns a value indicating whether this plugin is currently enabled

load class-attribute instance-attribute

load: PluginLoadOrder | None = None

load_before class-attribute instance-attribute

load_before: list[str] | None = None

logger property

logger: Logger

Returns the plugin logger associated with this server's logger.

name property

name: str

Returns the name of the plugin.

permissions class-attribute instance-attribute

permissions: dict | None = None

plugin_loader property

plugin_loader: PluginLoader

Gets the associated PluginLoader responsible for this plugin

prefix class-attribute instance-attribute

prefix: str | None = None

provides class-attribute instance-attribute

provides: list[str] | None = None

server property

server: Server

Returns the Server instance currently running this plugin

soft_depend class-attribute instance-attribute

soft_depend: list[str] | None = None

version class-attribute instance-attribute

version: str | None = None

website class-attribute instance-attribute

website: str | None = None

get_command

get_command(name: str) -> PluginCommand

Gets the command with the given name, specific to this plugin.

on_disable

on_disable() -> None

Called when this plugin is disabled

on_enable

on_enable() -> None

Called when this plugin is enabled

on_load

on_load() -> None

Called after a plugin is loaded but before it has been enabled.

register_events

register_events(listener: object) -> None

Registers all events defined in the given listener instance.

Parameters:

Name	Type	Description	Default
listener	object	The listener object containing event handler methods to be registered.	required

reload_config

reload_config() -> dict

Returns the plugin's configuration loaded from config.toml.

Loads and returns the plugin’s configuration data from config.toml. If a default configuration file is packaged with the plugin, its values are used as defaults.

Returns:

Name	Type	Description
dict	dict	The plugin's configuration data.

save_config

save_config() -> None

Saves the current configuration to the config.toml file.

save_default_config

save_default_config() -> None

Saves the default config.toml file to the plugin's data folder.

If config.toml does not already exist in the plugin’s data folder, this method copies the default version from the plugin’s packaged resources. If the file already exists, the method does nothing and fails silently.

save_resources

save_resources(path: str, replace: bool = False) -> None

Saves a packaged resource from the plugin module to the data folder.

The method locates a resource bundled within the plugin’s package and copies it to the plugin’s data folder, preserving its relative directory structure. If the target file already exists, it will only be replaced if replace is set to True.

Parameters:

Name	Type	Description	Default
path	str	The relative path to the resource inside the plugin’s package. Directory separators are normalized to forward slashes.	required
replace	bool	Whether to overwrite the existing file if it already exists. Defaults to False.	False

Raises:

Type	Description
FileNotFoundError	If the specified resource cannot be found in the package.
OSError	If an error occurs while copying or creating directories.

PluginCommand

PluginCommand(
    name: str,
    description: str | None = None,
    usages: list[str] | None = None,
    aliases: list[str] | None = None,
    permissions: list[str] | None = None,
    *args,
    **kwargs
)

Bases: Command

Represents a Command belonging to a Plugin.

Attributes:

Name	Type	Description
executor	CommandExecutor	The CommandExecutor to run when parsing this command.
plugin	Plugin	The owner of this PluginCommand.

executor property writable

executor: CommandExecutor

The CommandExecutor to run when parsing this command.

plugin property

plugin: Plugin

The owner of this PluginCommand.

PluginDescription

PluginDescription(
    name: str,
    version: str,
    description: str | None = None,
    load: PluginLoadOrder | None = None,
    authors: list[str] | None = None,
    contributors: list[str] | None = None,
    website: str | None = None,
    prefix: str | None = None,
    provides: list[str] | None = None,
    depend: list[str] | None = None,
    soft_depend: list[str] | None = None,
    load_before: list[str] | None = None,
    default_permission: PermissionDefault | None = None,
    commands: list[Command] | None = None,
    permissions: list[Permission] | None = None,
    *args,
    **kwargs
)

Represents the basic information about a plugin that the plugin loader needs to know.

Attributes:

Name	Type	Description
api_version	str	The API version which this plugin is designed to support.
authors	list[str]	The list of authors for the plugin.
commands	list[Command]	The list of commands the plugin will register at runtime.
contributors	list[str]	The list of contributors for the plugin.
default_permission	PermissionDefault	The default value of permissions registered for the plugin.
depend	list[str]	The list of other plugins that the plugin requires.
description	str	A human-friendly description of the functionality the plugin provides.
full_name	str	A descriptive name of the plugin and respective version.
load	PluginLoadOrder	The phase of server startup that the plugin should be loaded.
load_before	list[str]	The list of plugins that should consider this plugin a soft-dependency.
name	str	The name of the plugin. This name is a unique identifier for plugins.
permissions	list[Permission]	The list of permissions the plugin will register at runtime, immediately proceeding enabling.
prefix	str	The token to prefix plugin-specific logging messages with.
provides	list[str]	The list of other plugin APIs which this plugin provides. These are usable for other plugins to depend on.
soft_depend	list[str]	The list of other plugins that the plugin requires for full functionality.
version	str	The version of the plugin.
website	str	The plugin's or plugin's author's website.

api_version property

api_version: str

The API version which this plugin is designed to support.

authors property

authors: list[str]

The list of authors for the plugin.

commands property

commands: list[Command]

The list of commands the plugin will register at runtime.

contributors property

contributors: list[str]

The list of contributors for the plugin.

default_permission property

default_permission: PermissionDefault

The default value of permissions registered for the plugin.

depend property

depend: list[str]

The list of other plugins that the plugin requires.

description property

description: str

A human-friendly description of the functionality the plugin provides.

full_name property

full_name: str

A descriptive name of the plugin and respective version.

load property

load: PluginLoadOrder

The phase of server startup that the plugin should be loaded.

load_before property

load_before: list[str]

The list of plugins that should consider this plugin a soft-dependency.

name property

name: str

The name of the plugin. This name is a unique identifier for plugins.

permissions property

permissions: list[Permission]

The list of permissions the plugin will register at runtime, immediately proceeding enabling.

prefix property

prefix: str

The token to prefix plugin-specific logging messages with.

provides property

provides: list[str]

The list of other plugin APIs which this plugin provides. These are usable for other plugins to depend on.

soft_depend property

soft_depend: list[str]

The list of other plugins that the plugin requires for full functionality.

version property

version: str

The version of the plugin.

website property

website: str

The plugin's or plugin's author's website.

PluginLoadOrder

Bases: Enum

Represents the order in which a plugin should be initialized and enabled.

Attributes:

Name	Type	Description
POSTWORLD
STARTUP

POSTWORLD class-attribute instance-attribute

POSTWORLD = 1

STARTUP class-attribute instance-attribute

STARTUP = 0

PluginLoader

PluginLoader(server: Server)

Represents a plugin loader, which handles direct access to specific types of plugins.

Methods:

Name	Description
disable_plugin	Disables the specified plugin.
enable_plugin	Enables the specified plugin.
load_plugin	Loads the plugin contained in the specified file.
load_plugins	Loads the plugin contained within the specified directory.

Attributes:

Name	Type	Description
plugin_file_filters	list[str]	A list of all filename filters expected by this PluginLoader.
server	Server	The Server object associated with the PluginLoader.

plugin_file_filters property

plugin_file_filters: list[str]

A list of all filename filters expected by this PluginLoader.

server property

server: Server

The Server object associated with the PluginLoader.

disable_plugin

disable_plugin(plugin: Plugin) -> None

Disables the specified plugin.

Attempting to disable a plugin that is not enabled will have no effect.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin to disable.	required

enable_plugin

enable_plugin(plugin: Plugin) -> None

Enables the specified plugin.

Attempting to enable a plugin that is already enabled will have no effect.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin to enable.	required

load_plugin

load_plugin(file: str) -> Plugin

Loads the plugin contained in the specified file.

Parameters:

Name	Type	Description	Default
file	str	File to attempt to load.	required

Returns:

Type	Description
Plugin	Plugin that was contained in the specified file, or None if unsuccessful.

load_plugins

load_plugins(directory: str) -> list[Plugin]

Loads the plugin contained within the specified directory.

Parameters:

Name	Type	Description	Default
directory	str	Directory to check for plugins.	required

Returns:

Type	Description
list[Plugin]	A list of all plugins loaded.

PluginManager

Represents a plugin manager that handles all plugins from the Server.

Methods:

Name	Description
call_event	Calls an event which will be passed to plugins.
clear_plugins	Disables and removes all plugins.
disable_plugin	Disables the specified plugin.
disable_plugins	Disables all the loaded plugins.
enable_plugin	Enables the specified plugin.
enable_plugins	Enable all the loaded plugins.
get_default_perm_subscriptions	Gets a set containing all subscribed Permissibles to the given default list, by permission level.
get_default_permissions	Gets the default permissions for the given permission level.
get_permission	Gets a Permission from its fully qualified name.
get_permission_subscriptions	Gets a set containing all subscribed Permissibles to the given permission, by name.
get_plugin	Checks if the given plugin is loaded and returns it when applicable.
is_plugin_enabled
load_plugin	Loads the plugin in the specified file.
load_plugins
recalculate_permission_defaults	Recalculates the defaults for the given Permission.
register_event	Registers the given event.
remove_permission
subscribe_to_default_perms	Subscribes to the given Default permissions by permission level.
subscribe_to_permission	Subscribes the given Permissible for information about the requested Permission, by name.
unsubscribe_from_default_perms	Unsubscribes from the given Default permissions by permission level.
unsubscribe_from_permission	Unsubscribes the given Permissible for information about the requested Permission, by name.

Attributes:

Name	Type	Description
permissions	set[Permission]	Set of all registered permissions.
plugins	list[Plugin]	List of all currently loaded plugins.

permissions property

permissions: set[Permission]

Set of all registered permissions.

plugins property

plugins: list[Plugin]

List of all currently loaded plugins.

call_event

call_event(event: Event) -> None

Calls an event which will be passed to plugins.

Parameters:

Name	Type	Description	Default
event	Event	Event to be called.	required

clear_plugins

clear_plugins() -> None

Disables and removes all plugins.

disable_plugin

disable_plugin(plugin: Plugin) -> None

Disables the specified plugin.

Attempting to disable a plugin that is not enabled will have no effect.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin to disable.	required

disable_plugins

disable_plugins() -> None

Disables all the loaded plugins.

enable_plugin

enable_plugin(plugin: Plugin) -> None

Enables the specified plugin.

Attempting to enable a plugin that is already enabled will have no effect.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin to enable.	required

enable_plugins

enable_plugins() -> None

Enable all the loaded plugins.

get_default_perm_subscriptions

get_default_perm_subscriptions(
    level: PermissionLevel,
) -> set[Permissible]

Gets a set containing all subscribed Permissibles to the given default list, by permission level.

Parameters:

Name	Type	Description	Default
level	PermissionLevel	Default list to query for.	required

Returns:

Type	Description
set[Permissible]	Set containing all subscribed permissions.

get_default_permissions

get_default_permissions(
    level: PermissionLevel,
) -> list[Permission]

Gets the default permissions for the given permission level.

Parameters:

Name	Type	Description	Default
level	PermissionLevel	Which set of default permissions to get.	required

Returns:

Type	Description
list[Permission]	The default permissions.

get_permission

get_permission(name: str) -> Permission

Gets a Permission from its fully qualified name.

Parameters:

Name	Type	Description	Default
name	str	Name of the permission.	required

Returns:

Type	Description
Permission	Permission, or None if none.

get_permission_subscriptions

get_permission_subscriptions(
    permission: str,
) -> set[Permissible]

Gets a set containing all subscribed Permissibles to the given permission, by name.

Parameters:

Name	Type	Description	Default
permission	str	Permission to query for.	required

Returns:

Type	Description
set[Permissible]	Set containing all subscribed permissions.

get_plugin

get_plugin(name: str) -> Plugin

Checks if the given plugin is loaded and returns it when applicable.

Please note that the name of the plugin is case-sensitive.

Parameters:

Name	Type	Description	Default
name	str	Name of the plugin to check.	required

Returns:

Type	Description
Plugin	Plugin if it exists, otherwise None.

is_plugin_enabled

is_plugin_enabled(plugin: str) -> bool

is_plugin_enabled(plugin: Plugin) -> bool

load_plugin

load_plugin(file: str) -> Plugin

Loads the plugin in the specified file.

File must be valid according to the current enabled Plugin interfaces.

Parameters:

Name	Type	Description	Default
file	str	File containing the plugin to load.	required

Returns:

Type	Description
Plugin	The Plugin loaded, or None if it was invalid.

load_plugins

load_plugins(directory: str) -> list[Plugin]

load_plugins(files: list[str]) -> list[Plugin]

recalculate_permission_defaults

recalculate_permission_defaults(perm: Permission) -> None

Recalculates the defaults for the given Permission.

This will have no effect if the specified permission is not registered here.

Parameters:

Name	Type	Description	Default
perm	Permission	Permission to recalculate.	required

register_event

register_event(
    name: str,
    executor: Callable[[Event], None],
    priority: EventPriority,
    plugin: Plugin,
    ignore_cancelled: bool,
) -> None

Registers the given event.

Parameters:

Name	Type	Description	Default
name	str	Event name to register.	required
executor	Callable[[Event], None]	EventExecutor to register.	required
priority	EventPriority	Priority of this event.	required
plugin	Plugin	Plugin to register.	required
ignore_cancelled	bool	Do not call executor if event was already cancelled.	required

remove_permission

remove_permission(perm: Permission) -> None

remove_permission(name: str) -> None

subscribe_to_default_perms

subscribe_to_default_perms(
    level: PermissionLevel, permissible: Permissible
) -> None

Subscribes to the given Default permissions by permission level.

If the specified defaults change in any form, the Permissible will be asked to recalculate.

Parameters:

Name	Type	Description	Default
level	PermissionLevel	Default list to subscribe to.	required
permissible	Permissible	Permissible subscribing.	required

subscribe_to_permission

subscribe_to_permission(
    permission: str, permissible: Permissible
) -> None

Subscribes the given Permissible for information about the requested Permission, by name.

If the specified Permission changes in any form, the Permissible will be asked to recalculate.

Parameters:

Name	Type	Description	Default
permission	str	Permission to subscribe to.	required
permissible	Permissible	Permissible subscribing.	required

unsubscribe_from_default_perms

unsubscribe_from_default_perms(
    level: PermissionLevel, permissible: Permissible
) -> None

Unsubscribes from the given Default permissions by permission level.

Parameters:

Name	Type	Description	Default
level	PermissionLevel	Default list to unsubscribe from.	required
permissible	Permissible	Permissible subscribing.	required

unsubscribe_from_permission

unsubscribe_from_permission(
    permission: str, permissible: Permissible
) -> None

Unsubscribes the given Permissible for information about the requested Permission, by name.

Parameters:

Name	Type	Description	Default
permission	str	Permission to unsubscribe from.	required
permissible	Permissible	Permissible subscribing.	required

Service

Service()

Services represent a list of methods.

ServiceManager

Represent a service manager that manages services and service providers.

Services are an interface specifying a list of methods that a provider must implement. Providers are implementations of these services.

Methods:

Name	Description
load	Queries for a provider.
register	Register a provider of a service.
unregister
unregister_all	Unregister all the services registered by a particular plugin.

load

load(name: str) -> Service

Queries for a provider.

This may return None if no provider has been registered for the service. The highest priority provider is returned.

Parameters:

Name	Type	Description	Default
name	str	The service name.	required

Returns:

Type	Description
Service	The highest priority provider, or None if none is registered.

register

register(
    name: str,
    provider: Service,
    plugin: Plugin,
    priority: ServicePriority,
) -> None

Register a provider of a service.

Parameters:

Name	Type	Description	Default
name	str	Service name.	required
provider	Service	Service provider to register.	required
plugin	Plugin	Plugin associated with the service.	required
priority	ServicePriority	Priority of the provider.	required

unregister

unregister(name: str, provider: Service) -> None

unregister(provider: Service) -> None

unregister_all

unregister_all(plugin: Plugin) -> None

Unregister all the services registered by a particular plugin.

Parameters:

Name	Type	Description	Default
plugin	Plugin	The plugin.	required

ServicePriority

Bases: IntEnum

Represents various priorities of a provider.

Attributes:

Name	Type	Description
HIGH
HIGHEST
LOW
LOWEST
NORMAL

HIGH class-attribute instance-attribute

HIGH = 3

HIGHEST class-attribute instance-attribute

HIGHEST = 4

LOW class-attribute instance-attribute

LOW = 1

LOWEST class-attribute instance-attribute

LOWEST = 0

NORMAL class-attribute instance-attribute

NORMAL = 2