ts3.query_builder

This module contains a flexible query builder which is modeled after the COMMAND SYNTAX section in the TS3 Server Query Manual.

versionadded:2.0.0

class ts3.query_builder.TS3QueryBuilder(cmd, ts3conn=None, pipes=None)

Bases: object

Simplifies building a valid TS3 query.

# When you are interested in the whole response.
resp = TS3QueryBuilder(ts3conn, "clientkick").pipe(pattern="Ben").fetch()

# When you are only interested in the first item in the response.
resp = TS3QueryBuilder(ts3conn, "serverlist").first()

# When you are only interested in the items, but not in the actual
# response object.
resp = TS3QueryBuilder(ts3conn, "serverlist").all()

Please note, that query builder objects are not immutable.

Parameters:

• cmd (str) – The name of the command to execute, e.g. "clientkick".
• ts3conn (TS3BaseConnection) – The TS3 connection which will be used to send the query.
• pipes (list) – A list of (options, params) in which options is a set and params is a dictionary.

Seealso:

ts3.query.TS3BaseConnection.query(), ts3.query.TS3BaseConnection.exec_query()

Todo:

What about the crazy properties in the documentation, what are they?

pipe(*options, **params)

Starts a new pipe:

>>> q = TS3QueryBuilder("clientkick").pipe(clid=1).pipe(clid=2)
>>> print(q)
'clientkick clid=1 | clid=2'

options(*options)

Adds the options to the last pipe:

>>> q = TS3QueryBuilder("clientkick").options("foo").pipe().options("bar")
>>> print(q)
'clientkick -foo | -bar'

You should prefer passing the options directly to pipe() as it is more readable.

Note

Most commands do not support pipelining options.

params(**params)

Adds the parameters to the last pipe:

>>> q = TS3QueryBuilder("clientkick")\
...     .pipe().params(clid=1)\
...     .pipe().params(clid=2)
>>> print(q)
'clientkick clid=1 | clid=2'

You should prefer passing the options directly to pipe() as it is more readable.

compile()

Compiles the query into a TS3 query command and returns it:

# Strings are escaped automatic.
>>> q = TS3QueryBuilder("clientkick").params(reasonid=5, reasonmsg="Go away!")\
...     .pipe(clid=1).pipe(clid=2)
>>> q.compile()
'clientkick reasonid=5 reasonmsg=Go\saway! | clid=1 | clid=2'

# Booleans are turned into 0 or 1.
>>> q = TS3QueryBuilder("clientupdate").params(client_input_muted=True)
>>> q.compile()
'clientupdate client_input_muted=1'

Return type:str Returns:A valid TS3 query command string with arguments and options.

fetch()

Executes the query and returns the TS3QueryResponse.

Seealso:TS3BaseConnection.exec_query()

first()

Executes the query and returns the first item in the parsed response. Use this method if you are only interested in the first item of the response.

If the response did not contain any items, then None is returned.

Seealso:ts3.query.TS3BaseConnection.exec_query(), ts3.query.TS3QueryResponse.parsed

all()

Executes the query and returns the parsed response. Use this method if you are interested in the parsed response rather than the resoonse object.

Seealso:ts3.query.TS3BaseConnection.exec_query(), ts3.query.TS3QueryResponse.parsed