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.

Types and IDE hints

from ts3_web_query import Client, TeamSpeakError
from ts3_web_query.constants import TargetMode
from ts3_web_query.properties import ChannelCreateProperties
from ts3_web_query.types import ServerInfo

props: ChannelCreateProperties = {"channel_name": "Lobby", "channel_flag_permanent": 1}
cid = await client.channel.channel_create(props)   # int | TeamSpeakError

info = await client.server.server_info()
if not isinstance(info, TeamSpeakError):           # narrows the type: fields are suggested
    print(info.virtualserver_name)

Create/edit properties are TypedDicts, so editors and mypy check the keys. The package ships py.typed.

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.

Limitations

• server_create is limited by the server license (a second virtual server gives error 2816 without one).
• client_set_serverquery_login does not work over WebQuery: a connection authorized by an API key has no client ID (error 512).
• Commands of the whole instance (serverlist, servercreate, serverdelete, serverstart, serverstop, hostinfo, version, ...) are sent without a virtual server ID in the path; every other command uses instance_id.

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