berconpy.AsyncRCONClient

class berconpy.AsyncRCONClient(protocol_cls=<class 'berconpy.protocol.RCONClientDatagramProtocol'>)

An asynchronous interface for connecting to an BattlEye RCON server.

Note

Most of this class’s methods for sending commands like kick() may raise RCONCommandError or RuntimeError since they rely on the send_command() method.

Methods

add_listener(event, func)	Adds a listener for a given event, e.g.
ban(addr[, duration, reason])	Bans a given player ID, GUID, or IP address (without port).
close()	Closes the connection.
connect(ip, port, password)	Returns an asynchronous context manager for logging into the given IP and port with password.
fetch_admins()	Requests a list of RCON admins connected to the server, ordered by admin ID and IP address with port.
fetch_bans()	Requests a list of bans on the server.
fetch_missions()	Requests a list of mission files on the server.
fetch_players()	Requests a list of players from the server.
get_player(player_id)	Gets a player from cache using their server-given ID.
is_connected()	Indicates if the client has a currently active connection with the server.
is_logged_in()	Indicates if the client is currently authenticated with the server.
is_running()	Indicates if the client is running.
kick(player_id[, reason])	Kicks a player with the given ID from the server with an optional reason.
listen([event])	A decorator shorthand to add a listener for a given event, e.g.
remove_listener(event, func)	Removes a listener from a given event, e.g.
send(message)	Sends a message to all players in the server.
send_command(command)	Sends a command to the server and waits for a response.
unban(ban_id)	Removes the ban with the given ID from the server.
wait_for(event, *[, check, timeout])	Waits for a specific event to occur and returns the result.
whisper(player_id, message)	Sends a message to the player with the given ID.

Attributes

client_id	The RCON admin ID this client was given or None if the client has not logged in.
players	The list of players in the server.

add_listener(event, func)

Adds a listener for a given event, e.g. "on_login".

See the Event Reference for a list of supported events.

Parameters:

• event (str) – The event to listen for.

• func (Callable[..., Coroutine]) – The coroutine function to dispatch when the event is received.

async ban(addr, duration=None, reason='')

Bans a given player ID, GUID, or IP address (without port).

Note that the player ID cannot be used to ban players that are no longer in the server; a GUID or IP address must be provided.

Player.ban_ip() and Player.ban_guid() are shorthands for calling this method.

Parameters:

• addr (int | str) – The ID, GUID, or IP address to ban.

• duration (Optional[int]) – The duration of the ban in minutes. If None, the ban will be permanent.

• reason (str) – An optional reason to include with the ban.

Return type:

str

close()

Closes the connection.

This method is idempotent and can be called multiple times consecutively.

Changed in version 1.1: This method no longer causes the current task to be cancelled.

connect(ip, port, password)

Returns an asynchronous context manager for logging into the given IP and port with password.

Example usage:

client = berconpy.AsyncRCONClient()
async with client.connect(ip, port, password):
    print("Connected!")
print("Disconnected!")

If an unexpected error occurs after successfully logging in, the current task that the context manager is used in will be cancelled to prevent the script being stuck in an infinite loop.

Raises:

• LoginFailure – The password given to the server was denied.

• RuntimeError – This method was called while the client is already connected.

async fetch_admins()

Requests a list of RCON admins connected to the server, ordered by admin ID and IP address with port.

Return type:

list[tuple[int, str]]

async fetch_bans()

Requests a list of bans on the server.

Return type:

list[Ban]

async fetch_missions()

Requests a list of mission files on the server.

Return type:

list[str]

async fetch_players()

Requests a list of players from the server.

This method also updates the player cache and pings of each player.

Return type:

list[Player]

get_player(player_id)

Gets a player from cache using their server-given ID.

Parameters:

player_id (int) – The ID of the player.

Return type:

Optional[Player]

Returns:

The retrieved player or None if not found.

is_connected()

Indicates if the client has a currently active connection with the server.

Return type:

bool

is_logged_in()

Indicates if the client is currently authenticated with the server.

Return type:

Optional[bool]

Returns:

True if authenticated or None if no response has been received from the server.

Raises:

LoginFailure – The password given to the server was denied.

is_running()

Indicates if the client is running. This may not necessarily mean that the client is connected.

Return type:

bool

async kick(player_id, reason='')

Kicks a player with the given ID from the server with an optional reason.

Player.kick() is a shorthand for calling this method.

Parameters:

• player_id (int) – The ID of the player.

• reason (str) – An optional reason to show when kicking.

Return type:

str

listen(event=None)

A decorator shorthand to add a listener for a given event, e.g. "on_login".

Example usage:

>>> client = AsyncRCONClient()
>>> @client.listen()
... async def on_login():
...     print("We have logged in!")

Parameters:

event (Optional[str]) – The event to listen for. If None, the function name is used as the event name.

remove_listener(event, func)

Removes a listener from a given event, e.g. "on_login".

This method is a no-op if the given event and function does not match any registered listener.

Parameters:

• event (str) – The event used by the listener.

• func (Callable[..., Coroutine]) – The coroutine function used by the listener.

async send(message)

Sends a message to all players in the server.

Parameters:

message (str) – The message to send. Only ASCII characters are allowed.

Return type:

str

async send_command(command)

Sends a command to the server and waits for a response.

Parameters:

command (str) – The command to send. Only ASCII characters are allowed.

Return type:

str

Returns:

The server’s response as a string.

Raises:

• RCONCommandError – The server has either disabled this command or failed to respond to our command.

• RuntimeError – The client is either not connected or the server could/would not respond to the command.

async unban(ban_id)

Removes the ban with the given ID from the server.

Parameters:

ban_id (int) – The ID of the ban to remove.

Return type:

str

async wait_for(event, *, check=None, timeout=None)

Waits for a specific event to occur and returns the result.

This allows handling one-shot events in a simpler manner than with persistent listeners.

Parameters:

• event (str) – The event to wait for, e.g. "login" and "on_login".

• check (Union[Callable[..., Coroutine], Callable, None]) – An optional predicate function to use as a filter. This can be either a regular or an asynchronous function. The function should accept the same arguments that the event normally takes.

• timeout (Union[float, int, None]) – An optional timeout for the function. If this is provided and the function times out, an asyncio.TimeoutError is raised.

Returns:

The same arguments received in the event.

Raises:

asyncio.TimeoutError – The timeout was exceeded while waiting.

async whisper(player_id, message)

Sends a message to the player with the given ID.

Player.send() is a shorthand for calling this method.

Parameters:

• player_id (int) – The ID of the player to send to.

• message (str) – The message to send. Only ASCII characters are allowed.

Return type:

str

property client_id: int | None

The RCON admin ID this client was given or None if the client has not logged in.

property players: list[berconpy.player.Player]

The list of players in the server.