query

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

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 server failed, because the connection was closed or for other reasons.

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

Bases: object

The TS3 query client.

This class provides only the methods to handle the connection to a TeamSpeak 3 Server. For a more convenient interface, use the TS3Connection 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!

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

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

Connect to the TS3 Server listening on the address given by the host and port parmeters. If timeout is provided, this is the maximum time in seconds for the connection attempt.

Raises:

• OSError – If the client is already connected.
• TimeoutError – If the connection can not be created.

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=60)
    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 server to prevent automatic disconnect. Make sure to call it at least once in 5 minutes (better each minute).

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

The general structure of a query command is:

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

Examples are here worth a thousand words:

>>> # 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"]
...     )

See also

recv(), wait_for_resp()

class ts3.query.TS3Connection(host=None, port=10011)

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

TS3 server query client.

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

>>> with TS3Connection("localhost") as tsconn:
...     # From the TS3Commands class:
...     ts3conn.login("serveradmin", "FooBar")
...     ts3conn.clientkick(1)

quit()

Closes the connection.