API Reference¶

The following docs outline the classes involved in backtracked.

Client¶

class backtracked.Client(**kwargs)[source]¶

The client class is the main class you should be using to communicate with the QueUp API. It provides methods for handling events and non-room-specific functions.

All parameters are optional.

Parameters

connector (aiohttp.BaseConnector) – A custom aiohttp connector may be passed if desired. This is to allow proxying.
proxy_options (ProxyOptions) – Proxy options, if proxying is required.
recent_conversations (bool) – If True, calls Client.fetch_conversations() after you have logged in. Defaults to True.

user¶

The logged-in user. Populated after a successful login call, None otherwise.

Type: AuthenticatedUser

logged_in¶

True if logged in, False otherwise.

Type: bool

rooms¶

Cached rooms that the bot has joined at least once this session.

Type: RoomCollection

users¶

Cached users the bot has seen.

Type: Collection

messages¶

Messages received during this session.

Type: MessageCollection

await connect()[source]¶: Connect to the QueUp websocket. You must call login first.

event(coro)[source]¶: Decorator used for registering event handlers.

await fetch_conversations()[source]¶

Fetch currently open conversations from QueUp.

This method is called automatically if the parameter recent_conversations is True when initializing this Client.

await join_room(room_slug: str) → backtracked.models.room.Room[source]¶

Join a QueUp room via its URL slug.

Parameters: room_slug (str) – the room’s slug
Returns: Room object of the joined room
Return type: Room

await login(email: str, password: str)[source]¶

Log in to QueUp. This does not connect to the websocket.

Parameters

email (str) – Bot email
password (str) – Bot password

Raises

AuthorizationError – If the username or password is invalid.

run(email, password)[source]¶

Log in to QueUp and connect to the websocket. This call is blocking, and abstracts away event loop creation. If you need more control over the event loop, use login and connect.

Parameters

email (str) – Bot email
password (str) – Bot password

Data Classes¶

These classes should never be constructed. They are given to you in the various events and methods in the library.

Important

Creating the data classes yourself will result in pain and suffering.

Room¶

class backtracked.Room(client, data: dict)[source]¶

Represents a room on QueUp that may or may not be currently joined.

id¶

ID of this room.

Type: str

name¶

Name of this room.

Type: str

description¶

Description of this room.

Type: str

slug¶

Slug used for joining this room, seen in the URL upon room join.

Type: str

rtc¶

Real-time channel identifier for this room.

Type: str

type¶

Type of this room

Type: str

is_public¶

True if this room is public, False otherwise.

Type: bool

lang¶

Preferred language for talking in this room. Can be None.

Type: str

music_type¶: Music type for this room.

await change_presence(presence: backtracked.client.constants.Presence)[source]¶

Change the logged-in user’s presence in this room.

Parameters: presence (Presence) – Presence enum representing the desired presence.

await send_message(text: str)[source]¶

Sends a message to this room.

Parameters: text (str) – Text to send in the message.
Returns: The sent message.
Return type: Message

User¶

class backtracked.User(client, data: dict)[source]¶

Represents a specific user on QueUp.

id¶

ID of this user.

Type: str

username¶

User’s chosen username.

Type: str

created_at¶

Datetime representing the date when this user created their account.

Type: datetime.datetime

avatar_url¶

URL of this user’s avatar. May be None.

Type: str

member_of(room)[source]¶

Returns the Member object of this user in the given Room. May be None if the member hasn’t yet been backfilled.

Parameters: room (Room) – Room of the sought-after member.
Returns: Requested member or None.
Return type: Member

await open_conversation()[source]¶

Opens a conversation with this user. Will re-use a previous conversation if the bot has one cached.

Returns: A conversation with this user as the recipient.
Return type: Conversation

Member¶

class backtracked.Member(client, data: dict)[source]¶

Represents a QueUp user’s data from a specific Room. This does not subclass User, as QueUp itself does not count them as the same entity. Instead, the user getter should be used for retrieving the associated user.

id¶

The ID of this member.

Type: str

dubs¶

Total dubs this member has received in the associated Room

Type: int

order¶

Location of this user in the queue

Type: int

authorized¶

No idea tbh

Type: bool

skipped¶

Number of songs queued by this member that have been skipped.

Type: int

played¶

Number of songs queued by this member that have been played.

Type: int

queued_now¶

Number of songs in the current queue queued by this member.

Type: int

wait_line¶

Type: int

banned¶

True if this member is banned, False otherwise

Type: bool

banned_time¶

Datetime representing the time this member was banned. Useless if banned is False.

Type: datetime.datetime

banned_until¶

Datetime representing the time this member will be unbanned. Useless if banned is False.

Type: datetime.datetime

role¶

Get this user’s assigned role, or None if the user has no role.

Returns: Assigned role of this member.
Return type: Role

room¶

Gets the room this member object is assigned to.

Returns: Room of this member
Return type: Room

await set_role(role: backtracked.client.constants.Role)[source]¶

Sets the role of this member, if the bot has the required right.

Parameters: role (Role) – Role to give the member.

user¶

User object associated with this member object.

Returns: User behind this Member
Return type: User

AuthenticatedUser¶

class backtracked.AuthenticatedUser(client, data: dict)[source]¶

Represents the logged-in user. Subclass of User, and inherits all its properties.

await change_username(username)[source]¶

Change this account’s username.

Parameters: username (str) – New username to use
Returns: True if the username was successfully changed, False otherwise.
Return type: bool

Message¶

class backtracked.Message(client, data: dict)[source]¶

Represents a sent message on QueUp.

id¶

Chat ID of this message.

Type: str

content¶

Text of the message.

Type: str

deleted¶

True if the message has been deleted, False otherwise.

Type: bool

created_at¶

Datetime representing the time this message was sent.

Type: datetime.datetime

author¶

Get the author of this message.

Returns: Author of this message
Return type: User

member¶

Get the author of this message as a member of the room.

Returns: Member who sent this message.
Return type: Member

room¶

Get the room this message was sent in. If this message was sent in a private conversation, this will be None.

Returns: Room this message was sent to.
Return type: Room

Conversation¶

class backtracked.Conversation(client, data: dict)[source]¶

Represents a private conversation between two users.

id¶

ID of this conversation.

Type: str

created_at¶

Time this conversation was started.

Type: datetime.datetime

latest_message_str¶

Text of the last message to be sent in this conversation. May not be up-to-date unless fetch() is called.

Type: str

await fetch() → list [source]¶

Fetch all messages for this conversation.

Returns: List of message IDs in this conversation.
Return type: list[str]

has_read(user: backtracked.models.user.User) → bool [source]¶

Checks if the passed User has read this conversation.

Parameters: user (User) – User to check
Returns: True if the user has read this conversation, False otherwise.
Return type: bool

await mark_as_read()[source]¶: Marks this conversation as read by the current user.

recipients¶

Get the recipients of this conversation.

Returns: Recipients of this conversation.
Return type: list[User]

await send_message(text: str)[source]¶

Send a message to this conversation.

Parameters: text (str) – Text to send in the message.

Song¶

class backtracked.Song(client, data: dict)[source]¶

Represents a song on QueUp that will play, is playing, or has played in the past.

id¶

ID of this song entry

Type: str

created_at¶

Datetime representing the time this song was added.

Type: datetime.datetime

played_at¶

Datetime representing the time this song was played.

Type: datetime.datetime

active¶

True if this song is currently playing, False otherwise

Type: bool

played¶

True if this song was played in the past, False otherwise

Type: bool

skipped¶

True if this song was skipped, False otherwise.

Type: bool

order¶

Order of this song

Type: int

length¶

Length of this song’s assigned media in milliseconds. You can use backtracked.utils.song_length() to convert this to a human-readable string.

Type: int

up_dubs¶

Number of updubs this song has received.

Type: int

down_dubs¶

Number of downdubs this song has received.

Type: int

net_dubs¶

Total number of dubs this song has received.

Returns: Net number of dubs
Return type: int

room¶

Get the room this playlist entry was added to.

Returns: Room this song exists in.
Return type: Room

song_info¶

Get the media information object for this song.

Returns: Media information object for this playlist entry.
Return type: SongInfo

user¶

Get the user who added this playlist entry.

Returns: User who added this playlist entry.
Return type: User

SongInfo¶

class backtracked.SongInfo(data: dict)[source]¶

Represents a specific media from a specific media source.

id¶

QueUp ID of this media object.

Type: str

name¶

Source-provided name of this media object.

Type: str

media_id¶

Source’s ID for this media object.

Type: str

source¶

Name of the source that provided this media object.

Type: str

created_at¶

Datetime representing the time this media was created at the source.

Type: datetime.datetime

length¶

Length of this media in milliseconds. You can use backtracked.utils.song_length() to convert this to a human-readable string.

Type: int

thumbnail¶

URL of the thumbnail for this media.

Type: str

Helper Classes¶

These classes can be created by the user, and are used for supplying information to certain methods.

ProxyOptions¶

class backtracked.ProxyOptions(proxy_url: str, client_request: Optional[aiohttp.client_reqrep.ClientRequest] = None)[source]¶

Used to pass proxy options to the HTTP and WebSocket clients.

Parameters

proxy_url (str) – Proxy URL used by aiohttp. Certain connectors will use this option.
client_request (aiohttp.ClientRequest) – Custom ClientRequest, if needed for your proxy solution.

Examples

aiosocks socks4 proxy example:

from backtracked import Client, ProxyOptions
from aiosocks import connector

proxy_opts = ProxyOptions("socks4://127.0.0.1:1080", client_request=connector.ProxyClientRequest)
c = Client(connector=connector.ProxyConnector(), proxy_options=proxy_opts)

@c.event
async def on_ready():
    print("Logged in as {0.username}".format(c.user))

c.run("email", "password")

Enums¶

Classes here extend python’s builtin Enum class. Some attributes use these objects, and some parameters take these objects.

Presence¶

class backtracked.Presence(value)[source]¶

Represents a member’s presence in a room.

enter¶: “Visible” presence

exit¶: “Invisible” presence

Role¶

class backtracked.Role(value)[source]¶

Represents a possible role that may be assigned to a member.

resident_dj¶: Resident DJ role.

vip¶: VIP role.

moderator¶: Moderator role (can kick+ban)

manager¶: Manager role

co_owner¶: Co-Owner role

Utilities¶

The utils module contains several helper functions useful for converting and extracting information from various sources.

backtracked.utils.dt(msts: int) → datetime.datetime [source]¶

Converts a JavaScript-style timestamp (milliseconds) to a Python datetime.

Parameters: msts (int) – Timestamp to convert
Returns: Python datetime representing the passed date
Return type: datetime.datetime

backtracked.utils.get(iterable: collections.abc.Iterable, **attrs)[source]¶

Finds the first object in an iterable that has all attributes present and equal to their value

Parameters

iterable (Iterable) – Iterable of objects to check
attrs (kwargs) – Key-value pairs of attributes to check against

Returns

First element in the iterable that has all the required attributes

Return type

object

backtracked.utils.song_length(length: int, format='%M:%S')[source]¶

Convert a song length in milliseconds to a human-readable format, e.g. 03:54.

Parameters

length (int) – Length in milliseconds to convert
format (str) – Optional custom format, to change the output. Passed to datetime.datetime.strftime().

Returns

String representing the length of time according to the format string.

Return type

str

backtracked.utils.ts(time: datetime.datetime) → float [source]¶

Converts a Python datetime to a JavaScript-style timestamp (milliseconds). Not 100% accurate.

Parameters: time (datetime.datetime) – Datetime to convert.
Returns: Number of milliseconds elapsed since 1970.
Return type: float

backtracked.utils.tzdt(fulldate: str)[source]¶

Converts an ISO 8601 full timestamp to a Python datetime.

Parameters: fulldate (str) – ISO 8601 UTC timestamp, e.g. 2017-06-02T16:23:14.815Z
Returns: Python datetime representing ISO timestamp.
Return type: datetime.datetime

API Reference¶

Client¶

Data Classes¶

Room¶

User¶

Member¶

AuthenticatedUser¶

Message¶

Conversation¶

Song¶

SongInfo¶

Helper Classes¶

ProxyOptions¶

Enums¶

Presence¶

Role¶

Utilities¶

backtracked

Navigation

Related Topics