skidge

Submodules

• skidge.__main__

Attributes

Recipient
log
__version__

Classes

Gateway	The gateway component, handling registrations and un-registrations.
Contact	This class centralizes actions in relation to a specific legacy contact.
ListenThread	A class that represents a thread of control.
Roster	Virtual roster of a gateway user, that allows to represent all
Session	The session of a registered User.

Functions

main()
handle_thread_exception(args)

Package Contents

class skidge.Gateway

Bases: slidge.BaseGateway

The gateway component, handling registrations and un-registrations.

On slidge launch, a singleton is instantiated, and it will be made available to public classes such LegacyContact or BaseSession as the .xmpp attribute.

Must be subclassed by a legacy module to set up various aspects of the XMPP component behaviour, such as its display name or welcome message, via class attributes COMPONENT_NAME WELCOME_MESSAGE.

Abstract methods related to the registration process must be overriden for a functional Legacy Module:

• validate()

• validate_two_factor_code()

• get_qr_text()

• confirm_qr()

NB: Not all of these must be overridden, it depends on the REGISTRATION_TYPE.

The other methods, such as send_text() or react() are the same as those of LegacyContact and LegacyParticipant, because the component itself is also a “messaging actor”, ie, an XMPP Entity. For these methods, you need to specify the JID of the recipient with the mto parameter.

Since it inherits from slixmpp.componentxmpp.ComponentXMPP,you also have a hand on low-level XMPP interactions via slixmpp methods, e.g.:

self.send_presence(
    pfrom="somebody@component.example.com",
    pto="someonwelse@anotherexample.com",
)

However, you should not need to do so often since the classes of the plugin API provides higher level abstractions around most commonly needed use-cases, such as sending messages, or displaying a custom status.

REGISTRATION_INSTRUCTIONS = 'Enter skype credentials'

The text presented to a user that wants to register (or modify) their legacy account configuration.

REGISTRATION_FIELDS

Iterable of fields presented to the gateway user when registering using XEP-0077 extended by XEP-0004.

ROSTER_GROUP = 'Skype'

Name of the group assigned to a LegacyContact automagically added to the User’s roster with LegacyContact.add_to_roster().

COMPONENT_NAME = 'Skype (slidge)'

Name of the component, as seen in service discovery by XMPP clients

COMPONENT_TYPE = 'skype'

Type of the gateway, should follow https://xmpp.org/registrar/disco-categories.html

COMPONENT_AVATAR = 'https://logodownload.org/wp-content/uploads/2017/05/skype-logo-1-1-2048x2048.png'

Path, bytes or URL used by the component as an avatar.

async validate(user_jid, registration_form)

Validate a user’s initial registration form.

Should raise the appropriate slixmpp.exceptions.XMPPError if the registration does not allow to continue the registration process.

If REGISTRATION_TYPE is a RegistrationType.SINGLE_STEP_FORM, this method should raise something if it wasn’t possible to successfully log in to the legacy service with the registration form content.

It is also used for other types of REGISTRATION_TYPE too, since the first step is always a form. If REGISTRATION_FIELDS is an empty list (ie, it declares no FormField), the “form” is effectively a confirmation dialog displaying REGISTRATION_INSTRUCTIONS.

Parameters:

• user_jid (slixmpp.JID) – JID of the user that has just registered

• registration_form (dict[str, Optional[str]]) – A dict where keys are the FormField.var attributes of the BaseGateway.REGISTRATION_FIELDS iterable. This dict can be modified and will be accessible as the legacy_module_data of the

:returnA dict that will be stored as the persistent “legacy_module_data”

for this user. If you don’t return anything here, the whole registration_form content will be stored.

class skidge.Contact(*a, **kw)

Bases: slidge.LegacyContact[str]

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:

Use carbon=True as a keyword arg for methods to represent an action FROM the user TO the contact, typically when the user uses an official client to do an action such as sending a message or marking as message as read. This will use XEP-0363 to impersonate the XMPP user in order.

Parameters:

• session – The session this contact is part of

• legacy_id – The contact’s legacy ID

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

session: Session

_mood: str | None = None

serialize_extra_attributes()

Return type:

Optional[dict]

deserialize_extra_attributes(data)

Parameters:

data (dict) –

Return type:

None

update_presence(status)

Parameters:

status (skpy.SkypeUtils.Status) –

async update_info(contact=None)

Fetch information about this contact from the legacy network

This is awaited on Contact instantiation, and should be overridden to update the nickname, avatar, vcard […] of this contact, by making “legacy API calls”.

To take advantage of the slidge avatar cache, you can check the .avatar property to retrieve the “legacy file ID” of the cached avatar. If there is no change, you should not call slidge.core.mixins.avatar.AvatarMixin.set_avatar() or attempt to modify the .avatar property.

Parameters:

contact (Optional[skpy.SkypeContact]) –

class skidge.ListenThread(session, *a, **kw)

Bases: threading.Thread

A class that represents a thread of control.

This class can be safely subclassed in a limited fashion. There are two ways to specify the activity: by passing a callable object to the constructor, or by overriding the run() method in a subclass.

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is a list or tuple of arguments for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

Parameters:

session (Session) –

name

A string used for identification purposes only.

It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

session

_target

stop_event

skype_blocking()

stop()

class skidge.Roster(session)

Bases: slidge.LegacyRoster

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.BaseSession) –

session: Session

async fill()

Populate slidge’s “virtual roster”.

This should yield contacts that are meant to be added to the user’s roster, typically by using await self.by_legacy_id(contact_id). Setting the contact nicknames, avatar, etc. should be in LegacyContact.update_info()

It’s not mandatory to override this method, but it is recommended way to populate “friends” of the user. Calling await (await self.by_legacy_id(contact_id)).add_to_roster() accomplishes the same thing, but doing it in here allows to batch DB queries and is better performance-wise.

skidge.Recipient

class skidge.Session(user)

Bases: slidge.BaseSession[int, Recipient]

The session of a registered User.

Represents a gateway user logged in to the legacy network and performing actions.

Will be instantiated automatically on slidge startup for each registered user, or upon registration for new (validated) users.

Must be subclassed for a functional Legacy Module.

skype_token_path: pathlib.Path

sk: skpy.Skype

thread: ListenThread | None = None

sent_by_user_to_ack

unread_by_user

send_lock

async login()

Logs in the gateway user to the legacy network.

Triggered when the gateway start and on user registration. It is recommended that this function returns once the user is logged in, so if you need to await forever (for instance to listen to incoming events), it’s a good idea to wrap your listener in an asyncio.Task.

Returns:

Optionally, a text to use as the gateway status, e.g., “Connected as ‘dude@legacy.network’”

async on_skype_event(event)

Parameters:

event (skpy.SkypeEvent) –

async on_text(chat, text, **k)

Triggered when the user sends a text message from XMPP to a bridged entity, e.g. to translated_user_name@slidge.example.com, or translated_group_name@slidge.example.com

Override this and implement sending a message to the legacy network in this method.

Parameters:

• text (str) – Content of the message

• chat (Recipient) – Recipient of the message. LegacyContact instance for 1:1 chat, MUC instance for groups.

• reply_to_msg_id – A legacy message ID if the message references (quotes) another message (XEP-0461)

• reply_to_fallback_text – Content of the quoted text. Not necessarily set by XMPP clients

• reply_to – Author of the quoted message. LegacyContact instance for 1:1 chat, LegacyParticipant instance for groups. If None, should be interpreted as a self-reply if reply_to_msg_id is not None.

• link_previews – A list of sender-generated link previews. At the time of writing, only Cheogram supports it.

• mentions – (only for groups) A list of Contacts mentioned by their nicknames.

• thread –

Returns:

An ID of some sort that can be used later to ack and mark the message as read by the user

async logout()

Logs out the gateway user from the legacy network.

Called on gateway shutdown.

async on_file(chat, url, http_response, **kwargs)

Triggered when the user sends a file using HTTP Upload (XEP-0363)

Parameters:

• url (str) – URL of the file

• chat (Recipient) – See BaseSession.on_text()

• http_response – The HTTP GET response object on the URL

• reply_to_msg_id – See BaseSession.on_text()

• reply_to_fallback_text – See BaseSession.on_text()

• reply_to – See BaseSession.on_text()

• thread –

Returns:

An ID of some sort that can be used later to ack and mark the message as read by the user

async on_composing(c, thread=None)

Triggered when the user starts typing in a legacy chat (XEP-0085)

Parameters:

• chat – See BaseSession.on_text()

• thread –

• c (Recipient) –

async on_paused(c, thread=None)

Triggered when the user pauses typing in a legacy chat (XEP-0085)

Parameters:

• chat – See BaseSession.on_text()

• thread –

• c (Recipient) –

async on_displayed(c, legacy_msg_id, thread=None)

Triggered when the user reads a message in a legacy chat. (XEP-0333)

This is only possible if a valid legacy_msg_id was passed when transmitting a message from a legacy chat to the user, eg in slidge.contact.LegacyContact.send_text() or slidge.group.LegacyParticipant.send_text().

Parameters:

• chat – See BaseSession.on_text()

• legacy_msg_id (int) – Identifier of the message/

• thread –

• c (Recipient) –

async on_correct(c, text, legacy_msg_id, thread=None, link_previews=(), mentions=None)

Triggered when the user corrects a message using XEP-0308

This is only possible if a valid legacy_msg_id was returned by on_text().

Parameters:

• chat – See BaseSession.on_text()

• text (str) – The new text

• legacy_msg_id (Any) – Identifier of the edited message

• thread –

• link_previews –

  A list of sender-generated link previews. At the time of writing, only Cheogram supports it.

• mentions – (only for groups) A list of Contacts mentioned by their nicknames.

• c (Recipient) –

async on_retract(c, legacy_msg_id, thread=None)

Triggered when the user retracts (XEP-0424) a message.

Parameters:

• chat – See BaseSession.on_text()

• thread –

• legacy_msg_id (Any) – Legacy ID of the retracted message

• c (Recipient) –

async on_search(form_values)

Triggered when the user uses Jabber Search (XEP-0055) on the component

Form values is a dict in which keys are defined in BaseGateway.SEARCH_FIELDS

Parameters:

form_values (dict[str, str]) – search query, defined for a specific plugin by overriding in BaseGateway.SEARCH_FIELDS

Returns:

get_msg(legacy_msg_id, contact)

Parameters:

• legacy_msg_id (int) –

• contact (Recipient) –

Return type:

skpy.SkypeTextMsg

skidge.main()

skidge.handle_thread_exception(args)

Parameters:

args (threading.ExceptHookArgs) –

skidge.log

skidge.__version__ = '0.0.0-dev+20241007_git7160e13f54'