Capability Negotiation#

Management of IRC capability negotiation.

New in version 8.0.

This module contains the Capabilities class which tracks the state of the capability negotiation with the IRC server: it can store and update the state of available and enabled capabilities.

Important

Plugin authors should not instantiate this class directly, as the bot exposes an instance through its capabilities attribute.

All state handling methods (such as Capabilities.handle_ls()) are used by the coretasks plugin, and should not be used outside.

class sopel.irc.capabilities.Capabilities#

Capabilities negotiated with the server.

This stores a representation of the capability negotiation state between the bot and the server: it stores the list of available and enabled capabilities, and can track the state by handling various CAP subcommands:

handle_ls() for CAP LS
handle_ack() for CAP ACK
handle_nak() for CAP NAK
handle_new() for CAP NEW
handle_del() for CAP ADD

property available: dict[str, str | None]#

Dict of available server capabilities.

Each key is the name of a capability advertised by the server, and each value is the parameters as advertised (if any) for this capability.

If a capability is not in this dict, it means the server doesn’t advertise it, and it cannot be requested.

property enabled: frozenset[str]#

Set of enabled server capabilities.

Each element is the name of a capability that is enabled on the server.

get_capability_info( name: str, ) → CapabilityInfo#

Retrieve metadata about a capability.

The returned CapabilityInfo will tell if the capability is advertised by the server; and if so, its parameters and whether it is enabled.

If the capability is unknown, then its available attribute will be False, and its params attribute will be None.

handle_ack(bot: SopelWrapper, trigger: Trigger) → tuple[str, ...]#

Handle a CAP ACK command.

This method behaves as a plugin callable with its bot and trigger arguments, with the precise goals to handle CAP ACK command only, registering enabled or disabled capabilities and tracking acknowledgement.

Then it returns the list of acknowledged capability requests.

handle_del(bot: SopelWrapper, trigger: Trigger) → tuple[str, ...]#

Handle a CAP DEL command.

This method behaves as a plugin callable with its bot and trigger arguments, with the precise goals to handle CAP DEL command only.

It registers which capabilities are not available and not enabled anymore, then returns this list.

handle_ls(bot: SopelWrapper, trigger: Trigger) → bool#

Handle a CAP LS command.

This method behaves as a plugin callable with its bot and trigger arguments, with the precise goals to handle CAP LS command only, registering available capabilities.

Then it returns if there is no more LS command to handle (in case of multi-line LS).

handle_nak(bot: SopelWrapper, trigger: Trigger) → tuple[str, ...]#

Handle a CAP NAK command.

This method behaves as a plugin callable with its bot and trigger arguments, with the precise goals to handle CAP NAK command only.

Then it returns the list of denied capability requests.

handle_new(bot: SopelWrapper, trigger: Trigger) → tuple[str, ...]#

Handle a CAP NEW command.

This method behaves as a plugin callable with its bot and trigger arguments, with the precise goals to handle CAP NEW command only.

It registers which new capabilities are available, then returns this list.

is_available(name: str) → bool#: Tell if the capability name is available on the server.

is_enabled(name: str) → bool#: Tell if the capability name is enabled on the server.

class sopel.irc.capabilities.CapabilityInfo#

Capability metadata.

This contains the details of a capability: if available, enabled, and its params (if advertised).

Note

You can get a capability’s info through Capabilities.get_capability_info().

available: bool#

Flag to tell if the server advertises this capability or not.

This is True if the CAP LS subcommand contains the capability.

enabled: bool#: Flag to tell if the capability is enabled on the server.

name: str#

Name of the capability.

The name of a capability is the name as it appears in the CAP LS subcommand, such as multi-prefix or sasl.

params: str | None#

Advertised parameters for this capability.

When a server supports CAP version 302, capabilities can have parameters. The format and the meaning of the parameters depend on the capability itself.

For example, the sasl capability can provide the list of SASL mechanisms the server supports, such as PLAIN,EXTERNAL.