ts3 2.0.0b2

TS3 Query Commands

(Excerpt from the manual)

Query commands are made up of a command word, options and parameters (key-value pairs):

command key1=value1 key2=value2 key3=value3 -option1 -option1

This syntax translates into py-ts3 as follows:

ts3conn.exec_("command", "option1", "option2", key1=value1, key2=value2)
ts3conn.query("command", "option1", "option2", key1=value1, key2=value2).fetch()

The exec() method executes the command immediately and is often sufficient, while the query() method offers a slightly more sophisticated interface and supports pipelining:

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

# channellist -flags -icon
resp = ts3conn.query("channellist", "flags", "icon").fetch()
resp = ts3conn.query("channellist").options("flags", "icon").all()
resp = ts3conn.query("channellist").options("flags", "icon").first()

As a general rule of thumb, use exec_() if you don’t need pipelining.

Examples

You can find more examples in the ts3.examples package.

• Show all clients on the virtual server with the server id 1:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
          ts3conn.exec_("use", sid=1)
  
          # exec_() returns a **TS3QueryResponse** instance with the response.
          resp = ts3conn.exec_("clientlist")
          print("Clients on the server:", resp.parsed)
          print("Error:", resp.error["id"], resp.error["msg"])
  
          # Note, the TS3Response class and therefore the TS3QueryResponse
          # class too, can work as a rudimentary container. So, these two
          # commands are equal:
          for client in resp.parsed:
                  print(client)
          for client in resp:
                  print(client)

• Say hello to all clients:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
          ts3conn.exec_("use", sid=1)
  
          for client in ts3conn.exec_("clientlist"):
                  msg = "Hi {}".format(client["client_nickname"])
                  ts3conn.exec_("clientpoke", clid=client["clid"], msg=msg)

• Event handling (Server Query):

  #!/usr/bin/python3
  
  import time
  import ts3
  
  with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
          ts3conn.exec_("use", sid=1)
  
          # Register for events
          ts3conn.exec_("servernotifyregister", event="server")
  
          while True:
                  ts3conn.send_keepalive()
  
                  try:
                          event = ts3conn.wait_for_event(timeout=60)
                  except ts3.query.TS3TimeoutError:
                          pass
                  else:
                          # Greet new clients.
                          if event[0]["reasonid"] == "0":
                                  print("client connected")
                                  ts3conn.exec_("clientpoke", clid=event[0]["clid"], msg="Hello :)")

• A simple TS3 viewer:

  #!/usr/bin/python3
  
  import ts3
  
  # The examples package already contains this implementation.
  # Note, that the examples.viewer module has an helpful class to
  # build a complete channel tree of a virtual server: ChannelTreeNode
  #
  # You may have to download it from GitHub first.
  from ts3_examples.viewer import view
  
  with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
          view(ts3conn, sid=1)

• Download and upload files:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
          ts3conn.exec_("use", sid=1)
  
          # Create a new TS3FileTransfer instance associated with the
          # TS3ServerConnection.
          ts3ft = ts3.filetransfer.TS3FileTransfer(ts3conn)
  
          # Upload the image *baz.png* to the channel with the id 2 on the
          # TS3 server.
          # Note the opening mode ("rb").
          with open("baz.png", "rb") as file:
                  ts3ft.init_upload(input_file=file, name="/baz.png", cid=2)
  
          # Download the file into *baz1.png*.
          with open("baz1.png", "wb") as file:
                  ts3ft.init_download(output_file=file, name="/baz.png", cid=2)

• Event handling (Client Query):

  #!/usr/bin/python3
  
  import time
  import ts3
  
  with ts3.query.TS3ServerConnection("telnet://localhost:25639") as ts3conn:
          ts3conn.exec_("auth", apikey="AAAA-....-EEEE")
  
          # Register for events
          ts3conn.exec_("clientnotifyregister", event="any", schandlerid=0)
  
          while True:
                  event = ts3conn.wait_for_event()
                  print(event.parsed)