API reference

Connections

class omnipresence.connection.Connection

Omnipresence’s core IRC client protocol.

See Twisted’s IRCClient documentation for details on methods used to perform basic actions.

reply(string, request, tail='')

Send a reply string, truncated to MAX_REPLY_LENGTH characters, with tail appended. If the request venue is a channel, send the reply to the venue as a standard message addressed to request‘s target, formatted using the venue‘s reply format. Otherwise, send the reply as a notice to request‘s actor.

is_channel(name)

Return True if name belongs to a channel, according to the server-provided list of channel prefixes, or False otherwise.

suspend_joins()

Suspend all channel joins until resume_joins is called.

resume_joins()

Resume immediate joining of channels after suspending it with suspend_joins, and perform any channel joins that have been queued in the interim.

case_mapping

The CaseMapping currently in effect on this connection. Defaults to rfc1459 if none is explicitly provided by the server.

venues

A mapping of venue names to VenueInfo objects.

parser

The RawMessageParser being used on this connection.

reactor

The reactor in use on this client. This may be overridden when a deterministic clock is needed, such as in unit tests.

class omnipresence.connection.VenueInfo(case_mapping=None)

A container for information about a venue.

modes = None

A mapping of modes currently active on this channel to one of False (not set or invalid), True (set, for modes that take no arguments), a single number or string, or a set of Hostmask objects.

nicks = None

A dictionary mapping nicks to VenueUserInfo objects.

topic = None

This channel’s topic, or the empty string if none is set.

class omnipresence.connection.VenueUserInfo

A container for information about a user’s state in a particular venue.

reply_buffer = None

This user’s current channel reply buffer.

omnipresence.connection.MAX_REPLY_LENGTH = 288

The maximum length of a single command reply, in bytes.

Messages

class omnipresence.message.Message(connection, outgoing, action, actor=None, venue=None, target=None, subaction=None, content=None)

Represents a message, loosely defined as an event to which plugins can respond. Messages have the following basic attributes:

connection

The Connection on which the message was received.

outgoing

A boolean indicating whether this message resulted from a bot action.

action

This message’s MessageType. A string containing a message type name may be passed to the constructor, but the property always contains an enumeration member.

actor

A Hostmask corresponding to the message prefix, indicating the message’s true origin. In some cases, unknown messages will set this attribute to None if a prefix could not be parsed.

venue

target

subaction

content

Optional attributes, whose presence and meaning depend on the message type. An attribute is None if and only if it is not used by the current message type, and a string value otherwise.

raw

If this message was created by parsing a raw message with RawMessageParser.parse, the original raw IRC message string passed to that function. Otherwise, None.

Note

All string values are byte strings, not Unicode strings, and therefore must be appropriately decoded when necessary.

The following additional properties are derived from the values of one or more basic attributes, and are included for convenience:

private

True if this message has a venue and that venue is not a public channel. Otherwise, False.

encoding

The character encoding in effect for this message’s venue.

New message objects can be created using either the standard constructor, or by parsing a raw IRC message string using RawMessageParser.parse.

Message is a namedtuple type, and thus its instances are immutable. To create a new object based on the attributes of an existing one, use an instance’s _replace method.

class omnipresence.message.MessageType

An enumeration of valid values of Message.action.

The following message types directly correspond to incoming or outgoing IRC messages (also see RFC 1459#section-4):

action = <MessageType.action: 1>

Represents a CTCP ACTION (/me). All attributes are as for the privmsg type.

ctcpquery = <MessageType.ctcpquery: 2>

Represents an otherwise unrecognized CTCP query wrapped in a PRIVMSG. venue is the nick or channel name of the recipient. subaction is the CTCP message tag. content is a string containing any trailing arguments.

Note

Omnipresence does not support mixed messages containing both normal and CTCP extended content.

ctcpreply = <MessageType.ctcpreply: 3>

Represents an unrecognized CTCP reply wrapped in a NOTICE. All attributes are as for the ctcpquery type.

join = <MessageType.join: 4>

Represents a channel join. venue is the channel being joined.

kick = <MessageType.kick: 5>

Represents a kick. venue is the channel the kick took place in. target is the nick of the kicked user. content is the kick message.

mode = <MessageType.mode: 6>

Represents a mode change. venue is the affected channel or nick. content is the mode change string.

nick = <MessageType.nick: 7>

Represents a nick change. content is the new nick.

notice = <MessageType.notice: 8>

Represents a notice. All attributes are as for the privmsg type.

part = <MessageType.part: 9>

Represents a channel part. venue is the channel being departed from. content is the part message.

privmsg = <MessageType.privmsg: 10>

Represents a typical message. venue is the nick or channel name of the recipient. (private can also be used to determine whether a message was sent to a single user or a channel.) content is the text of the message.

quit = <MessageType.quit: 11>

Represents a client quit from the IRC network. content is the quit message.

topic = <MessageType.topic: 12>

Represents a topic change. venue is the affected channel. content is the new topic, or an empty string if the topic is being unset.

unknown = <MessageType.unknown: 0>

Represents a message that is not of any known type, or that could not be correctly parsed. subaction is the IRC command name or numeric. content is a string containing any trailing arguments.

Omnipresence defines additional message types for synthetic events:

connected = <MessageType.connected: 9001>

Created when the server has responded with RPL_WELCOME. No optional arguments are specified.

disconnected = <MessageType.disconnected: 9002>

Created when the connection to the server has been closed or lost. No optional arguments are specified.

command = <MessageType.command: 9003>

Represents a command invocation. venue is as for the privmsg type. target is a string containing the reply redirection target, or the actor’s nick if none was specified. subaction is the command keyword. content is a string containing any trailing arguments.

cmdhelp = <MessageType.cmdhelp: 9004>

Represents a command help request. venue and target are as for the command type. subaction is the command keyword for which help was requested. content is a string containing any trailing arguments.

class omnipresence.message.parser.RawMessageParser

An implementation of the parsing rules for a specific version of the IRC protocol.

In most cases, you should use the parser attribute of a Connection to retrieve an instance of this class.

parse(connection, outgoing, raw, **kwargs)

Parse a raw IRC message string and return a corresponding Message object. Any keyword arguments override field values returned by the parser.

Message formatting

Operations on mIRC-style message formatting.

omnipresence.message.formatting.remove_formatting(string)

Return string with mIRC-style formatting control codes removed.

omnipresence.message.formatting.unclosed_formatting(string)

Return a frozenset containing any mIRC-style formatting codes that remain in effect at the end of string.

Hostmasks

Operations on IRC hostmasks.

class omnipresence.hostmask.Hostmask

Represents an IRC hostmask (sometimes called a message prefix) of the form nick!user@host. The user and host attributes are optional, and default to None if not present.

classmethod from_string(string)

Return a new Hostmask object parsed from string, according to the definition of <prefix> in RFC 1459#section-2.3.1.

has_wildcard

True if this hostmask contains a wildcard or any None components. Otherwise, False otherwise.

matches(other, case_mapping=None)

Check whether this hostmask matches the pattern in other, which can be a Hostmask object or a string in the form "nick!user@host", according to the wildcard expansion rules in RFC 2812#section-2.5. A CaseMapping object may optionally be provided, in which case nicks are compared case-insensitively according to the mapping’s rules; otherwise, nick comparisons are fully case-sensitive. Users and hosts are always compared case-insensitively, using normal ASCII case folding rules.

Briefly, * and ? wildcards match zero or more and exactly one non-delimiter character, respectively; a backslash can be used to escape these special characters. Components that equal None are assumed to match all possible values for that component.

Warning

This method only matches wildcards in other, not the Hostmask object it is called on:

>>> Hostmask.from_string('nick!user@host').matches('nick!*@*')
True
>>> Hostmask.from_string('nick!*@*').matches('nick!user@host')
False

Case mappings

Operations on IRC case mappings.

class omnipresence.case_mapping.CaseMapping(lower, upper)

Provides convenience methods for bidirectional string translation given a mapping of characters from lower to upper.

classmethod by_name(name)

Return an IRC case mapping given the name used in the CASEMAPPING parameter of a RPL_ISUPPORT IRC message (numeric 005). The following mapping names are recognized:

ascii

Treats the letters A-Z as uppercase versions of the letters a-z.

strict-rfc1459

Extends the ascii case mapping to further treat {}| as the lowercase versions of []\. This matches the rules specified in RFC 1459#section-2.2.

rfc1459

Extends the strict-rfc1459 case mapping to further treat ~ as the lowercase version of ^. This corresponds to most servers’ actual implementation of the RFC 1459 rules.

ValueError is raised on an unrecognized mapping name.

equates(one, two)

Return a boolean value indicating whether a and b are equal under this case mapping.

lower(string)

Return a copy of string with uppercase characters converted to lowercase according to this case mapping.

upper(string)

Return a copy of string with lowercase characters converted to uppercase according to this case mapping.

class omnipresence.case_mapping.CaseMappedDict(initial=None, case_mapping=None)

A dictionary whose keys are treated case-insensitively according to a CaseMapping or mapping name string (as given to by_name) provided on instantiation.

Web resource interactions

omnipresence.web.html.textify(html, format_output=True)

Convert the contents of html to a Unicode string. html can be either a string containing HTML markup, or a Beautiful Soup tag object. If format_output is true, mIRC-style formatting codes are added to simulate common element styles.

omnipresence.web.http.read_json_body(response)

Return a Deferred yielding a Python object deserialized from the Twisted Web response containing JSON data in its body.

Human-readable output helpers

Functions for presenting data in human-readable forms.

omnipresence.humanize.ago(then, now=None)

Given a datetime object, return an English string giving an approximate relative time, such as “5 days ago”.

omnipresence.humanize.andify(seq, two_comma=False)

Join the elements of a sequence and return a string of the form “x and y” for a two-element list, or “x, y, and z” for three or more elements. If two_comma is True, insert a comma before “and” even if the list is only two elements long (“x, and y”).

omnipresence.humanize.duration_to_timedelta(duration)

Convert a duration string of the form “_w_d_h_m_s” into a timedelta object.

omnipresence.humanize.readable_duration(duration)

Convert a duration string of the form “_w_d_h_m_s” to a plain English representation such as “2 weeks, 5 days, and 20 hours”.