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

str – Plug-specific user identifier.

plug

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

username

str – User’s chosen or allocated display name.

real_name

str – User’s preferred and/or family name.

avatar

str – URL of the user’s profile picture.

str – Public profile URL, or identifier used for invites.

suggested

boolTrue 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.

raw

Optional plug-specific underlying user object.

is_system()

Equivalent to Plug.user_is_system().

Returns
True if the user relates to the plug itself.
Return type
bool
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

str – Plain segment text.

bold

bool – Whether this segment should be formatted bold.

italic

bool – Whether this segment should be emphasised.

underline

bool – Whether this segment should be underlined.

strike

bool – Whether this segment should be struck through.

code

bool – Whether this segment should be monospaced.

pre

bool – Whether this segment should be preformatted.

str – Anchor URL if this segment represents a clickable link.

mention

.User – Target user mentioned in this segment.

plain

boolTrue if the segment is not formatted.

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

int – Number of segments in the text.

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
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: 0>, source=None)

Bases: object

Base file attachment object.

title

str – Name of file, if the plug supports names.

type

.Type – Basic type of the file.

source

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

class Type

Bases: enum.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).

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

float – North-South coordinate of the location in degrees.

longitude

float – East-West coordinate of the location in degrees.

coordintes

float – Read-only (latitude, longitude) pair.

name

str – Name of the place represented by this location.

address

str – Full street address of this place.

google_map_url

str – URL to Google Maps centred on this place.

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: immp.core.message._SentMessageSlots

Base message content container, understood by all plugs.

text

.RichText – Representation of the message text content.

user

.User – User profile that sent the message.

edited

bool – Whether the message content has been changed.

action

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

reply_to

.Message – Parent message, which this message replies to.

joined

.User list – Collection of users that just joined the channel.

left

.User list – Collection of users that just parted the channel.

title

str – New channel title, if this message represents a rename.

attachments

.Attachment list – Additional data included in the message.

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: immp.core.message._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

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

channel

.Channel – Source channel of this message.

at

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

revision

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

deleted

bool – Whether the message was deleted from its source.

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: immp.core.message.Receipt, immp.core.message.Message

Combination of Receipt and Message.