query

This module contains a high-level API for the TeamSpeak 3 Server Query and Client Query plugin.

Changed in version 2.0.0: The TS3Connection class has been renamed to TS3ServerConnection.

New in version 2.0.0: The TS3ClientConnection class has been added.

exception ts3.query.TS3QueryError(resp)

Bases: ts3.common.TS3Error

Raised, if the error code of the response was not 0.

resp = None

The TS3Response instance with the response data.

exception ts3.query.TS3TimeoutError

Bases: ts3.common.TS3Error, TimeoutError

Raised, if a response or event could not be received due to a timeout.

exception ts3.query.TS3RecvError

Bases: ts3.common.TS3Error

Raised if receiving data from the endpoint failed, because the connection was closed or for other reasons.

class ts3.query.TS3BaseConnection(host=None, port=None)

Bases: object

The TS3 query client.

This class provides only the methods to handle the connection to a TeamSpeak 3 query service. For a more convenient interface, use the TS3ServerConnection or TS3ClientConnection class.

Note, that this class supports the with statement:

>>> with TS3BaseConnection() as ts3conn:
...     ts3conn.open("localhost")
...     ts3conn.send(...)
>>> # This is equal too:
>>> ts3conn = TS3BaseConnection()
>>> try:
...     ts3conn.open("localhost")
...     ts3conn.send(...)
... finally:
...     ts3conn.close()

Warning

This class is not thread safe!

DEFAULT_PORT = None

The default port to use when no port is specified.

GREETING_LENGTH = None

The length of the greeting. This is the number of lines returned by the query service after successful connection.

For example, the TS3 Server Query returns these lines upon connection:

b'TS3\n\r'
b'Welcome to the [...] on a specific command.\n\r'

telnet_conn

Getter:If the client is connected, the used Telnet instance else None. Type:None or telnetlib.Telnet.

is_connected()

Returns:True, if the client is currently connected. Return type:bool

conn()

open(host, port=None, timeout=<object object>)

Connect to the TS3 query service listening on the address given by the host and port parameters. If timeout is provided, this is the maximum time in seconds for the connection attempt. If no port is provided, then the DEFAULT_PORT is used.

raises OSError:If the client is already connected. raises TimeoutError:  If the connection can not be created.

Changed in version 2.0.0: This method does not consume the greeting anymore:

b'TS3

‘

b’Welcome to the […] on a specific command.

‘

close()

Sends the quit command and closes the telnet connection.

fileno()

Returns:The fileno() of the socket object used internally. Return type:int

wait_for_event(timeout=None)

Blocks until an event is received or the timeout exceeds. The next received event is returned.

A simple event loop looks like this:

ts3conn.servernotifyregister(event="server")
while True:
    ts3conn.send_keepalive()
    try:
        event = ts3conn.wait_for_event(timeout=540)
    except TS3TimeoutError:
        pass
    else:
        # Handle the received event here ...

Parameters:

timeout (None or float) – The maximum number of seconds waited for the next event.

Return type:

TS3Event

Returns:

The next received ts3 event.

Raises:

• TS3TimeoutError –
• TS3RecvError –

send_keepalive()

Sends an empty query to the endpoint to prevent automatic disconnect. Make sure to call it at least once in 10 minutes.

send(command, common_parameters=None, unique_parameters=None, options=None, properties=None, timeout=None)

The general structure of a query command is:

<command> <options> <common parameters> <unique parameters>|<unique parameters>|...
<command> <options> <common parameter> <properties>

Example:

>>> # clientaddperm cldbid=16 permid=17276 permvalue=50 permskip=1|permid=21415 permvalue=20 permskip=0
>>> ts3conn.send(
...     command = "clientaddperm",
...     common_paramters = {"cldbid": 16},
...     parameterlist = [
...         {"permid": 17276, "permvalue": 50, "permskip": 1},
...         {"permid": 21415, "permvalue": 20, "permskip": 0}
...         ]
...     )
>>> # clientlist -uid -away
>>> ts3conn.send(
...     command = "clientlist",
...     options = ["uid", "away"]
...     )

New in version 2.0.0:

• The properties parameter

See also

recv(), wait_for_resp()

class ts3.query.TS3ServerConnection(host=None, port=None)

Bases: ts3.query.TS3BaseConnection, ts3.commands.TS3ServerCommands

TS3 Server Query client.

This class provides the command wrapper capabilities TS3ServerCommands and the ability to handle a connection to a TeamSpeak 3 server of TS3BaseConnection.

Use this class to connect to a TS3 Server.

>>> with TS3ServerConnection("localhost") as tsconn:
...     ts3conn.login("serveradmin", "MyStupidPassword")
...     ts3conn.clientkick(1)

DEFAULT_PORT = 10011

The default port of the server query service.

GREETING_LENGTH = 2

The typical TS3 Server greeting:

b'TS3\n\r'
b'Welcome to the [...] on a specific command.\n\r'

quit()

Closes the connection.

class ts3.query.TS3ClientConnection(host=None, port=None)

Bases: ts3.query.TS3BaseConnection, ts3.commands.TS3ClientCommands

TS3 Client Query client.

This class provides the command wrapper capabilities TS3ClientCommands and the ability to handle a connection to a TeamSpeak 3 server of TS3BaseConnection.

Use this class if you want to connect to a TS3 Client.

>>> with TS3ClientConnection("localhost") as tsconn:
...     ts3conn.auth(apikey="AAAA-BBBB-CCCC-DDDD-EEEE")
...     ts3conn.use()

DEFAULT_PORT = 25639

The default port of the server query service.

GREETING_LENGTH = 4

The typical TS3 Server greeting:

b'TS3 Client\n\r'
b'Welcome to the TeamSpeak 3 ClientQuery interface [...].\n\r'
b'Use the "auth" command to authenticate yourself. [...].\n\r'
b'selected schandlerid=1\n\r'

quit()

Closes the connection.