core.message¶

class immp.core.message.User(id_=None, plug=None, *, username=None, real_name=None, avatar=None, link=None, suggested=False, raw=None)¶

Bases: object

Generic class to represent senders of messages.

id¶

Plug-specific user identifier.

Type:: str

plug¶

Source plug instance, representing the domain this user comes from.

Type:: .Plug

username¶

User’s chosen or allocated display name.

Type:: str

real_name¶

User’s preferred and/or family name.

Type:: str

avatar¶

URL of the user’s profile picture.

Type:: str

link¶

Public profile URL, or identifier used for invites.

Type:: str

suggested¶

True if the display of this user is not important. Useful for bot messages where displaying the author is superfluous – plugs may choose to show the user only if required by the network to show something.

Type:: bool

raw¶: Optional plug-specific underlying user object.

async is_system()¶

Equivalent to Plug.user_is_system().

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

async private_channel()¶

Equivalent to Plug.channel_for_user().

Returns:: Private channel for this user.
Return type:: .Channel

class immp.core.message.Segment(text, *, bold=False, italic=False, underline=False, strike=False, code=False, pre=False, link=None, mention=None)¶

Bases: object

Substring of message text with consistent formatting.

Calling str() on an instance will return the segment text. Similarly, the length of a segment is just the length of the contained text.

text¶

Plain segment text.

Type:: str

bold¶

Whether this segment should be formatted bold.

Type:: bool

italic¶

Whether this segment should be emphasised.

Type:: bool

underline¶

Whether this segment should be underlined.

Type:: bool

strike¶

Whether this segment should be struck through.

Type:: bool

code¶

Whether this segment should be monospaced.

Type:: bool

pre¶

Whether this segment should be preformatted.

Type:: bool

link¶

Anchor URL if this segment represents a clickable link.

Type:: str

mention¶

Target user mentioned in this segment.

Type:: .User

text_is_link¶

True if the segment text just matches the link, potentially without a protocol.

Type:: bool

plain¶

True if the segment is not formatted.

Type:: bool

same_format(other)¶

Test if this and another segment are equally formatted. Works like == but ignores the segment text.

Parameters:: other (.Segment) – Second segment for comparison.
Returns:: True if the segments match.
Return type:: bool

class immp.core.message.RichText(segments=None)¶

Bases: object

Common standard for formatted message text, akin to Hangouts’ message segments. This is a container designed to hold instances of Segment.

Calling str() on an instance will return the entire text without formatting.

Instances may be indexed or sliced, which will apply to the segments. The slice.step argument is overloaded to be boolean; if True, slicing will apply to characters of the text content rather than the segments. Length is always based on the content.

size¶

Number of segments in the text.

Type:: int

normalise()¶

Make a copy of this message with formatting applied from text boundaries.

For example:

Some<b> bold </>text.

The bold boundaries would be moved to surround “bold” excluding the spaces:

Some <b>bold</> text.

Returns:: Normalised message text instance.
Return type:: .RichText

clone()¶

Make a copy of this message text and all its segments.

Returns:: Cloned message text instance.
Return type:: .RichText

prepend(*segments)¶

Insert one or more segments at the beginning of the text.

Parameters:: segments (.Segment list) – New segments to lead the message text.

append(*segments)¶

Insert one or more segments at the end of the text.

Parameters:: segments (.Segment list) – New segments to tail the message text.

indent(chars=' ')¶

Prefix each line of text with another string.

Parameters:: chars (str) – Prefix characters to prepend to each line.
Returns:: Indented message text instance.
Return type:: .RichText

offset(pos)¶

Find the position within a segment corresponding to a point along the whole text.

Parameters:: pos (int) – Position within the represented text.
Returns:: Segment and offset within it.
Return type:: (int, int) tuple

trim(length)¶

Reduce a long message text to a snippet with an ellipsis.

Parameters:: length (int) – Maximum length of the message text.
Returns:: Trimmed message text instance.
Return type:: .RichText

lines()¶

Split the message text into lines.

Returns:: Message text parts.
Return type:: .RichText list

chunked(limit)¶

Split long text into parts, each not exceeding the length limit. Prefers splitting on line breaks where possible – any individual lines exceeding the limit will be wrapped.

Parameters:: limit (int) – Character length limit for each chunk.
Returns:: Chunked message text parts.
Return type:: .RichText list

classmethod chunked_plain(text, limit)¶

Split long text into parts, each not exceeding the length limit. See chunked().

Parameters:

text (str) – Raw message text.
limit (int) – Character length limit for each chunk.

Returns:

Chunked message text parts.

Return type:

str list

classmethod unraw(text, host=None)¶

Inverse of raw(), parse a string with formatting syntax into a rich instance.

Parameters:

text (str) – Plain text with formatting syntax.
host (.Host) – Optional host instance, needed to resolve mention tags.

Returns:

Parsed message text instance.

Return type:

.RichText

raw()¶

Serialise formatted text into a string representation, suitable for storage or transmission as plain text.

Returns:: Plain text with formatting syntax.
Return type:: str

class immp.core.message.File(title=None, type_=Type.unknown, source=None)¶

Bases: object

Base file attachment object.

title¶

Name of file, if the plug supports names.

Type:: str

type¶

Basic type of the file.

Type:: .Type

source¶

Public URL to the original file location, if one is available.

Type:: str

class Type(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Possible file attachment types.

unknown¶: Default file type if not otherwise specified.

image¶: Picture in a standard recognised format (e.g. PNG, JPEG).

video¶: Video in a standard recognised format (e.g. MP4).

async get_content(sess)¶

Stream the contents of the file, suitable for writing to a file or uploading elsewhere.

The default implementation will try to fetch a file by the source field. It may be overridden to add authentication or other metadata, but the method must remain callable with only a session passed to it.

Parameters:: sess (aiohttp.ClientSession) – Existing HTTP session with which to make any requests.
Returns:: Readable stream of the raw file.
Return type:: io.IOBase

class immp.core.message.Location(latitude=None, longitude=None, name=None, address=None)¶

Bases: object

latitude¶

North-South coordinate of the location in degrees.

Type:: float

longitude¶

East-West coordinate of the location in degrees.

Type:: float

coordintes¶

Read-only (latitude, longitude) pair.

Type:: float

name¶

Name of the place represented by this location.

Type:: str

address¶

Full street address of this place.

Type:: str

google_map_url¶

URL to Google Maps centred on this place.

Type:: str

google_image_url(width, height=None)¶

Generate a static map image URL centred on this place.

Parameters:

width (int) – Width of the image.
height (int) – Height of the image, matches the width (for a square image) if not specified.

Returns:

Corresponding image URL from the Google Maps API.

Return type:

str

class immp.core.message.Message(*, text=None, user=None, edited=False, action=False, reply_to=None, joined=None, left=None, title=None, attachments=None, raw=None)¶

Bases: _SentMessageSlots

Base message content container, understood by all plugs.

text¶

Representation of the message text content.

Type:: .RichText

user¶

User profile that sent the message.

Type:: .User

edited¶

Whether the message content has been changed.

Type:: bool

action¶

Whether this message should be presented as an action involving its user.

Type:: bool

reply_to¶

Parent message, which this message replies to.

Type:: .Message

joined¶

Collection of users that just joined the channel.

Type:: .User list

left¶

Collection of users that just parted the channel.

Type:: .User list

title¶

New channel title, if this message represents a rename.

Type:: str

attachments¶

Additional data included in the message.

Type:: .Attachment list

raw¶: Optional plug-specific underlying message or event object.

render(*, real_name=True, link_name=True, edit=False, delimiter='\n', quote_reply=False, strip_links=False, trim=None)¶

Add the sender’s name (if present) to the start of the message text, suitable for sending as-is on plugs that need all the textual message content in the body.

Parameters:

real_name (bool) – True (default) to display real names, or False to prefer usernames. If only one kind of name is available, it will be used regardless of this setting.
link_name (bool) – True (default) to link the author’s name to their profile, if a link exists.
edit (bool) – Whether this render should show an [edit] tag next to the author.
delimiter (str) – Characters added between the sender’s name and the message text (a new line by default).
quote_reply (bool) – True to quote the parent message before the current one, prefixed with a box-drawing vertical line (not quoted by default).
strip_links (bool) – True to skip over links in the message text (links left intact by default).
trim (int) – Show an ellipsed snippet if the text exceeds this length, or None (default) for no trimming.

Returns:

Rendered message body.

Return type:

.RichText

clone()¶

Make a shallow copy of this message, but recursively cloning replies and attachments.

Returns:: Copied message.
Return type:: .Message

class immp.core.message.Receipt(id_, channel, *, at=None, revision=None, deleted=False)¶

Bases: _SentMessageSlots

Reference to a physical message received from a plug. This provides metadata for identifying a source message, in addition to the actual content attributes.

id¶

Unique (to the plug) message identifier, which should persist across edits and deletes.

Type:: str

channel¶

Source channel of this message.

Type:: .Channel

at¶

Timestamp of the message according to the external server, defaults to the current time at creation if unset.

Type:: datetime.datetime

revision¶

Key to uniquely identify updates to a previous message, defaults to id. Need not be in the same format as the main identifier.

Type:: str

deleted¶

Whether the message was deleted from its source.

Type:: bool

async resolve()¶: Equivalent to Plug.resolve_message().

async delete()¶: Equivalent to Plug.delete().

class immp.core.message.SentMessage(id_, channel, *, at=None, revision=None, edited=False, deleted=False, text=None, user=None, action=False, reply_to=None, joined=None, left=None, title=None, attachments=None, raw=None)¶

Bases: Receipt, Message

Combination of Receipt and Message.