ts3.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.TS3InvalidCommandError(cmd, valid_cmds)

Bases: ts3.common.TS3Error, ValueError

Raised if a TS3QueryBuilder is constructed with an unknown command.

Seealso:TS3BaseConnection.COMMAND_SET

cmd = None

The unknown command.

valid_cmds = None

A set with all allowed (known) commands.

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.TS3TransportError

Bases: ts3.common.TS3Error

Raised if something goes wrong on the transport level, e.g. a connection cannot be established or has already been closed.

Seealso:TS3Transport

class ts3.query.TS3BaseConnection(uri=None, tp_args=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("ssh://serveradmin:Z0YxRb7u@localhost:10022") as ts3conn:
    ts3conn.exec_("use", sid=1)

# You can also use an equal try-finally construct.
ts3conn = TS3BaseConnection()
try:
    ts3conn.open_uri("telnet://serveradmin:Z0YxRb7u@localhost:10011")
    ts3conn.exec_("use", sid=1)
finally:
    ts3conn.close()

Warning

• This class is not thread safe.
• Do not reuse already connected instances.

Changed in version 2.0.0:

• The send() method has been removed, use exec_(), query() instead.

• SSH support

• The open_uri() method.

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'

COMMAND_SET = set()

A set with all known commands.

is_connected()

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

host

The hostname of the host of the query service.

open(host, port, timeout=None, protocol='telnet', tp_args=None)

Connect to the TS3 query service.

# Connect using telnet.
ts3conn.open("localhost", 10011)

# Connect using ssh.
ts3conn.open("localhost", 10022, protocol="ssh", tp_args={
    "username": "serveradmin", "password": "123456"
})

Parameters:

• host (str) – The hostname
• port (int) – The listening port of the service.
• timeout (int) – If not None, an exception is raised if the connection cannot be established within timeout seconds.
• protocol (str) – The protocol to be used. The TS3 server supports ssh and telnet, while the client only supports telnet.
• tp_args (dict) – A dictionary with parameters that are passed to the connect() method of the used transport. The SSH protocol for example requires a username and password.

Raises:

• TS3TransportError – If the client is already connected or the connection cannot be established.
• TS3TimeoutError – If the connection cannot be established within the specified timeout.

Seealso:

open_uri()

open_uri(uri, timeout=None, tp_args=None)

The same as open(), but the host, port, username, password, … are encoded compact in a URI.

>>> ts3conn.open_uri("telnet://my.server.com:10011")
>>> ts3conn.open_uri("ssh://serveradmin@123456@my.server.com:10022")

close(timeout=None)

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.query("servernotifyregister", event="server").exec()
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 query service in order to prevent automatic disconnect. Make sure to call it at least once in 5 minutes.

exec_(cmd, *options, **params)

Sends a command to the TS3 server and returns the response. Check out the query() method if you want to make use of pipelining and more control.

# use sid=1
ts3conn.exec_("use", sid=1)

# clientlist -uid -away -groups
resp = ts3conn.exec_("clientlist", "uid", "away", "groups")

Parameters:

• cmd (str) – A TS3 command
• options – The options of a command without a leading minus, e.g. 'uid', 'away'.
• params – Some parameters (key, value pairs) which modify the command, e.g. sid=1.

Return type:

TS3QueryResponse

Returns:

A object which contains all information about the response.

Seealso:

wait_for_resp()

Versionadded:

2.0.0

query(cmd, *options, **params)

Note

The query() method is great if you want to fetch data from the server or want to pipeline parameters on the same command.

If you are only interested in getting the command executed, then you are probably better off using exec_().

Returns a new TS3QueryBuilder object with the first pipe being initialised with the options and params:

# serverlist
q = ts3conn.query("serverlist")

# clientlist -uid -away -groups
q = ts3conn.query("clientlist", "uid", "away", "groups")

# clientdbfind pattern=ScP
q = ts3conn.query("clientdbfind", pattern="ScP")

# clientdbfind pattern=FPMPSC6MXqXq751dX7BKV0JniSo= -uid
q = ts3conn.query("clientdbfind", "uid", pattern="FPMPSC6MXqXq751dX7BKV0JniSo")

# clientkick reasonid=5 reasonmsg=Go\saway! clid=1|clid=2|clid=3
q = ts3conn.query("clientkick", reasonid=5, reasonmsg="Go away!")\
    .pipe(clid=1).pipe(clid=2).pipe(clid=3)

# channelmove cid=16 cpid=1 order=0
q = ts3conn.query("channelmove", cid=16, cpid=1, order=0)

# sendtextmessage targetmode=2 target=12 msg=Hello\sWorld!
q = ts3conn.query("sendtextmessage", targetmode=2, target=12, msg="Hello World!")

Queries are executed once the fetch(), first() or all() is invoked:

# Returns a TS3Response object.
resp = q.fetch()

# Returns the first item in the response or *None*.
resp = q.first()

# Returns a list with all items in the response rather
# than a TS3Response object.
resp = q.all()

Parameters:

• options – All initial options in the first pipe.
• params – All initial parameters (key value pairs) in the first pipe.

Return type:

TS3QueryBuilder

Returns:

A query builder initialised with the options and params.

Versionadded:

2.0.0

exec_query(query, timeout=None)

Sends the query to the server, waits and returns for the response.

Parameters:query (TS3QueryBuilder) – The query which should be executed. Return type:TS3QueryResponse Returns:A object which contains all information about the response. Seealso:wait_for_resp() Versionadded:2.0.0

class ts3.query.TS3ServerConnection(uri=None, tp_args=None)

Bases: ts3.query.TS3BaseConnection

Use this class to connect to a TS3 Server:

with TS3ServerConnection("localhost") as tsconn:
    ts3conn.exec_("login", client_login_name="serveradmin", client_login_password="MyStupidPassword")
    ts3conn.exec_("use")
    ts3conn.exec_("clientkick", clid=1)

    resp = ts3conn.query("serverlist").all()

GREETING_LENGTH = 2

The typical TS3 Server greeting:

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

COMMAND_SET = frozenset({'serversnapshotcreate', 'permreset', 'ftrenamefile', 'logview', 'version', 'servergrouplist', 'privilegekeyadd', 'servergroupdelclient', 'servergroupautoaddperm', 'servergroupdelperm', 'serverstop', 'channelgroupdel', 'ftgetfilelist', 'serverstart', 'bandelall', 'servertemppassworddel', 'clientdbinfo', 'permoverview', 'logadd', 'channeledit', 'channelgroupadd', 'customsearch', 'clientgetnamefromuid', 'privilegekeylist', 'ftcreatedir', 'channelgroupdelperm', 'servergrouppermlist', 'bindinglist', 'serversnapshotdeploy', 'bandel', 'ftgetfileinfo', 'setclientchannelgroup', 'clientsetserverquerylogin', 'clientinfo', 'banadd', 'channellist', 'channelgroupclientlist', 'banclient', 'logout', 'messagelist', 'clientdblist', 'serverdelete', 'servergroupaddperm', 'serverrequestconnectioninfo', 'channelgroupaddperm', 'servertemppasswordadd', 'permissionlist', 'clientupdate', 'clientaddperm', 'hostinfo', 'channelclientpermlist', 'login', 'channelgrouprename', 'messageadd', 'clientkick', 'channelfind', 'clientpoke', 'serveridgetbyport', 'complaindelall', 'channeldelperm', 'instanceedit', 'help', 'clientfind', 'clientdbedit', 'channelclientaddperm', 'clientgetnamefromdbid', 'gm', 'channelgrouppermlist', 'messageupdateflag', 'messageget', 'servergroupadd', 'messagedel', 'banlist', 'ftstop', 'ftinitdownload', 'permget', 'whoami', 'sendtextmessage', 'serverprocessstop', 'use', 'ftdeletefile', 'clientgetids', 'complainadd', 'clientlist', 'servergroupautodelperm', 'channelinfo', 'clientmove', 'privilegekeyuse', 'permidgetbyname', 'clientedit', 'servergroupdel', 'servergrouprename', 'servernotifyregister', 'channeldelete', 'clientdelperm', 'ftlist', 'channelmove', 'serverinfo', 'channelgrouplist', 'servertemppasswordlist', 'clientgetdbidfromuid', 'privilegekeydelete', 'channelgroupcopy', 'servergroupcopy', 'ftinitupload', 'serverlist', 'complainlist', 'servernotifyunregister', 'clientdbfind', 'channeladdperm', 'servergroupsbyclientid', 'instanceinfo', 'channelcreate', 'servergroupaddclient', 'custominfo', 'complaindel', 'clientpermlist', 'clientdbdelete', 'channelclientdelperm', 'servercreate', 'serveredit', 'permfind', 'servergroupclientlist', 'channelpermlist'})

All server query commands as returned by the help command, excluding quit. Use close() instead.

open(host, port, timeout=None, protocol='telnet', tp_args=None)

Connect to the TS3 query service.

# Connect using telnet.
ts3conn.open("localhost", 10011)

# Connect using ssh.
ts3conn.open("localhost", 10022, protocol="ssh", tp_args={
    "username": "serveradmin", "password": "123456"
})

Parameters:

• host (str) – The hostname
• port (int) – The listening port of the service.
• timeout (int) – If not None, an exception is raised if the connection cannot be established within timeout seconds.
• protocol (str) – The protocol to be used. The TS3 server supports ssh and telnet, while the client only supports telnet.
• tp_args (dict) – A dictionary with parameters that are passed to the connect() method of the used transport. The SSH protocol for example requires a username and password.

Raises:

• TS3TransportError – If the client is already connected or the connection cannot be established.
• TS3TimeoutError – If the connection cannot be established within the specified timeout.

Seealso:

open_uri()

class ts3.query.TS3ClientConnection(uri=None, tp_args=None)

Bases: ts3.query.TS3BaseConnection

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

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

GREETING_LENGTH = 4

The typical TS3 Server greeting:

b’TS3 Clientnr’ b’Welcome to the TeamSpeak 3 ClientQuery interface […].nr’ b’Use the “auth” command to authenticate yourself. […].nr’ b’selected schandlerid=1nr’

COMMAND_SET = frozenset({'ftrenamefile', 'servergrouplist', 'servergroupdelclient', 'hashpassword', 'servergroupdelperm', 'tokendelete', 'channelgroupdel', 'ftgetfilelist', 'bandelall', 'permoverview', 'channelclientlist', 'channeledit', 'tokenadd', 'currentschandlerid', 'channelgroupadd', 'clientgetnamefromuid', 'serverconnectionhandlerlist', 'ftcreatedir', 'channelgroupdelperm', 'servergrouppermlist', 'serverconnectinfo', 'bandel', 'ftgetfileinfo', 'setclientchannelgroup', 'banadd', 'banclient', 'channelgroupclientlist', 'channellist', 'messagelist', 'clientgetuidfromclid', 'clientdblist', 'servergroupaddperm', 'channelgroupaddperm', 'clientvariable', 'verifyserverpassword', 'clientnotifyregister', 'clientupdate', 'clientaddperm', 'channelclientpermlist', 'auth', 'channelvariable', 'clientunmute', 'servervariable', 'messageadd', 'clientkick', 'clientpoke', 'complaindelall', 'channeldelperm', 'help', 'clientdbedit', 'channelclientaddperm', 'clientgetnamefromdbid', 'channelgrouppermlist', 'messageupdateflag', 'messageget', 'servergroupadd', 'messagedel', 'banlist', 'ftstop', 'ftinitdownload', 'whoami', 'sendtextmessage', 'clientmute', 'use', 'ftdeletefile', 'clientgetids', 'complainadd', 'clientlist', 'clientmove', 'servergroupdel', 'tokenlist', 'quit', 'channeldelete', 'clientdelperm', 'ftlist', 'channelmove', 'channelgrouplist', 'clientgetdbidfromuid', 'verifychannelpassword', 'ftinitupload', 'complainlist', 'channeladdperm', 'servergroupsbyclientid', 'channelcreate', 'servergroupaddclient', 'tokenuse', 'complaindel', 'clientpermlist', 'channelclientdelperm', 'clientdbdelete', 'clientnotifyunregister', 'channelconnectinfo', 'channelpermlist', 'servergroupclientlist'})

All client query commands as returned by the help command, excluding quit. Use close() instead.