slidge.core.contact#

Module Contents#

Classes#

LegacyContact

This class centralizes actions in relation to a specific legacy contact.

LegacyRoster

Virtual roster of a gateway user, that allows to represent all

Attributes#

slidge.core.contact.SessionType[source]#
class slidge.core.contact.LegacyContact(session, legacy_id, jid_username)[source]#

Bases: Generic[slidge.core.session.SessionType]

This class centralizes actions in relation to a specific legacy contact.

You shouldn’t create instances of contacts manually, but rather rely on LegacyRoster.by_legacy_id() to ensure that contact instances are singletons. The LegacyRoster instance of a session is accessible through the BaseSession.contacts attribute.

Typically, your plugin should have methods hook to the legacy events and call appropriate methods here to transmit the “legacy action” to the xmpp user. This should look like this:

Parameters
  • session (slidge.core.session.SessionType) – The session this contact is part of

  • legacy_id (slidge.util.types.LegacyContactIdType) – The contact’s legacy ID

  • jid_username (str) – User part of this contact’s ‘puppet’ JID. NB: case-insensitive, and some special characters are not allowed

property jid: slixmpp.JID[source]#

Full JID (including the ‘puppet’ resource) of the contact

Return type

slixmpp.JID

property name[source]#

Friendly name of the contact, as it should appear in the user’s roster

property avatar[source]#

An image that represents this contact

RESOURCE :str = slidge[source]#

A full JID, including a resource part is required for chat states (and maybe other stuff) to work properly. This is the name of the resource the contacts will use.

AVATAR = True[source]#
RECEIPTS = True[source]#
MARKS = True[source]#
CHAT_STATES = True[source]#
UPLOAD = True[source]#
CORRECTION = True[source]#
REACTION = True[source]#
RETRACTION = True[source]#
REPLIES = True[source]#

A list of features advertised through service discovery and client capabilities.

CLIENT_TYPE = pc[source]#

https://xmpp.org/registrar/disco-categories.html#client

__repr__()[source]#

Return repr(self).

__get_subscription_string()[source]#
async __make_caps()[source]#

Configure slixmpp to correctly advertise this contact’s capabilities.

set_vcard(/, full_name = None, given = None, surname = None, birthday = None, phone = None, note = None, url = None, email = None, country = None, locality=None)[source]#
Parameters
  • full_name (Optional[str]) –

  • given (Optional[str]) –

  • surname (Optional[datetime.date]) –

  • birthday (Optional[str]) –

  • phone (Optional[str]) –

  • note (Optional[str]) –

  • url (Optional[str]) –

  • email (Optional[str]) –

  • country (Optional[str]) –

async add_to_roster()[source]#

Add this contact to the user roster using XEP-0356

__send_presence(*, ptype=None, show=None, status=None, last_seen=None)[source]#
Parameters
online(status=None, *, last_seen=None)[source]#

Send an “online” presence from this contact to the user.

Parameters
  • status (Optional[str]) – Arbitrary text, details of the status, eg: “Listening to Britney Spears”

  • last_seen (Optional[datetime.datetime]) – For XEP-0319

away(status=None, *, last_seen=None)[source]#

Send an “away” presence from this contact to the user.

This is a global status, as opposed to LegacyContact.inactive() which concerns a specific conversation, ie a specific “chat window”

Parameters
  • status (Optional[str]) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”

  • last_seen (Optional[datetime.datetime]) – For XEP-0319

extended_away(status=None, *, last_seen=None)[source]#

Send an “extended away” presence from this contact to the user.

This is a global status, as opposed to LegacyContact.inactive() which concerns a specific conversation, ie a specific “chat window”

Parameters
  • status (Optional[str]) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”

  • last_seen (Optional[datetime.datetime]) – For XEP-0319

busy(status=None, *, last_seen=None)[source]#

Send a “busy” presence from this contact to the user,

Parameters
offline(*, last_seen=None)[source]#

Send an “offline” presence from this contact to the user.

Parameters

last_seen (Optional[datetime.datetime]) – For XEP-0319

unsubscribe()[source]#

Send an “unsubscribe”, “unsubscribed”, “unavailable” presence sequence from this contact to the user, ie, “this contact has removed you from their ‘friends’”.

status(text)[source]#

Set a contact’s status

Parameters

text (str) –

__chat_state(state)[source]#
Parameters

state (str) –

active()[source]#

Send an “active” chat state (XEP-0085) from this contact to the user.

composing()[source]#

Send a “composing” (ie “typing notification”) chat state (XEP-0085) from this contact to the user.

paused()[source]#

Send a “paused” (ie “typing paused notification”) chat state (XEP-0085) from this contact to the user.

inactive()[source]#

Send an “inactive” (ie “typing paused notification”) chat state (XEP-0085) from this contact to the user.

gone()[source]#

Send an “inactive” (ie “typing paused notification”) chat state (XEP-0085) from this contact to the user.

__send_marker(legacy_msg_id, marker)[source]#

Send a message marker (XEP-0333) from this contact to the user.

NB: for the ‘received’ marker, this also sends a message receipt (XEP-0184)

Parameters
  • legacy_msg_id (slidge.util.types.LegacyMessageType) – ID of the message this marker refers to

  • marker (Literal[acknowledged, received, displayed]) – The marker type

ack(legacy_msg_id)[source]#

Send an “acknowledged” message marker (XEP-0333) from this contact to the user.

Parameters

legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to

received(legacy_msg_id)[source]#

Send a “received” message marker (XEP-0333) and a “message delivery receipt” (XEP-0184) from this contact to the user

Parameters

legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to

displayed(legacy_msg_id)[source]#

Send a “displayed” message marker (XEP-0333) from this contact to the user.

Parameters

legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to

__make_message(mtype='chat', **kwargs)[source]#
Return type

slixmpp.Message

__send_message(msg, legacy_msg_id=None, when=None)[source]#
Parameters
  • msg (slixmpp.Message) –

  • legacy_msg_id (Optional[Any]) –

  • when (Optional[datetime.datetime]) –

__make_reply(msg, reply_to_msg_id)[source]#
Parameters
  • msg (slixmpp.Message) –

  • reply_to_msg_id (Optional[slidge.util.types.LegacyMessageType]) –

send_text(body='', *, chat_state='active', legacy_msg_id=None, reply_to_msg_id=None, when=None)[source]#

Transmit a message from the contact to the user

Parameters
  • body (str) – Context of the message

  • chat_state (Optional[str]) – By default, will send an “active” chat state (XEP-0085) along with the message. Set this to None if this is not desired.

  • legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this

  • reply_to_msg_id (Optional[slidge.util.types.LegacyMessageType]) –

  • when (Optional[datetime.datetime]) – when the message was sent, for a “delay” tag (XEP-0203)

Returns

the XMPP message that was sent

Return type

slixmpp.Message

async __upload(filename, content_type=None, input_file=None, url=None)[source]#
Parameters
  • filename (Union[pathlib.Path, str]) –

  • content_type (Optional[str]) –

  • input_file (Optional[IO[bytes]]) –

  • url (Optional[str]) –

async send_file(filename, content_type=None, input_file=None, url=None, *, legacy_msg_id=None, reply_to_msg_id=None, when=None, caption=None)[source]#

Send a file using HTTP upload (XEP-0363)

Parameters
  • filename (Union[pathlib.Path, str]) – Filename to use or location on disk to the file to upload

  • content_type (Optional[str]) – MIME type, inferred from filename if not given

  • input_file (Optional[IO[bytes]]) – Optionally, a file like object instead of a file on disk. filename will still be used to give the uploaded file a name

  • legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this

  • url (Optional[str]) – Optionally, a URL of a file that slidge will download and upload to the default file upload service on the xmpp server it’s running on. url and input_file are mutually exclusive.

  • reply_to_msg_id (Optional[slidge.util.types.LegacyMessageType]) –

  • when (Optional[datetime.datetime]) – when the file was sent, for a “delay” tag (XEP-0203)

  • caption (Optional[str]) – an optional text that is linked to the file

Returns

The msg stanza that was sent

Return type

slixmpp.Message

__privileged_send(msg, when=None)[source]#
Parameters
carbon(body, legacy_id=None, when=None, *, reply_to_msg_id=None)[source]#

Call this when the user sends a message to a legacy network contact.

This synchronizes the outgoing message history on the XMPP side, using XEP-0356 to impersonate the XMPP user and send a message from the user to the contact. Thw XMPP server should in turn send carbons (XEP-0280) to online XMPP clients +/- write the message in server-side archives (XEP-0313), depending on the user’s and the server’s archiving policy.

Parameters
  • body (str) – Body of the message.

  • legacy_id (Optional[Any]) – Legacy message ID

  • when (Optional[datetime.datetime]) – When was this message sent.

  • reply_to_msg_id (Optional[slidge.util.types.LegacyMessageType]) –

async carbon_upload(filename, content_type=None, input_file=None, url=None, legacy_id=None, when=None, *, reply_to_msg_id=None)[source]#
Parameters
  • filename (Union[pathlib.Path, str]) –

  • content_type (Optional[str]) –

  • input_file (Optional[IO[bytes]]) –

  • url (Optional[str]) –

  • legacy_id (Optional[Any]) –

  • when (Optional[datetime.datetime]) –

  • reply_to_msg_id (Optional[slidge.util.types.LegacyMessageType]) –

carbon_read(legacy_msg_id, when=None)[source]#

Synchronize user read state from official clients.

Parameters
carbon_correct(legacy_msg_id, text, when=None, *, reply_to_msg_id=None)[source]#

Call this when the user corrects their own (last) message from an official client

Parameters
  • legacy_msg_id (slidge.util.types.LegacyMessageType) –

  • text (str) – The new body of the message

  • when (Optional[datetime.datetime]) –

  • reply_to_msg_id (Optional[slidge.util.types.LegacyMessageType]) –

carbon_react(legacy_msg_id, reactions=(), when=None)[source]#

Call this to modify the user’s own reactions (XEP-0444) about a message.

Can be called when the user reacts from the official client, or to modify a user’s reaction when the legacy network has constraints about acceptable reactions.

Parameters
  • legacy_msg_id (slidge.util.types.LegacyMessageType) – Legacy message ID this refers to

  • reactions (Iterable[str]) – iterable of emojis

  • when (Optional[datetime.datetime]) –

carbon_retract(legacy_msg_id, when=None)[source]#

Call this when the user calls retracts (XEP-0424) a message from an official client

Parameters
  • legacy_msg_id (slidge.util.types.LegacyMessageType) –

  • when (Optional[datetime.datetime]) –

Returns

correct(legacy_msg_id, new_text)[source]#

Call this when a legacy contact has modified his last message content.

Uses last message correction (XEP-0308)

Parameters
  • legacy_msg_id (Any) – Legacy message ID this correction refers to

  • new_text (str) – The new text

react(legacy_msg_id, emojis=())[source]#

Call this when a legacy contact reacts to a message

Parameters
  • legacy_msg_id (slidge.util.types.LegacyMessageType) – The message which the reaction refers to.

  • emojis (Iterable[str]) – A iterable of emojis used as reactions

Returns

retract(legacy_msg_id)[source]#

Call this when a legacy contact retracts (XEP-0424) a message

Parameters

legacy_msg_id (slidge.util.types.LegacyMessageType) – Legacy ID of the message to delete

static _add_delay(msg, when=None)[source]#
Parameters
slidge.core.contact.LegacyContactType[source]#
class slidge.core.contact.LegacyRoster(session)[source]#

Bases: Generic[LegacyContactType, slidge.core.session.SessionType]

Virtual roster of a gateway user, that allows to represent all of their contacts as singleton instances (if used properly and not too bugged).

Every BaseSession instance will have its own LegacyRoster instance accessible via the BaseSession.contacts attribute.

Typically, you will mostly use the LegacyRoster.by_legacy_id() function to retrieve a contact instance.

You might need to override LegacyRoster.legacy_id_to_jid_username() and/or LegacyRoster.jid_username_to_legacy_id() to incorporate some custom logic if you need some characters when translation JID user parts and legacy IDs.

Parameters

session (slidge.core.session.SessionType) –

__iter__()[source]#
by_jid(contact_jid)[source]#

Retrieve a contact by their JID

If the contact was not instantiated before, it will be created using slidge.LegacyRoster.jid_username_to_legacy_id() to infer their legacy user ID.

Parameters

contact_jid (slixmpp.JID) –

Returns

Return type

LegacyContactType

by_legacy_id(legacy_id)[source]#

Retrieve a contact by their legacy_id

If the contact was not instantiated before, it will be created using slidge.LegacyRoster.legacy_id_to_jid_username() to infer their legacy user ID.

Parameters

legacy_id (Any) –

Returns

Return type

LegacyContactType

by_stanza(s)[source]#

Retrieve a contact by the destination of a stanza

See slidge.Roster.by_legacy_id() for more info.

Parameters

s

Returns

Return type

LegacyContactType

static legacy_id_to_jid_username(legacy_id)[source]#

Convert a legacy ID to a valid ‘user’ part of a JID

Should be overridden for cases where the str conversion of the legacy_id is not enough, e.g., if it is case-sensitive or contains forbidden characters not covered by XEP-0106.

Parameters

legacy_id (Any) –

Return type

str

static jid_username_to_legacy_id(jid_username)[source]#

Convert a JID user part to a legacy ID.

Should be overridden in case legacy IDs are not strings, or more generally for any case where the username part of a JID (unescaped with to the mapping defined by XEP-0106) is not enough to identify a contact on the legacy network.

Default implementation is an identity operation

Parameters

jid_username (str) – User part of a JID, ie “user” in “user@example.com

Returns

An identifier for the user on the legacy network.

Return type

slidge.util.types.LegacyUserIdType

slidge.core.contact.LegacyRosterType[source]#
slidge.core.contact.ESCAPE_TABLE[source]#
slidge.core.contact.log[source]#