sopel.tools.target#

User and channel objects used in state tracking.

class sopel.tools.target.Channel( name: Identifier, identifier_factory: sopel.tools.identifiers.IdentifierFactory = Identifier, )#

A representation of a channel Sopel is in.

Parameters:

name (Identifier) – the channel name
identifier_factory – A factory to create Identifiers

add_user(user: User, privs: int = 0) → None#

Add user to this channel.

Parameters:

user – the new user to add
privs – privilege bitmask (see constants in sopel.privileges.AccessLevel)

Called when a new user JOINs the channel.

clear_user(nick: Identifier) → None#

Remove nick from this channel.

Parameters:: nick – the nickname of the user to remove

Called after a user leaves the channel via PART, KICK, QUIT, etc.

has_privilege(nick: str, privilege: int) → bool#

Tell if a user has a privilege level or above in this channel.

Parameters:

nick – a user’s nick in this channel
privilege – privilege level to check

This method checks the user’s privilege level in this channel, i.e. if it has this level or higher privileges:

>>> channel.add_user(some_user, plugin.OP)
>>> channel.has_privilege(some_user.nick, plugin.VOICE)
True

The nick argument can be either a str or a sopel.tools.identifiers.Identifier. If the user is not in this channel, it will be considered as not having any privilege.

See also

There are other methods to check the exact privilege level of a user, such as is_oper(), is_owner(), is_admin(), is_op(), is_halfop(), and is_voiced().

Important

Not all IRC networks support all privilege levels. If you intend for your plugin to run on any network, it is safest to rely only on the presence of standard modes: +v (voice) and +o (op).

is_admin(nick: str) → bool#

Tell if a user has the ADMIN privilege level.

Parameters:: nick – a user’s nick in this channel

Unlike has_privilege(), this method checks if the user has been explicitly granted the ADMIN privilege level:

>>> channel.add_user(some_user, plugin.ADMIN)
>>> channel.is_admin(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
False

Note that you can always have more than one privilege level:

>>> channel.add_user(some_user, plugin.ADMIN | plugin.VOICE)
>>> channel.is_admin(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
True

Important

Not all IRC networks support this privilege mode. If you are writing a plugin for public distribution, ensure your code behaves sensibly if only +v (voice) and +o (op) modes exist.

is_halfop(nick: str) → bool#

Tell if a user has the HALFOP privilege level.

Parameters:: nick – a user’s nick in this channel

Unlike has_privilege(), this method checks if the user has been explicitly granted the HALFOP privilege level:

>>> channel.add_user(some_user, plugin.HALFOP)
>>> channel.is_halfop(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
False

Note that you can always have more than one privilege level:

>>> channel.add_user(some_user, plugin.HALFOP | plugin.VOICE)
>>> channel.is_halfop(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
True

Important

Not all IRC networks support this privilege mode. If you are writing a plugin for public distribution, ensure your code behaves sensibly if only +v (voice) and +o (op) modes exist.

is_op(nick: str) → bool#

Tell if a user has the OP privilege level.

Parameters:: nick – a user’s nick in this channel

Unlike has_privilege(), this method checks if the user has been explicitly granted the OP privilege level:

>>> channel.add_user(some_user, plugin.OP)
>>> channel.is_op(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
False

Note that you can always have more than one privilege level:

>>> channel.add_user(some_user, plugin.OP | plugin.VOICE)
>>> channel.is_op(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
True

is_oper(nick: str) → bool#

Tell if a user has the OPER (operator) privilege level.

Parameters:: nick – a user’s nick in this channel

Unlike has_privilege(), this method checks if the user has been explicitly granted the OPER privilege level:

>>> channel.add_user(some_user, plugin.OPER)
>>> channel.is_oper(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
False

Note that you can always have more than one privilege level:

>>> channel.add_user(some_user, plugin.OPER | plugin.VOICE)
>>> channel.is_oper(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
True

Important

Not all IRC networks support this privilege mode. If you are writing a plugin for public distribution, ensure your code behaves sensibly if only +v (voice) and +o (op) modes exist.

is_owner(nick: str) → bool#

Tell if a user has the OWNER privilege level.

Parameters:: nick – a user’s nick in this channel

Unlike has_privilege(), this method checks if the user has been explicitly granted the OWNER privilege level:

>>> channel.add_user(some_user, plugin.OWNER)
>>> channel.is_owner(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
False

Note that you can always have more than one privilege level:

>>> channel.add_user(some_user, plugin.OWNER | plugin.VOICE)
>>> channel.is_owner(some_user.nick)
True
>>> channel.is_voiced(some_user.nick)
True

Important

Not all IRC networks support this privilege mode. If you are writing a plugin for public distribution, ensure your code behaves sensibly if only +v (voice) and +o (op) modes exist.

is_voiced(nick: str) → bool#

Tell if a user has the VOICE privilege level.

Parameters:: nick – a user’s nick in this channel

Unlike has_privilege(), this method checks if the user has been explicitly granted the VOICE privilege level:

>>> channel.add_user(some_user, plugin.VOICE)
>>> channel.is_voiced(some_user.nick)
True
>>> channel.add_user(some_user, plugin.OP)
>>> channel.is_voiced(some_user.nick)
False

Note that you can always have more than one privilege level:

>>> channel.add_user(some_user, plugin.VOICE | plugin.OP)
>>> channel.is_voiced(some_user.nick)
True
>>> channel.is_op(some_user.nick)
True

join_time: datetime.datetime | None#

The time the server acknowledged our JOIN message.

Based on server-reported time if the server-time IRCv3 capability is available, otherwise the time Sopel received it.

last_who: datetime.datetime | None#: The last time a WHO was requested for the channel.

make_identifier: IdentifierFactory#

Factory to create Identifier.

Identifier is used for User’s nick, and the channel needs to translate nicks from string to Identifier when manipulating data associated to a user by its nickname.

modes: dict[str, set | str | bool]#

The channel’s modes.

For type A modes (nick/address list), the value is a set. For type B (parameter) or C (parameter when setting), the value is a string. For type D, the value is True.

Note

Type A modes may only contain changes the bot has observed. Sopel does not automatically populate all modes and lists.

name: Identifier#: The name of the channel.

privileges: dict[Identifier, int]#

The permissions of the users in the channel.

This maps nickname Identifiers to bitwise integer values. This can be compared to appropriate constants from sopel.privileges.AccessLevel.

rename_user( old: Identifier, new: Identifier, ) → None#

Rename a user.

Parameters:

old – the user’s old nickname
new – the user’s new nickname

Called on NICK events.

topic: str#: The topic of the channel.

users: dict[Identifier, User]#

The users in the channel.

This maps nickname Identifiers to User objects.

class sopel.tools.target.User( nick: Identifier, user: str | None, host: str | None, )#

A representation of a user Sopel is aware of.

Parameters:

nick (sopel.tools.identifiers.Identifier) – the user’s nickname
user (str) – the user’s local username (“user” in user@host.name)
host (str) – the user’s hostname (“host.name” in user@host.name)

account: str | None#

The IRC services account of the user.

This relies on IRCv3 account tracking being enabled.

Will be None if the user is not logged into an account (including when account tracking is not supported by the IRC server.)

away: bool | None#

Whether the user is marked as away.

Will be None if the user’s current away state hasn’t been established yet (via WHO or other means such as away-notify).

channels: dict[Identifier, 'Channel']#

The channels the user is in.

This maps channel name Identifiers to Channel objects.

host: str | None#

The user’s hostname.

Will be None if Sopel has not yet received complete user information from the IRC server.

property hostmask: str#: The user’s full hostmask (nick!user@host).

is_bot: bool | None#

Whether the user is flagged as a bot.

Will be None if the user hasn’t yet been WHOed, or if the IRC server does not support a ‘bot’ user mode.

nick: Identifier#: The user’s nickname.

realname: str | None#

The user’s realname.

Will be None if Sopel has not yet received complete user information from the IRC server.

user: str | None#

The user’s local username.

Will be None if Sopel has not yet received complete user information from the IRC server.