ts3-web-query

Русская версия

Async Python wrapper for the TeamSpeak 3 HTTP WebQuery API (not the raw telnet/SSH ServerQuery). Built on aiohttp; commands return typed dataclasses.

Status: alpha. All ServerQuery commands accepted by WebQuery are covered (109 of the 130 documented ones); see Not supported.

Requirements

• Python 3.10+
• aiohttp >= 3.9
• A TeamSpeak 3 server with WebQuery enabled and an API key (apikeyadd)

Installation

pip install ts3-web-query

Quick start

import asyncio
from ts3_web_query import Client


async def main():
    async with Client(
        api_url="http://127.0.0.1:10080",  # WebQuery address
        api_key="BABAB...",                 # x-api-key
        instance_id=1,                      # virtual server (sid)
        timeout=30.0,                       # total request timeout, seconds
    ) as client:
        print(await client.server.server_info())
        print(await client.channel.channel_list())


asyncio.run(main())

Without async with, close the HTTP session yourself: await client.close(). A complete example is in examples/basic_usage.py.

Error handling

• Network failures and unexpected responses raise ts3_web_query.TeamSpeakConnectionError.
• TeamSpeak errors are not raised: the method returns TeamSpeakError(code, message, extra_message). Commands without a payload return TeamSpeakError(code=0, message='ok') on success.

result = await client.channel.channel_delete(cid=5, force=True)
if result.code != 0:
    print("failed:", result.message)

An empty result is reported by the server as error 1281 (database empty result set), so e.g. ban_list() with no bans returns TeamSpeakError(code=1281, ...), not an empty list.

Implemented API

Methods with repeated parameters (several clids, permission sets, ...) take lists. They are sent as POST with a JSON body, because WebQuery silently honors only the first value of a repeated query-string key.

Some operations are destructive: perm_reset resets the virtual server's permissions, server_snapshot_deploy recreates channels and groups (their IDs change), ban_del_all removes every ban.

Not supported

• File transfer (ft*, 9 commands): WebQuery answers 5120 out of scope for any API key.
• servernotifyregister / servernotifyunregister: unavailable in WebQuery.
• Raw-session commands login, logout, use, quit, help, bindinglist: authentication uses the x-api-key header and the server is chosen with instance_id.
• Aliases tokenadd/tokendelete/tokenlist/tokenuse: use privilege_key_*.

License

MIT