sopel.tools.identifiers#

Identifier tools to represent IRC names (nick or channel).

Nick and channel are defined by their names, which are “identifiers”: their names are used to differentiate users from each others, channels from each others. To ensure that two channels or two users are the same, their identifiers must be processed to be compared properly. This process depends on which RFC and how that RFC is implemented by the server: IRC being an old protocol, different RFCs have different versions of that process:

RFC 1459 § 2.2: ASCII characters, and []\ are mapped to {}|
RFC 2812 § 2.2: same as in the previous RFC, adding ~ mapped to ^

Then when ISUPPORT was added, the CASEMAPPING parameter was defined so the server can say which process to apply:

ascii: only [A-Z] must be mapped to [a-z] (implemented by ascii_lower())
rfc1459: follows RFC 2812, because of how it was implemented in most servers (implemented by rfc1459_lower())
A strict version of RFC 1459 also exists but it is not recommended (implemented by rfc1459_strict_lower())

As a result, the Identifier class requires a casemapping function, which should be provided by the bot.

See also

The bot’s make_identifier method should be used to instantiate an Identifier to honor the CASEMAPPING parameter.

sopel.tools.identifiers.Casemapping#

Type definition of a casemapping callable.

alias of Callable[[str], str]

class sopel.tools.identifiers.Identifier( identifier: str, *, casemapping: sopel.tools.identifiers.Casemapping = rfc1459_lower, chantypes: tuple = DEFAULT_CHANTYPES, )#

A str subclass which acts appropriately for IRC identifiers.

Parameters:

identifier – IRC identifier
casemapping – a casemapping function (optional keyword argument)

When used as normal str objects, case will be preserved. However, when comparing two Identifier objects, or comparing an Identifier object with a str object, the comparison will be case insensitive.

This case insensitivity uses the provided casemapping function, following the rules for the CASEMAPPING parameter from ISUPPORT. By default, it uses rfc1459_lower(), following RFC 2812 § 2.2.

Note

To instantiate an Identifier with the appropriate casemapping function, it is best to rely on bot.make_identifier.

Changed in version 8.0: The casemapping and chantypes parameters have been added.

static _lower(identifier: str) → str#

Convert an identifier to lowercase per RFC 2812.

Parameters:: identifier – the identifier (nickname or channel) to convert
Returns:: RFC 2812-compliant lowercase version of identifier

Changed in version 8.0: Previously, this would lower all non-ASCII characters. It now uses a strict implementation of the CASEMAPPING parameter. This is now equivalent to call rfc1459_lower().

If the identifier is an instance of Identifier, this will call that identifier’s lower() method instead.

static _lower_swapped(identifier: str) → str#

Backward-compatible version of _lower().

Parameters:: identifier – the identifier (nickname or channel) to convert
Returns:: RFC 2812-non-compliant lowercase version of identifier

This is what the old _lower() function did before Sopel 7.0. It maps {}, [], |, \, ^, and ~ incorrectly.

You shouldn’t use this unless you need to migrate stored values from the previous, incorrect “lowercase” representation to the correct one.

casemapping: sopel.tools.identifiers.Casemapping#: Casemapping function to lower the identifier.

chantypes#: Tuple of prefixes used for channels.

is_nick() → bool#

Check if the Identifier is a nickname (i.e. not a channel)

Returns:: True if this Identifier is a nickname; False if it appears to be a channel

>>> from sopel import tools
>>> ident = tools.Identifier('Sopel')
>>> ident.is_nick()
True
>>> ident = tools.Identifier('#sopel')
>>> ident.is_nick()
False

To detect channels, chantypes is used:

>>> from sopel import tools
>>> ident = tools.Identifier('!sopel', chantypes=('#', '&'))
>>> ident.is_nick()
True
>>> ident.chantypes = ('#', '&', '!')
>>> ident.is_nick()
False

lower() → str#

Get the IRC-compliant lowercase version of this identifier.

Returns:: IRC-compliant lowercase version used for case-insensitive comparisons

The behavior of this method depends on the identifier’s casemapping function, which should be selected based on the CASEMAPPING parameter from ISUPPORT.

Changed in version 8.0: Now uses the casemapping function to lower the identifier.

sopel.tools.identifiers.IdentifierFactory#

Type definition of an identifier factory.

alias of Callable[[str], Identifier]

sopel.tools.identifiers.ascii_lower(text: str) → str#

Lower text according to the ascii value of CASEMAPPING.

In that version, only [A-Z] are to be mapped to their lowercase equivalent ([a-z]). Non-ASCII characters are kept unmodified.

sopel.tools.identifiers.rfc1459_lower(text: str) → str#

Lower text according to RFC 2812.

Similar to rfc1459_strict_lower(), but also maps ~ to ^, as per RFC 2812 § 2.2:

Because of IRC’s Scandinavian origin, the characters {}|^ are considered to be the lower case equivalents of the characters []\~, respectively.

Note

This is an implementation of the CASEMAPPING parameter for the value rfc1459, which doesn’t use RFC 1459 but its updated version RFC 2812.

sopel.tools.identifiers.rfc1459_strict_lower(text: str) → str#

Lower text according to RFC 1459 (strict version).

As per RFC 1459 § 2.2:

Because of IRC’s scandanavian origin, the characters {}| are considered to be the lower case equivalents of the characters []\.