API Reference¶

The following section outlines the API of teamtalk.py.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured,

Bot¶

A module that contains the TeamTalkBot class.

The TeamTalkBot class is the main class of the library. It’s used to create a bot,connect to any amount of TeamTalk servers and dispatch events.

class teamtalk.bot.TeamTalkBot¶

A class that represents a TeamTalk bot.

@event¶

A decorator that registers an event to listen to.

The events must be a coroutine, if not, TypeError is raised.

Example

@client.event
async def on_ready():
    print('Ready!')

See the event Reference for more information and a list of all events.

Parameters:: coro (CoroT) – The coroutine to register.
Returns:: The coroutine that was registered.
Return type:: CoroT
Raises:: TypeError – The coroutine is not a coroutine function.

__init__(client_name: str | None = 'Teamtalk.py') → None¶

Initialize a TeamTalkBot object.

Parameters:: client_name (Optional[str]) – The name of the client. Defaults to “Teamtalk.py”.

await add_server(server: TeamTalkServerInfo | dict) → None¶

Add a server to the bot.

Parameters:: server – A Union[TeamTalkServerInfo, dict] object representing the server to add. If a dictionary is provided, it will be converted to a TeamTalkServerInfo object.

run()¶: A blocking call that connects to all added servers and handles all events.

await on_error(event_method: str, /, *args: Any, **kwargs: Any) → None¶

This function is a coroutine. .

The default error handler provided by the client.

By default this logs to the library logger however it could be overridden to have a different implementation. The traceback from this exception is logged to the logging module.

Parameters:

event_method (str) – The event method that errored.
*args (Any) – The arguments to the event.
**kwargs (Any) – The keyword arguments to the event.

Enums¶

TeamTalk enums and constants.

class teamtalk.enums.TeamTalkServerInfo¶

Holds the required information to connect and login to a TeamTalk server.

__init__(host: str, tcp_port: int, udp_port: int, username: str, password: str = '', encrypted: bool = False, nickname: str = '', join_channel_id: int = -1, join_channel_password: str = '') → None¶

Initialize a TeamTalkServerInfo object.

Parameters:

host (str) – The host of the TeamTalk server.
tcp_port (int) – The TCP port of the TeamTalk server.
udp_port (int) – The UDP port of the TeamTalk server.
username (str) – The username to login with.
password (str) – The password to login with. Defaults to “” (no password).
encrypted (bool) – Whether or not to use encryption. Defaults to False.
nickname (str) – The nickname to use. Defaults to “teamtalk.py Bot”.
join_channel_id (int) – The channel ID to join. Defaults to -1 (don’t join a channel on login). Set to 0 to join the root channel, or a positive integer to join a specific channel. # noqa: E501
join_channel_password (str) – The password to join the channel with. Defaults to “” (no password).

classmethod from_dict(data: dict) → Self¶

Construct a TeamTalkServerInfo object from a dictionary.

Parameters:: data (dict) – The dictionary to construct the object from.
Returns:: The constructed object.
Return type:: Self

to_dict() → dict¶

Convert this object to a dictionary.

Returns:: The dictionary representation of this object.
Return type:: dict

class teamtalk.enums.UserStatusMode¶

The status mode of a user. This is used in the teamtalk.TeamTalkInstance.change_status call.

ONLINE = 0¶: The user is online.

AWAY = 1¶: The user is away.

QUESTION = 2¶: The user has a question

class teamtalk.enums.UserType¶

The type of a user account.

DEFAULT = 1¶: The default user type. This only has the permissions set, and no other permissions.

ADMIN = 2¶: The admin user type. This has all permissions.

Server¶

Provides the Server class for interacting with a TeamTalk5 server.

class teamtalk.server.Server¶

Represents a TeamTalk5 server.

teamtalk_instance¶: An instance of teamtalk.TeamTalkInstance.

info¶: The server information.

__init__(teamtalk_instance, server_info)¶

Initializes a Server instance.

Parameters:

teamtalk_instance – An instance of teamtalk.TeamTalkInstance.
server_info – The server information.

send_message(content: str, **kwargs)¶

Sends a message to all users on the server, using a broadcast message.

Parameters:

content – The content of the message.
**kwargs – Keyword arguments. See teamtalk.TeamTalkInstance.send_message for more information.

Returns:

The result of the doTextMessage call.

Raises:

PermissionError – If the user is not an admin.

ping() → bool¶

Pings the server.

Returns:: True if the ping is successful, False otherwise.

get_users() → list¶

Gets a list of users on the server.

Returns:: A list of teamtalk.User instances representing the users on the server.

get_channels() → list¶

Gets a list of channels on the server.

Returns:: A list of teamtalk.Channel instances representing the channels on the server.

get_channel(channel_id)¶

Gets the channel with the specified ID.

Parameters:: channel_id – The ID of the channel.
Returns:: The teamtalk.Channel instance representing the channel with the specified ID.

get_user(user_id)¶

Gets the user with the specified ID.

Parameters:: user_id – The ID of the user.
Returns:: The teamtalk.User instance representing the user with the specified ID.

join_channel(channel: Channel | str | int, password='')¶

Joins the specified channel.

Parameters:

channel – The channel to join.
password – The password for the channel, if required.

Returns:

True if the channel was joined successfully, False otherwise.

get_statistics(timeout: int = 2)¶

Gets the servers statistics.

Parameters:: timeout – The time to wait before assuming that getting the servers statistics failed.
Returns:: The teamtalk.Statistics instance representing the servers statistics.

move_user(user: User | int, channel: Channel | int)¶

Moves the specified user to the specified channel.

Parameters:

user – The user to move.
channel – The channel to move the user to.

Raises:

PermissionError – If the user is not an admin.

kick(user: User | int)¶

Kicks the specified user from the specified channel.

Parameters:: user – The user to kick.
Raises:: PermissionError – If the user is not an admin.

ban(user: User | int)¶

Bans the specified user from the specified channel.

Parameters:: user – The user to ban.
Raises:: PermissionError – If the user is not an admin.

unban(user: User | int)¶

Unbans the specified user from the specified channel.

Parameters:: user – The user to unban.
Raises:: PermissionError – If the user is not an admin.

subscribe(subscription)¶

Subscribes to the specified subscription for all users on the server.

Parameters:: subscription – The subscription to subscribe to.

unsubscribe(subscription)¶

Unsubscribes to the specified subscription for all users on the server.

Parameters:: subscription – The subscription to unsubscribe to.

get_properties() → ServerProperties¶

Gets the properties of the server.

Returns:: A teamtalk.ServerProperties instance representing the properties of the server.

update_properties(properties: ServerProperties)¶

Updates the properties of the server.

Parameters:: properties – The updated properties. See teamtalk.ServerProperties for more information.
Raises:: PermissionError – If the bot does not have the permission to update the properties.

class teamtalk.server.ServerProperties¶

Represents the properties of a server.

This class should not be instantiated directly. Instead, use the teamtalk.Server.get_properties() method. # noqa

Example

>>> server = teamtalk server
>>> properties = server.get_properties()
>>> properties.max_users
1000
>>> properties.max_users = 500
>>> server.update_properties(properties)
>>> properties = server.get_properties()
>>> properties.max_users
500

Channel¶

Channel module for teamtalk.py.

class teamtalk.channel.Channel¶

Represents a channel on a TeamTalk server.

__init__(teamtalk, channel: int | Channel) → None¶

Initialize a Channel object.

Parameters:

teamtalk – The teamtalk.TeamTalkInstance instance.
channel (Union[int, sdk.Channel]) – The channel ID or a sdk.Channel object.

update() → bool¶

Update the channel information.

Example

>>> channel = teamtalk.get_channel(1)
>>> channel.name = "New Channel Name"
>>> channel.update()

Raises:

PermissionError – If the bot does not have permission to update the channel.
ValueError – If the channel could not be updated.

Returns:

True if the channel was updated successfully.

Return type:

bool

send_message(content: str, **kwargs) → None¶

Send a message to the channel.

Parameters:

content – The message to send.
**kwargs – Keyword arguments. See teamtalk.TeamTalkInstance.send_message for more information.

Raises:

PermissionError – If the bot is not in the channel and is not an admin.

upload_file(filepath)¶

Upload a file to the channel.

Parameters:: filepath (str) – The local path to the file to upload.

get_users() → List[User]¶

Get a list of users in the channel.

Returns:: A list of teamtalk.User instances in the channel.
Return type:: List[TeamTalkUser]

get_files() → List[RemoteFile]¶

Get a list of files in the channel.

Returns:: A list of teamtalk.RemoteFile instances in the channel.
Return type:: List[RemoteFile]

move(user: User | int) → None¶

Move a user to this channel.

Parameters:: user – The user to move.

kick(user: User | int) → None¶

Kick a user from this channel.

Parameters:: user – The user to kick.

ban(user: User | int) → None¶

Ban a user from this channel.

Parameters:: user – The user to ban.

subscribe(subscription) → None¶

Subscribe to a subscription for all users in this channel.

Parameters:: subscription – The subscription to subscribe to.

unsubscribe(subscription) → None¶

Unsubscribe from a subscription for all users in this channel.

Parameters:: subscription – The subscription to unsubscribe from.

class teamtalk.channel.ChannelType¶: A class representing Channel types in TeamTalk.

UserAccount¶

This module defines a class for a User Account on a TeamTalk server.

The difference between this class and the User class is that this class represents a user account, while the User class represents a user that is currently connected to the server.

class teamtalk.user_account.UserAccount¶

A class for a user account on a TeamTalk server. This class is not meant to be instantiated directly. Instead, use the TeamTalkBot.list_user_accounts() method to get a list of UserAccount objects. # noqa

__init__(teamtalk_instance, account: UserAccount) → None¶

Initialize a UserAccount object.

Parameters:

teamtalk_instance – The TeamTalk instance.
account – The user account.

class teamtalk.user_account.BannedUserAccount¶: Represents a banned user account on a TeamTalk server. This class is not meant to be instantiated directly. Instead, use the TeamTalkBot.list_banned_users() method to get a list of BannedUserAccount objects. # noqa

User¶

This module defines a User class that represents a user on a TeamTalk server.

class teamtalk.user.User¶

Represents a user on a TeamTalk server.

teamtalk_instance¶: An instance of TeamTalk.TeamTalkInstance.

user¶: Either a string (username) or an int (user_id) or an instance of sdk.User.

__init__(teamtalk_instance, user: str | int | User)¶

Initializes the User instance.

Parameters:

teamtalk_instance – An instance of TeamTalk5.
user – Either a string (username) or an int (user_id) or an instance of sdk.User.

Raises:

TypeError – If the user argument is not of the expected type.

is_me() → bool¶

Checks if this user is the bot itself.

Returns:: True if this user is the bot itself, False otherwise.

send_message(content: str, **kwargs) → int¶

Sends a text message to this user.

Parameters:

content – The content of the message.
**kwargs – Keyword arguments. See teamtalk.TeamTalkInstance.send_message for more information.

Returns:

The ID of the message if successful, or a negative value if unsuccessful.

move(channel) → bool¶

Moves this user to the specified channel.

Parameters:: channel – The channel to move this user to.
Returns:: True if the user was moved successfully, False otherwise.

kick(from_server: bool) → None¶

Kicks this user from the server.

Parameters:: from_server – If True, the user will be kicked from the server. If False, the user will be kicked from the channel. # noqa

ban(from_server: bool) → None¶

Bans this user from the server.

Parameters:: from_server – If True, the user will be banned from the server. If False, the user will be banned from the channel. # noqa

subscribe(subscription) → None¶

Subscribes to the specified subscription.

Parameters:: subscription – The subscription to subscribe to.

unsubscribe(subscription) → None¶

Unsubscribes from the specified subscription.

Parameters:: subscription – The subscription to unsubscribe from.

is_subscribed(subscription) → bool¶

Checks if this user is subscribed to the specified subscription.

Parameters:: subscription – The subscription to check.
Returns:: True if the bot is subscribed to the specified subscription from this user, False otherwise.

Message¶

This module contains the Message class and its subclasses.

class teamtalk.message.Message¶

Represents a TeamTalk5 message. This class should not be instantiated directly.

__init__(teamtalk_instance, msg)¶

Initializes a Message instance.

Parameters:

teamtalk_instance – An instance of teamtalk.TeamTalkInstance.
msg – The message.

reply(content, **kwargs)¶

Replies to the message.

The reply will be sent to the place where the message was sent from. Meaning that if the message was sent to a channel, the reply will be sent to the channel. If the message was sent to a user, the reply will be sent to the user. And if the message was a broadcast message, the reply will be sent to the server as a broadcast.

Parameters:

content – The content of the message.
**kwargs – Keyword arguments. See teamtalk.TeamTalkInstance.send_message for more information.

Returns:

The message ID of the reply.

Raises:

PermissionError – If the sender doesn’t have permission to send the message.

is_me() → bool¶

Checks if the message was sent by the bot.

Returns:: True if the message was sent by the bot, False otherwise.

class teamtalk.message.ChannelMessage¶

Represents a message sent to a channel. This class should not be instantiated directly.

__init__(teamtalk_instance, msg)¶

Initializes a ChannelMessage instance.

Parameters:

teamtalk_instance – An instance of teamtalk.TeamTalkInstance.
msg – The message payload.

class teamtalk.message.DirectMessage¶

Represents a message sent to a user. This class should not be instantiated directly.

__init__(teamtalk_instance, msg)¶

Initializes a DirectMessage instance.

Parameters:

teamtalk_instance – An instance of teamtalk.TeamTalkInstance.
msg – The message payload.

class teamtalk.message.BroadcastMessage¶

Represents a message sent to a server. This class should not be instantiated directly.

__init__(teamtalk_instance, msg)¶

Initializes a BroadcastMessage instance.

Parameters:

teamtalk_instance – An instance of teamtalk.TeamTalkInstance.
msg – The message payload.

class teamtalk.message.CustomMessage¶

Represents a custom message. This class should not be instantiated directly.

__init__(teamtalk_instance, msg)¶

Initializes a CustomMessage instance.

Parameters:

teamtalk_instance – An instance of teamtalk.TeamTalkInstance.
msg – The message payload.

Audio Streaming¶

A module containing the Streamer class.

This module contains the Streamer class, which is used to stream audio data to a TeamTalk channel.

Warning

To use other files than .wav files, you need to have ffmpeg installed on your system.

Warning

To stream urls, you need to have yt-dlp installed on your system.

Example

>>> import teamtalk
>>> # asuming we have a bot in the variable bot
>>> @bot.event
>>> async def on_message(message):
>>>     if message.content.lower() == "play":
>>>         streamer = teamtalk.Streamer.get_streamer_for_channel(message.channel)
>>>         streamer.stream("path/to/file.wav")
>>> # or for an url
>>> streamer.stream("https://www.example.com/youtube/or/other/stream")

It’s also possible to stream audio from an arbitrary data stream, such as a microphone. To do this, you need to set the correct sample rate and number of channels on initialization, and then feed the data to the streamer as it becomes available. The data needs to be in 16 bit PCM format (pcm_s16le).

Example

>>> import teamtalk
>>> # asuming we have a bot in the variable bot
>>> @bot.event
>>> async def on_message(message):
>>>     if message.content.lower() == "play":
>>>         streamer = teamtalk.Streamer.get_streamer_for_channel(message.channel, sample_rate=48000, channels=2)
>>>         # we could get the data from any source, so let's assume it's coming from a live microphone.
>>>         data_stream = # connect to microphone
>>>         while True:
>>>             # get the data from the stream
>>>             data = data_stream.read(streamer.block_size*16) # we are reading 16 chunks at a time to combat buffering
>>>             if data == 0:
>>>                 break
>>>             # add the data to the streamer
>>>             streamer.feed(data)
>>>         # close the connection to our microphone

class teamtalk.streamer.Streamer¶

A class representing a streamer for audio data to a TeamTalk channel.

staticmethod get_streamer_for_channel(channel: Channel, sample_rate: int = 48000, channels: int = 2, block_size: int = 4096)¶

Gets a streamer for a channel.

Parameters:

channel (TeamTalkChannel) – The TeamTalk channel to get the streamer for.
sample_rate (int, optional) – The sample rate of the audio data. Defaults to 48000.
channels (int, optional) – The number of channels in the audio data. Defaults to 2.
block_size (int, optional) – The block size of the audio data. Defaults to 4 * 1024 (4kb)

Returns:

The streamer for the channel.

Return type:

Streamer

__init__(channel: Channel, sample_rate: int = 48000, channels: int = 2, block_size: int = 4096)¶

Initializes a new instance of the TeamTalkStreamer class.

Parameters:

channel (TeamTalkChannel) – The TeamTalk channel to which the streamer streams the audio data.
sample_rate (int, optional) – The sample rate of the audio data. Defaults to 48000.
channels (int, optional) – The number of channels in the audio data. Defaults to 2.
block_size (int, optional) – The block size of the audio data. Defaults to 4 * 1024 (4kb)

search_and_stream(query: str) → None¶

Searches for a song and streams it to the channel.

Parameters:: query (str) – The query to search for.
Returns:: None

stop() → None¶: Stops the current stream.

stream(path: str) → int¶

Streams a file or an url to the channel.

Parameters:: path (str) – The file or url to stream.
Raises:: RuntimeError – If the url could not be opened as a wav file or if the file could not be converted to a wav file.

property volume: int¶

The volume of the streamer.

Returns:: The volume of the streamer.
Return type:: int

property mute_left: bool¶

If the left channel of the speaker is muted.

Returns:: True if the left channel is muted, False otherwise.
Return type:: bool

property mute_right: bool¶

If the right channel of the speaker is muted.

Returns:: True if the right channel is muted, False otherwise.
Return type:: bool

feed(data: bytes) → int¶

Feeds data to the streamer.

Parameters:: data (bytes) – The data to feed to the streamer.
Returns:: The stream id of the stream.
Return type:: int

Files¶

Teamtalk file object.

class teamtalk.tt_file.RemoteFile¶

Represents a file on a TeamTalk server. Should not be instantiated directly.

__init__(teamtalk_instance, payload)¶

Initializes the RemoteFile instance.

Parameters:

teamtalk_instance – The teamtalk.TeamTalkInstance instance.
payload – An instance of sdk.RemoteFile.

Permission¶

A module for managing user permissions and some shorthands for checking permissions.

class teamtalk.permission.Permission¶: A class representing user permissions in TeamTalk.

Subscriptions¶

Subscription class for TeamTalk.

class teamtalk.subscription.Subscription¶: A class representing subscriptions in TeamTalk.

Exceptions¶

teamtalk.py exceptions.

exception teamtalk.exceptions.TeamTalkException¶

Base exception class for teamtalk.py.

All other exceptions inherit from this class, which inherits from Exception.

__init__(message: str) → None¶

Initialise the exception.

Parameters:: message (str) – The message to be displayed when the exception is raised.

exception teamtalk.exceptions.PermissionError¶: Exception raised when the bot does not have permission to perform an action.

TeamTalkInstance (low level)¶

This module contains the TeamTalkInstance class.

The TeamTalkInstance class contains one instance of a connection to a TeamTalkServer. It is used to send and receive messages, join and leave channels, and perform other actions. In addition, it’s also here that events are dispatched.

class teamtalk.instance.TeamTalkInstance¶

Represents a TeamTalk5 instance.

__init__(bot, server_info: TeamTalkServerInfo) → None¶

Initializes a teamtalk.TeamTalkInstance instance.

Parameters:

bot – The teamtalk.Bot instance.
server_info – The server info for the server we wish to connect to.

connect() → bool¶

Connects to the server. This doesn’t return until the connection is successful or fails.

Returns:: True if the connection was successful, False otherwise.
Return type:: bool

login(join_channel_on_login: bool = True) → bool¶

Logs in to the server. This doesn’t return until the login is successful or fails.

Parameters:: join_channel_on_login – Whether to join the channel on login or not.
Returns:: True if the login was successful, False otherwise.
Return type:: bool

logout()¶: Logs out of the server.

disconnect()¶: Disconnects from the server.

change_nickname(nickname: str)¶

Changes the nickname of the bot.

Parameters:: nickname – The new nickname.

change_status(status_mode: UserStatusMode, status_message: str)¶

Changes the status of the bot.

Parameters:

status_mode – The status mode.
status_message – The status message.

get_sound_devices() → List[SoundDevice]¶

Gets the list of available TeamTalk sound devices, marking the default input.

Returns:: A list of SoundDevice objects representing the available devices. Returns an empty list if the SDK call fails.

get_current_input_device_id() → int | None¶

Gets the ID of the currently active input device for this instance.

Note

This returns the ID that was stored when the input device was last initialized or set for this instance using set_input_device. It does not query the SDK directly for the current device.

Returns:: The ID of the current input device, or -1 if not set or unknown.

set_input_device(device_id_or_name: int | str) → bool¶

Sets and initializes the input device for this instance.

Accepts a specific device ID (int) or the string “default” to use the system default input device. Updates the stored current input device ID on success.

Parameters:: device_id_or_name – The ID (int) of the device or the string “default”.
Returns:: True on success, False on initialization failure or if default not found.
Raises:: ValueError – If the input is not a valid integer or “default”.

enable_voice_transmission(enabled: bool) → bool¶

Enables or disables voice transmission state for this instance.

Parameters:: enabled – True to enable voice transmission, False to disable it.
Returns:: True if the SDK call was successful, False otherwise.

get_input_volume() → int¶

Gets the current input gain level (100=SDK default).

Retrieves the raw SDK gain and scales it so the SDK default gain level (SOUND_GAIN_DEFAULT) corresponds to 100.

Returns:

The volume level where 100 is the SDK default gain. Values: above 100 represent gain higher than the SDK default. Returns 0 if the SDK call fails.

Return type:

int

set_input_volume(volume: int) → bool¶

Sets the input gain level (100=SDK default).

Scales the input volume (where 100 is the SDK default gain) to the SDK’s raw gain range [0, 32000] and applies it, clamping the value.

Parameters:: volume (int) – The desired volume level, where 100 corresponds to the SDK default gain.
Returns:: True on success, False otherwise.
Return type:: bool
Raises:: ValueError – If volume is negative.

has_permission(permission: Permission) → bool¶

Checks if the bot has a permission.

If the user is an admin, they have all permissions.

Parameters:: permission – The permission to check for.
Returns:: True if the bot has the permission, False otherwise.
Return type:: bool

is_admin() → bool¶

Checks if the bot is an admin.

Returns:: True if the bot is an admin, False otherwise.
Return type:: bool

is_user_admin(user: User | int) → bool¶

Checks if a user is an admin.

Parameters:: user – The user to check.
Returns:: True if the user is an admin, False otherwise.
Return type:: bool
Raises:: TypeError – If the user is not of type teamtalk.User or int.

subscribe(user: User, subscription: Subscription)¶

Subscribes to a subscription.

Parameters:

user – The user to subscribe to.
subscription – The subscription to subscribe to.

unsubscribe(user: User, subscription: Subscription)¶

Unsubscribes from a subscription.

Parameters:

user – The user to unsubscribe from.
subscription – The subscription to unsubscribe from.

is_subscribed(subscription: Subscription) → bool¶

Checks if the bot is subscribed to a subscription.

Parameters:: subscription – The subscription to check.
Returns:: True if the bot is subscribed to the subscription, False otherwise.
Return type:: bool

join_root_channel()¶: Joins the root channel.

join_channel_by_id(id: int, password: str = '')¶

Joins a channel by its ID.

Parameters:

id – The ID of the channel to join.
password – The password of the channel to join.

join_channel(channel: Channel)¶

Joins a channel.

Parameters:: channel – The channel to join.

leave_channel()¶: Leaves the current channel.

get_channel(channel_id: int) → Channel¶

Gets a channel by its ID.

Parameters:: channel_id – The ID of the channel to get.
Returns:: The channel.
Return type:: TeamTalkChannel

get_path_from_channel(channel: Channel | int) → str¶

Gets the path of a channel.

Parameters:

channel – The channel to get the path of.

Returns:

The path of the channel.

Return type:

str

Raises:

TypeError – If the channel is not of type teamtalk.Channel or int.
ValueError – If the channel is not found.

get_channel_from_path(path: str) → Channel¶

Gets a channel by its path.

Parameters:: path – The path of the channel to get.
Returns:: The channel.
Return type:: TeamTalkChannel
Raises:: ValueError – If the channel is not found.

create_channel(name: str, parent_channel: Channel | int, topic: str = '', password: str = '', channel_type: ChannelType = None) → bool¶

Creates a channel.

Parameters:

name – The name of the channel to create.
parent_channel – The parent channel of the channel.
topic – The topic of the channel.
password – The password of the channel. Leave empty for no password.
channel_type – The type of the channel. Defaults to CHANNEL_DEFAULT.

Raises:

PermissionError – If the bot does not have permission to create channels.
ValueError – If the channel could not be created.

Returns:

True if the channel was created, False otherwise.

Return type:

bool

delete_channel(channel: Channel | int)¶

Deletes a channel.

Parameters:

channel – The channel to delete.

Raises:

TypeError – If the channel is not of type teamtalk.Channel or int.
PermissionError – If the bot doesn’t have the permission to delete the channel.
ValueError – If the channel is not found.

Returns:

True if the channel was deleted.

Return type:

bool

make_channel_operator(user: User | int, channel: User | int, operator_password: str = '') → bool¶

Makes a user the channel operator.

Parameters:

user – The user to make the channel operator.
channel – The channel to make the user the channel operator in.
operator_password – The operator password of the channel.

Raises:

TypeError – If the user or channel is not of type teamtalk.User or int.
PermissionError – If the bot doesn’t have the permission to make a user the channel operator.
ValueError – If the user or channel is not found.

Returns:

True if the user was made the channel operator, False otherwise.

Return type:

bool

remove_channel_operator(user: User | int, channel: User | int, operator_password: str = '') → bool¶

Removes a user as the channel operator.

Parameters:

user – The user to make the channel operator.
channel – The channel to make the user the channel operator in.
operator_password – The operator password of the channel.

Raises:

TypeError – If the user or channel is not of type teamtalk.User or int.
PermissionError – If the bot doesn’t have the permission to make a user the channel operator.
ValueError – If the channel or user does not exist.

Returns:

True if the user was removed as the channel operator, False otherwise.

Return type:

bool

get_user(user_id: int) → User¶

Gets a user by its ID.

Parameters:: user_id – The ID of the user to get.
Returns:: The user.
Return type:: TeamTalkUser

create_user_account(username: str, password: str, usertype: UserType) → UserAccount¶

Creates a user account on the server.

Parameters:

username – The username of the user account.
password – The password of the user account.
usertype – The type of the user account.

Returns:

The user account.

Return type:

TeamTalkUserAccount

Raises:

ValueError – If the username or password is invalid.
PermissionError – If the bot does not have permission to create a user account or if the bot is not logged in.

delete_user_account(username: str) → bool¶

Deletes a user account.

Parameters:

username – The username of the user account to delete.

Returns:

True if the user account was deleted, False otherwise.

Return type:

bool

Raises:

ValueError – If the username is empty or the user account does not exist.
PermissionError – If the user does not have permission to delete a user account.

await list_user_accounts() → List[UserAccount]¶

Lists all user accounts on the server.

Returns:

A list of all user accounts.

Raises:

PermissionError – If the bot is not an admin.
ValueError – If an unknown error occurred.

upload_file(channel_id: int, filepath: str) → None¶

Uploads a local file to a channel.

Parameters:

channel_id – The ID of the channel to upload the file to.
filepath – The path to the local file to upload.

Raises:

PermissionError – If the bot does not have permission to upload files.
ValueError – If the channel ID is less than 0.
FileNotFoundError – If the local file does not exist.

download_file(channel_id: int, remote_file_name: str, local_file_path: str) → None¶

Downloads a remote file from a channel.

Parameters:

channel_id – The ID of the channel to download the file from.
remote_file_name – The name of the remote file to download.
local_file_path – The path to save the file to.

Raises:

PermissionError – If the bot does not have permission to download files.
ValueError – If the channel ID is less than 0.

download_file_by_id(channel_id: int, file_id: int, filepath: str)¶

Downloads a remote file from a channel by its ID.

Parameters:

channel_id – The ID of the channel to download the file from.
file_id – The ID of the file to download.
filepath – The path to save the file to.

Raises:

PermissionError – If the bot does not have permission to download files.

delete_file_by_id(channel_id: int, file_id: int)¶

Deletes a remote file from a channel by its ID.

Parameters:

channel_id – The ID of the channel to delete the file from.
file_id – The ID of the file to delete.

Raises:

PermissionError – If the bot does not have permission to delete files.

get_channel_files(channel_id: int) → List[RemoteFile]¶

Gets a list of remote files in a channel.

Parameters:: channel_id – The ID of the channel to get the files from.
Returns:: A list of remote files in the channel.
Return type:: List[RemoteFile]

move_user(user: User | int, channel: Channel | int) → None¶

Moves a user to a channel.

Parameters:

user – The user to move.
channel – The channel to move the user to.

Raises:

PermissionError – If the bot does not have permission to move users.
TypeError – If the user or channel is not a subclass of User or Channel.

kick_user(user: User | int, channel: Channel | int) → None¶

Kicks a user from a channel or the server.

Parameters:

user – The user to kick.
channel – The channel to kick the user from. If 0, the user will be kicked from the server. # noqa

Raises:

PermissionError – If the bot does not have permission to kick users.
TypeError – If the user or channel is not a subclass of User or Channel.
ValueError – If the user or channel is not found.

ban_user(user: User | int, channel: Channel | int) → None¶

Bans a user from a channel or the server.

Parameters:

user – The user to ban.
channel – The channel to ban the user from. If 0, the user will be banned from the server. # noqa

Raises:

PermissionError – If the bot does not have permission to ban users.
TypeError – If the user or channel is not a subclass of User or Channel.
ValueError – If the user is not found.

unban_user(ip: str, channel: Channel | int) → None¶

Unbans a user from the server.

Parameters:

ip – The IP address of the user to unban.
channel – The channel to unban the user from. If 0, the user will be unbanned from the server. # noqa

Raises:

PermissionError – If the bot does not have permission to unban users.

await list_banned_users() → List[BannedUserAccount]¶

Lists all banned users.

Returns:

A list of banned users.

Return type:

List[BannedUserAccount]

Raises:

PermissionError – If the bot is not an admin.
ValueError – If an unknown error occurs.

get_server_statistics(timeout: int) → Statistics¶

Gets the statistics from the server.

Parameters:: timeout – The time to wait before assuming that getting the servers statistics failed.
Raises:: TimeoutError – If the server statistics are not received with in the given time.
Returns:: The teamtalk.statistics object representing the servers statistics.