tracking — Interfaces for high-level message tracking

This submodule provides interfaces for tracking messages to the recipient. The actual tracking is not implemented here.

New in version 0.5: This module was added in version 0.5.

Changed in version 0.9: This module was completely rewritten in 0.9.

See also

Method send_tracked_message()

implements tracking for messages sent through a MUC.

General Remarks about Tracking and Memory Consumption

Tracking stanzas costs memory. There are basically two options on how to implement the management of additional information:

  1. Either the tracking stops when the MessageTracker is released (i.e. the last reference to it gets collected).

  2. Or the tracking is stopped explicitly by the user.

Option (1) has the appeal that users (applications) do not have to worry about properly releasing the tracking objects. However, it has the downside that applications have to keep the MessageeTracker instance around. Remember that connecting to callbacks of an object is not enough to keep it alive.

Option (2) is somewhat like file objects work: in theory, you have to close them explicitly and manually: if you do not, there is no guarantee when the file is actually closed. It is thus a somewhat known Python idiom, and also is more explicit. And it doesn’t break callbacks.

The implementation of MessageTracker uses Option 2. So you have to MessageTracker.close() all MessageTracker objects to ensure that all tracking resources associated with it are released; this stops any tracking which is still in progress.

It is strongly recommended that you close message trackers after a timeout. You can use MessageTracker.set_timeout() for that, or manually call MessageTracker.close() as desired.

Tracking implementations

class aioxmpp.tracking.BasicTrackingService(client, **kwargs)[source]

Error handling and StanzaToken-based tracking for messages.

This service provides the most basic tracking of message stanzas. It can be combined with other forms of tracking.

Specifically, the stanza is tracked using the means of StanzaToken, that is, until it is acknowledged by the server. In addition, error stanzas in reply to the message are also tracked (but they do not override states occurring after DELIVERED_TO_SERVER).

Tracking stanzas:

send_tracked(stanza, tracker)[source]

Send a message stanza with tracking.

Parameters
Return type

StanzaToken

Returns

The token used to send the stanza.

If tracker is None, a new MessageTracker is created.

This configures tracking for the stanza as if by calling attach_tracker() with a token and sends the stanza through the stream.

See also

attach_tracker()

can be used if the stanza cannot be sent (e.g. because it is a carbon-copy) or has already been sent.

attach_tracker(stanza, tracker=None, token=None)[source]

Configure tracking for a stanza without sending it.

Parameters
Return type

MessageTracker

Returns

The message tracker.

If tracker is None, a new MessageTracker is created.

If token is not None, updates to the stanza token are reflected in the tracker.

If an error reply is received, the tracker will enter ERROR and the error will be set as response.

You should use send_tracked() if possible. This method however is very useful if you need to track carbon copies of sent messages, as a stanza token is not available here and re-sending the message to obtain one is generally not desirable ☺.

Interfaces

class aioxmpp.tracking.MessageTracker[source]

This is the high-level equivalent of the StanzaToken.

This structure is used by different tracking implementations. The interface of this class is split in two parts:

  1. The public interface for use by applications.

  2. The “protected” interface for use by tracking implementations.

MessageTracker objects are designed to be drivable from multiple tracking implementations at once. The idea is that different tracking implementations can cover different parts of the path a stanza takes: one can cover the path to the server (by hooking into the events of a StanzaToken), the other implementation can use e.g. XEP-0184 to determine delivery at the target and so on.

Methods and attributes from the “protected” interface are marked by a leading underscore.

state

The current state of the tracking. Read-only.

response

A stanza which is relevant to the current state. For MessageState.ERROR, this will generally be a MessageType.ERROR stanza. For other states, this is either None or another stanza depending on the tracking implementation.

closed

Boolean indicator whether the tracker is closed.

See also

close() for details.

signal on_state_changed(new_state, response=None)

Emits when a new state is entered.

Parameters

  • new_state (MessageState member) – The new state of the tracker.

  • response (StanzaBase or None) – A stanza related to the state.

The is not emitted when the tracker is closed.

signal on_closed()

Emits when the tracker is closed.

close()[source]

Close the tracking, clear all references to the tracker and release all tracking-related resources.

This operation is idempotent. It does not change the state, but closed turns True.

The on_closed() event is only fired on the first call to close().

set_timeout(timeout)[source]

Automatically close the tracker after timeout has elapsed.

Parameters

timeout (numbers.Real or datetime.timedelta) – The timeout after which the tracker is closed automatically.

If the timeout is not a datetime.timedelta instance, it is assumed to be given as seconds.

The timeout cannot be cancelled after it has been set. It starts at the very moment set_timeout() is called.

“Protected” interface:

_set_state(new_state, response=None)[source]

Set the state of the tracker.

Parameters

  • new_state (MessageState member) – The new state of the tracker.

  • response (StanzaBase or None) – A stanza related to the new state.

Raises

The state of the tracker is set to the new_state. The response is also overridden with the new value, no matter if the new or old value is None or not. The on_state_changed() event is emitted.

The following transitions are forbidden and attempting to perform them will raise ValueError:

If the tracker is already close()-d, RuntimeError is raised. This check happens before a test is made whether the transition is valid.

This method is part of the “protected” interface.

class aioxmpp.tracking.MessageState(value)[source]

Enumeration of possible states for MessageTracker. These states are used to inform using code about the delivery state of a message. See MessageTracker for details.

Changed in version 0.10: The ERROR state is no longer final. Tracking implementations may now trump an error state with another state in some cases.

An example would be XEP-0184 message delivery receipts which can for sure attest an DELIVERED_TO_RECIPIENT state. This is more useful than an error reply.

ABORTED

The message has been aborted or dropped in the StanzaStream queues. See StanzaToken and MessageTracker.token.

This is a final state.

ERROR

An error reply stanza has been received for the stanza which was sent.

This is, in most cases, a final state, but transitions to DELIVERED_TO_RECIPIENT and SEEN_BY_RECIPIENT are allowed.

IN_TRANSIT

The message is still queued for sending or has been sent to the peer server without stream management.

Depending on the tracking implementation, this may be a final state.

DELIVERED_TO_SERVER

The message has been delivered to the server and the server acked the delivery using stream management.

Depending on the tracking implementation, this may be a final state.

DELIVERED_TO_RECIPIENT

The message has been delivered to the recipient.

Depending on the tracking implementation, this may be a final state.

SEEN_BY_RECIPIENT

The recipient has marked the message as seen or read. This is a final state.