Built-in features

The following features are packaged with pydle and live in the pydle.features namespace.

RFC1459

API: pydle.features.RFC1459Support

RFC1459 is the bread and butter of IRC: it is the standard that defines the very base concepts of the IRC protocol, ranging from what a channel is to the basic commands to channel limits. If you want your client to have actually any useful IRC functionality, it is recommend to include this feature.

Transport Layer Security (TLS)

API: pydle.features.TLSSupport

Support for secure connections to the IRC server using Transport Layer Security.

This allows, if the server supports it, for encrypted connections between the server and the client, to prevent snooping and provide two-way authentication: both for the server to ensure its identity to the client, and for the client to ensure its identity to the server. The latter can also be used in certain service packages to automatically identify to the user account.

In order to connect to a TLS-enabled server, supply tls=True to pydle.features.TLSSupport.connect().

Hint

pydle does not verify server-side TLS certificates by default; to enable certificate verification, supply tls_verify=True to pydle.features.TLSSupport.connect() as well.

In order to supply a client certificate, pydle.features.TLSSupport takes 3 additional constructor parameters:

  • tls_client_cert: A path to the TLS client certificate.
  • tls_client_cert_key: A path to the TLS client certificate key.
  • tls_client_cert_password: The optional password for the certificate key.

Client-to-Client Protocol (CTCP)

API: pydle.features.CTCPSupport

Support for encapsulation of out-of-band features into standard IRC messages using the Client-to-Client Protocol.

This allows you to send meta-messages to other users, requesting e.g. their local time, client version, and more, and respond to such requests. It adds pydle.Client.ctcp(target, query, contents=None), which allows you to send a CTCP request to a target, and pydle.Client.ctcp_reply(target, query, contents=None), which allows you to respond to CTCP requests.

In addition, it registers the pydle.Client.on_ctcp(from, query, contents) hook, which allows you to act upon any CTCP request, and a per-type hook in the form of pydle.Client.on_ctcp_<type>(from, contents), which allows you to act upon CTCP requests of type type. type will always be lowercased. A few examples of type can be: action, time, version.

Finally, it registers the pydle.Client.on_ctcp_reply(from, queyr, contents) hook, which acts similar to the above hook, except it is triggered when the client receives a CTCP response. It also registers pydle.Client.on_ctcp_<type>_reply, which works similar to the per-type hook described above.

Server-side Extension Support (ISUPPORT)

API: pydle.features.ISUPPORTSupport

Support for IRC protocol extensions using the ISUPPORT message.

This feature allows pydle to support protocol extensions which are defined using the non-standard ISUPPORT (005) message. It includes built-in support for a number of popular ISUPPORT-based extensions, like CASEMAPPING, CHANMODES, NETWORK and PREFIX.

It also provides the generic pydle.Client.on_isupport_type(value) hook, where type is the type of ISUPPORT-based extension that the server indicated support for, and value is the optional value of said extension, or None if no value was present.

Account System

API: pydle.features.AccountSupport

Support for a generic IRC account system.

Most IRC networks have some kind of account system that allows users to register and manage their nicknames and personas. This feature provides additional support in pydle for this idea and its integration into the networks.

Currently, all it does is set the identified and account fields when doing a WHOIS query (pydle.Client.whois(user)) on someone, which indicate if the target user has identified to their account, and if such, their account name, if available.

Extended User Tracking

API: pydle.features.WHOXSupport

Support for better user tracking using WHOX.

This feature allows pydle to perform more accurate tracking of usernames, idents and account names, using the WHOX IRC extension. This allows pydle’s internal user database to be more accurate and up-to-date.

IRCv3

API: pydle.features.IRCv3Support

A shortcut for IRCv3.1 and IRCv3.2 support; see below.

IRCv3.1

API: pydle.features.IRCv3_1Support

IRCv3.1 support.

The `IRCv3 Working Group`_ is a working group organized by several network, server author, and client author representatives with the intention to standardize current non-standard IRC practices better, and modernize certain parts of the IRC protocol. The IRCv3 standards are specified as a bunch of extension specifications on top of the last widely-used IRC version, IRC v2.7, also known as RFC1459.

The IRCv3.1 specification adds useful features to IRC from a client perspective, including SASL authentication, support for indicating when a user identified to their account, and indicating when a user went away from their PC.

Including this feature entirely will activate all IRCv3.1 functionality for pydle. You can also opt-in to only select the two major features of IRCv3.1, the capability negotiation framework and SASL authentication support, as described below, by only including their features.

Capability Negotiation Support

API: pydle.features.ircv3.CapabilityNegotiationSupport

Support for capability negotiation for IRC protocol extensions.

This feature enables support for a generic framework for negotiating IRC protocol extension support between the client and the server. It was quickly found that ISUPPORT alone wasn’t sufficient, as it only advertises support from the server side instead of allowing the server and client to negotiate. This is a generic base feature: enabling it on its own won’t do much, instead other features like the IRCv3.1 support feature, or the SASL authentication feature will rely on it to work.

This feature adds three generic hooks for feature authors whose features makes use of capability negotiation:

  • pydle.Client.on_capability_<cap>_available(value): Called when the server indicates capability cap is available.
    Is passed a value as given by the IRC server, or None if no value was given Should return either a boolean indicating whether or not to request the capability, or a string indicating to request the capability with the returned value.
  • pydle.Client.on_capability_<cap>_enabled(): Called when the server has acknowledged the request of capability cap, and it
    has been enabled. Should return one of three values: pydle.CAPABILITY_NEGOTIATING when the capability will be further negotiated, pydle.CAPABILITY_NEGOTIATED when the capability has been negotiated successfully, or pydle.CAPABILITY_FAILED when negotiation of the capability has failed. If the function returned pydle.CAPABILITY_NEGOTIATING, it has to call pydle.Client.capability_negotiated(cap, success=True) when negotiating is finished.
  • pydle.Client.on_capability_<cap>_disabled(): Called when a previously-enabled capability cap has been disabled.

User Authentication Support (SASL)

API: pydle.features.ircv3.SASLSupport

Support for user authentication using SASL.

This feature enables users to identify to their network account using the SASL protocol and practices. Three extra arguments are added to the pydle.Client constructor:

  • sasl_username: The SASL username.
  • sasl_password: The SASL password.
  • sasl_identity: The identity to use. Default, and most common, is ''.
  • sasl_mechanism: The SASL mechanism to force. Default involves auto-selection from server-supported mechanism, or a PLAIN` fallback.

These arguments are also set as attributes.

Currently, pydle’s SASL support requires on the Python pure-sasl package and is thus limited to the mechanisms it supports. The EXTERNAL mechanism is also supported without, however.

IRCv3.2

API: pydle.features.IRCv3_2Support

Support for the IRCv3.2 specification.

The IRCv3.2 specification is the second iteration of specifications from the `IRCv3 Working Group`_. This set of specification is still under development, and may change at any time. pydle’s support is conservative, likely incomplete and to-be considered experimental.

pydle currently supports the following IRCv3.2 extensions:

As with the IRCv3.1 features, using this feature enables all of pydle’s IRCv3.2 support. A user can also opt to only use individual large IRCv3.2 features by using the features below.

Online Status Monitoring

API: pydle.features.ircv3.MonitoringSupport

Support for monitoring a user’s online status.

This feature allows a client to monitor the online status of certain nicknames. It adds the pydle.Client.monitor(nickname) and pydle.Client.unmonitor(nickname) APIs to add and remove nicknames from the monitor list.

If a monitored user comes online, pydle.Client.on_user_online(nickname) will be called. Similarly, if a user disappears offline, pydle.Client.on_user_offline(nickname) will be called.

Tagged Messages

API: pydle.features.ircv3.TaggedMessageSupport

Support for message metadata using tags.

This feature allows pydle to parse message metadata that is transmitted using ‘tags’. Currently, this has no impact on any APIs or hooks for client developers.

Metadata

API: pydle.features.ircv3.MetadataSupport

Support for user and channel metadata.

This allows you to set and unset arbitrary key-value information on yourself and on channels, as well as retrieve such values from other users and channels.