Skip to main content

TS3 Server&Client Query API

Project description

Forked from https://github.com/benediktschmitt/py-ts3, which only supports ServerQuery. However, benediktschmitts version is more likely to be up-to-date, since this was only forked for one specific project and only implements a small subset of ClientQuery methods.

This package provides a Python 3 API for:

  • TS3 query connections

  • TS3 query events

  • TS3 file transfers

You can find a complete API documentation here.

Installation

This package is registered on PyPi, so you’re done with:

$ pip3 install ts3

TS3 Server configuration

If you want to send lots of queries to the TS3 server, make sure, that you’re connection is not closed by the anti-flood protection of the TS3 server. So it may be wise to add the host that runs the TS3 queries to the query_ip_whitelist.txt of your TS3 server:

$ echo "192.168.178.42" >> path/to/ts3/server/directory/query_ip_whitelist.txt

Introduction

The easiest way to get to grips with this library is taking a look at the examples.

If you need information about the possible query commands, take a look at the TS3 Server Query Manual.

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("localhost") as ts3conn:
            # Note, that the client will wait for the response and raise a
            # **TS3QueryError** if the error id of the response is not 0.
            try:
                    ts3conn.login(
                            client_login_name="serveradmin",
                            client_login_password="FoOBa9"
                    )
            except ts3.query.TS3QueryError as err:
                    print("Login failed:", err.resp.error["msg"])
                    exit(1)
    
            ts3conn.use(sid=1)
    
            # Each query method will return a **TS3QueryResponse** instance,
            # with the response.
            resp = ts3conn.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("localhost") as ts3conn:
            ts3conn.login(
                    client_login_name="serveradmin",
                    client_login_password="FoOBa9"
            )
            ts3conn.use(sid=1)
    
            for client in ts3conn.clientlist():
                    msg = "Hi {}".format(client["client_nickname"])
                    ts3conn.clientpoke(clid=client["clid"], msg=msg)
  • Say hello to all clients but use it with the ClientQuery plugin instead of a ServerQuery connection:

    #!/usr/bin/python3
    
    import ts3
    
    with ts3.query.TS3Connection("localhost", 25639) as ts3conn:
            ts3conn.auth(apikey="AAAA-BBBB-CCCC-DDDD-EEEEh")
    
            for client in ts3conn.clientlist():
                    msg = "Hi {}".format(client["client_nickname"])
                    ts3conn.clientpoke(clid=client["clid"], msg=msg)
  • Event handling (Server Query):

    #!/usr/bin/python3
    
    import time
    import ts3
    
    with ts3.query.TS3ServerConnection("localhost") as ts3conn:
            ts3conn.login(
                    client_login_name="serveradmin",
                    client_login_password="FoOBa9"
            )
            ts3conn.use(sid=1)
    
            # Register for events
            ts3conn.servernotifyregister(event="server")
    
            while True:
                    event = ts3conn.wait_for_event()
    
                    # Greet new clients.
                    if event[0]["reasonid"] == "0":
                            print("client connected")
                            ts3conn.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 ts3.examples.viewer module has an helpful class to
    # build a complete channel tree of a virtual server: ChannelTreeNode
    from ts3.examples.viewer import view
    
    with ts3.query.TS3ServerConnection("localhost") as ts3conn:
            ts3conn.login(
                    client_login_name="serveradmin",
                    client_login_password="FoOBa9"
            )
            view(ts3conn, sid=1)
  • Download and upload files:

    #!/usr/bin/python3
    
    import ts3
    
    with ts3.query.TS3ServerConnection("localhost") as ts3conn:
            ts3conn.login(
                    client_login_name="serveradmin",
                    client_login_password="FoOBa9"
            )
    
            # 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.TS3ClientConnection("localhost") as ts3conn:
            ts3conn.auth(apikey="AAAA-....-EEEE")
            ts3conn.use()
    
            # Register for events
            ts3conn.clientnotifyregister(event="any")
    
            while True:
                    event = ts3conn.wait_for_event()
                    print(event.parsed)

Bugs

If you found a bug please report it or sent a pull request.

Please report grammar or spelling errors too.

Versioning

For the version numbers, take a look at http://semver.org/.

License

This package is licensed under the MIT License.

The docstrings copied from the TS3 Server Query Manual are the property of the TeamSpeak Systems GmbH.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ts3query-2.0.1.tar.gz (50.9 kB view hashes)

Uploaded Source

Built Distribution

ts3query-2.0.1-py3-none-any.whl (66.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page