plug.irc¶

exception immp.plug.irc.IRCError¶

Bases: PlugError

Generic error from the IRC server.

exception immp.plug.irc.IRCTryAgain¶

Bases: IRCError

Rate-limited response to an IRC command (RPL_TRYAGAIN, 263).

class immp.plug.irc.Line(command, *args, source=None, tags=None)¶

Bases: object

Low-level representation of an IRC message, either sent or received. Calling str() on a line will encode it suitable for transmission.

command¶

IRC verb or numeric.

Type:: str

args¶

Additional arguments for this message.

Type:: str list

source¶

Optional source of this message.

Type:: str list

tags¶

Any tags attached to the message.

Type:: (str, str) dict

classmethod parse(line)¶

Take a raw IRC line and decode it into a Line.

Parameters:: line (str) – Raw IRC message.
Returns:: Parsed line.
Return type:: .Line

class immp.plug.irc.IRCSegment(text, *, bold=False, italic=False, underline=False, strike=False, code=False, pre=False, link=None, mention=None)¶

Bases: Segment

Plug-friendly representation of IRC message formatting.

classmethod to_formatted(segment)¶

Convert a Segment into text formatted using IRC ASCII escape sequences.

Parameters:: segment (.Segment) – Message segment created by another plug.
Returns:: Code-formatted string.
Return type:: str

class immp.plug.irc.IRCRichText(segments=None)¶

Bases: RichText

Wrapper for IRC-specific encoding of formatting.

classmethod to_formatted(rich)¶

Convert a RichText into text formatted using IRC ASCII escape sequences.

Parameters:: rich (.RichText) – Parsed rich text container.
Returns:: Code-formatted string.
Return type:: str

class immp.plug.irc.IRCUser(id_=None, plug=None, *, username=None, real_name=None, avatar=None, link=None, suggested=False, raw=None)¶

Bases: User

User present in IRC.

classmethod nick_colour(nick)¶

Assign a random but stable colour to a string, similar to IRC clients’ display of nicks.

Parameters:: nick (str) – Name of a user.
Returns:: IRC colour code, between 2 and 13 inclusive.
Return type:: int

classmethod from_id(irc, id_, real_name=None)¶

Extract the nick from a nickmask into a User.

Parameters:

irc (.IRCPlug) – Related plug instance that provides the user.
id (str) – Nickmask of the target user.
real_name (str) – Display name of the user, if known.

Returns:

Parsed user object.

Return type:

.User

classmethod from_who(irc, line)¶

Convert the response of a WHO query into a User.

Parameters:

irc (.IRCPlug) – Related plug instance that provides the user.
line (.Line) – 352-numeric line containing a user’s nickmask and real name.

Returns:

Parsed user object.

Return type:

.User

classmethod from_whois(irc, line)¶

Convert the response of a WHOIS query into a User.

Parameters:

irc (.IRCPlug) – Related plug instance that provides the user.
line (.Line) – 311-numeric line containing a user’s nick, host and real name.

Returns:

Parsed user object.

Return type:

.User

class immp.plug.irc.IRCMessage(*, text=None, user=None, edited=False, action=False, reply_to=None, joined=None, left=None, title=None, attachments=None, raw=None)¶

Bases: Message

Message originating from IRC.

async classmethod from_line(irc, line)¶

Convert a Line into a Message.

Parameters:

irc (.IRCPlug) – Related plug instance that provides the line.
line (.Line) – Raw message line from the server.

Returns:

Parsed message object.

Return type:

.IRCMessage

class immp.plug.irc.Wait(success, fail, collect)¶

Bases: object

Request-like object for sending a Line and waiting on a response.

After sending, await an instance of this class to retrieve all collected lines after a success line is received. On failure, an IRCError is raised.

done¶

True once a success or fail line has been received.

Type:: bool

add(line)¶

Consume and handle a line, or raise TypeError if it’s not applicable to this wait.

Parameters:: line (.Line) – Incoming line to be handled.

cancel()¶: Cancel any tasks waiting on this wait.

class immp.plug.irc.IRCClient(plug, host, port, ssl, nick, password=None, user=None, name=None, on_connect=None, on_receive=None)¶

Bases: object

Minimal, standalone IRC client.

nick¶

Connected user’s nickname.

Type:: str

nickmask¶

Combination of the connected user’s nick and hostname.

Type:: str

name¶

Connected user’s display name.

Type:: str

async set_nick(value)¶

Set the user’s nick, and wait until it’s successful. If connected and the desired nick is not available, underscores will be appended until a free nick is found.

Parameters:: value (str) – Desired new nick.

async connect()¶: Join the target IRC server.

async disconnect(msg)¶

Quit from the connected IRC server.

Parameters:: msg (str) – Disconnect message sent to the server.

async who(name)¶

Perform a member lookup on the server.

Parameters:: name (str) – User nick or channel name.
Returns:: Matching users, either a single user or all participants of a channel.
Return type:: .User set

async whois(name)¶

Perform a user lookup on the server.

Parameters:: name (str) – User nick.
Returns:: Matching user, or None if not found.
Return type:: .User

async join(channel)¶

Attempt to join the given channel.

Parameters:: channel (str) – Target channel name.

async part(channel)¶

Leave a channel you’re participating in.

Parameters:: str) (channel) – Target channel name.

async invite(channel, nick)¶

Invite another user to a channel you’re partipating in.

Parameters:

channel (str) – Target channel name.
nick (str) – User to be invited.

async kick(channel, nick)¶

Remove a user from a channel you’re an operator of.

Parameters:

channel (str) – Target channel name.
nick (str) – User to be kicked.

async list()¶

Request a list of open channels on the server.

Returns:: Response lines from the server.
Return type:: .Line list

async names(channel)¶

Request a list of users in a given channel.

Parameters:: channel (str) – Target channel name.
Returns:: Response lines from the server.
Return type:: .Line list

async all_names()¶

Request a list of users across all channels you’re participating in.

Returns:: Response lines from the server.
Return type:: .Line list

async send(channel, text)¶

Send a message to a user or channel.

Parameters:

channel (str) – Target channel name or user nick.
text (str) – IRC-formatted message text.

Returns:

Resulting line sent to the server.

Return type:

.Line

class immp.plug.irc.DelayLock(delay)¶

Bases: object

Timed-release lock, used in an async with statement to acquire a lock, but delay its release by some number of seconds after the caller has finished with it.

class immp.plug.irc.IRCPlug(name, config, host)¶

Bases: Plug

Plug for an IRC server.

async start()¶

Perform any underlying operations needed to ready this resource for use, such as opening connections to an external network or API.

If using an event-driven framework that yields and runs in the background, you should use a signal of some form (e.g. asyncio.Condition) to block this method until the framework is ready for use.

async stop()¶

Perform any underlying operations needed to stop using this resource and tidy up, such as terminating open network connections.

Like with start(), this should block as needed to wait for other frameworks – this method should return only when ready to be started again.

async user_from_id(id_)¶

Retrieve a User based on the underlying network’s identifier.

Parameters:: id (str) – Network identifier of the user.
Returns:: Corresponding user instance.
Return type:: .User

async user_from_username(username)¶

Retrieve a User based on the underlying network’s username.

Parameters:: username (str) – Network username of the user.
Returns:: Corresponding user instance.
Return type:: .User

async user_is_system(user)¶

Check if a given user is automated by the plug (for example a bot user from which the plug operates). Hooks may exclude system users from certain operations.

Returns:: True if the user relates to the plug itself.
Return type:: bool

async public_channels()¶

Retrieve all shared channels known to this plug, either public or otherwise accessible. May return None if the network doesn’t support channel discovery.

Returns:: All available non-private channels.
Return type:: .Channel list

async private_channels()¶

Retrieve all private (one-to-one) channels known to this plug. May return None if the network doesn’t support channel discovery.

Returns:: All available private channels.
Return type:: .Channel list

async channel_for_user(user)¶

Retrieve a Channel representing a private (one-to-one) conversation between a given user and the service. Returns None if the user does not have a private channel.

Parameters:: user (.User) – Requested user instance.
Returns:: Private channel for this user.
Return type:: .Channel

async channel_is_private(channel)¶

Test if a given channel represents a private (one-to-one) conversation between a given user and the service. May return None if the network doesn’t have a notion of public/shared and private channels.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: True if the channel is private.
Return type:: bool

async channel_title(channel)¶

Retrieve the friendly name of this channel, as used in the underlying network. May return None if the service doesn’t have a notion of titles.

Returns:: Display name for the channel.
Return type:: str

async channel_members(channel)¶

Retrieve a User list representing all members of the given channel. May return None if the plug doesn’t recognise the channel, or is unable to query members.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Members present in the channel.
Return type:: .User list

async channel_admins(channel)¶

Retrieve a User list representing members of the given channel with the ability to manage the channel or its members. May return None if the plug doesn’t recognise the channel, is unable to query members, or has no concept of admins.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Members with admin privileges present in the channel.
Return type:: .User list

async channel_invite(channel, user)¶

Add the given user to the channel’s list of members.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – New user to invite.

async channel_remove(channel, user)¶

Remove the given user from the channel’s list of members.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – Existing user to kick.

async put(channel, msg)¶

Take a Message object, and push it to the underlying network.

Because some plugs may not support combinations of message components (such as text and an accompanying image), this method may send more than one physical message.

Parameters:

channel (.Channel) – Target channel for the new message.
msg (.Message) – Original message received from another channel or plug.

Returns:

References to new messages sent to the plug.

Return type:

.Receipt list