samp_query module

API reference

class samp_query.Client(ip: str, port: int, rcon_password: str | None = None, prefix: bytes | None = None, _socket: SocketType | None = None)

Bases: object

Main query client class to interact with a given game server.

Parameters:

ip (str) – The IP address of the server.
port (int) – The port number of the server.
rcon_password (str | None) – The RCON password for the server (optional).

async connect() → None: Connect to the server (called automatically).

async info() → ServerInfo

Retrieve server information.

Returns:: The server information.
Return type:: ServerInfo

async is_omp() → bool

Check if the server uses open.mp.

Returns:: True if the server uses open.mp, False otherwise.
Return type:: bool

async ping() → float

Send a ping request to the server and measure the round-trip time.

Returns:: The round-trip time in seconds.
Return type:: float

async players() → PlayerList

Retrieve the list of players on the server.

Returns:: The list of players.
Return type:: PlayerList

async rcon(command: str) → str

Execute a RCON command on the server.

Parameters:

command (str) – The RCON command to execute.

Returns:

The response from the server.

Return type:

str

Raises:

MissingRCONPassword – If the RCON password is missing.
InvalidRCONPassword – If an invalid RCON password is provided.
RCONDisabled – If RCON is disabled on the server or no response was received.

async receive(header: bytes = b'') → bytes

Receive a query response from the server.

Parameters:: header (bytes) – The expected header of the response (optional).
Returns:: The received response.
Return type:: bytes

async rules() → RuleList

Retrieve the list of server rules.

Returns:: The list of rules.
Return type:: RuleList

async send(opcode: bytes, payload: bytes = b'') → None

Send a query message to the server.

Parameters:

opcode (bytes) – The opcode of the message.
payload (bytes) – The payload of the message (optional).

class samp_query.Encodings

Bases: TypedDict

Encoding detection sources: name, gamemode, and language.

exception samp_query.InvalidRCONPassword

Bases: Exception

Raised when an invalid RCON password is provided.

exception samp_query.MissingRCONPassword

Bases: Exception

Raised when no RCON password was provided.

class samp_query.PlayerInfo(name: str, score: int)

Bases: object

Represents player information.

Parameters:

name (str) – The name of the player.
score (int) – The score of the player.

classmethod from_data(data: bytes) → tuple[PlayerInfo, bytes]

Create a PlayerInfo object from the given raw data.

Parameters:: data (bytes) – The data to create the PlayerInfo object from.
Returns:: The created PlayerInfo object and the remaining data.
Return type:: tuple[PlayerInfo, bytes]

class samp_query.PlayerList(players: list[PlayerInfo])

Bases: object

Represents a list of players.

Parameters:: players (list[PlayerInfo]) – The list of players.

classmethod from_data(data: bytes) → PlayerList

Create a PlayerList object from the given raw data.

Parameters:: data (bytes) – The data to create the PlayerList object from.
Returns:: The created PlayerList object.
Return type:: PlayerList

exception samp_query.RCONDisabled

Bases: Exception

Raised when RCON is disabled on the server or did not respond.

class samp_query.Rule(name: str, value: str, encoding: str)

Bases: object

Represents a server rule.

Parameters:

name (str) – The name of the rule.
value (str) – The value of the rule.

classmethod from_data(data: bytes) → tuple[Rule, bytes]

Create a Rule object from the given raw data.

Parameters:: data (bytes) – The data to create the Rule object from.
Returns:: The created Rule object and the remaining data.
Return type:: tuple[Rule, bytes]

class samp_query.RuleList(rules: list[Rule])

Bases: object

Represents a list of server rules.

Parameters:: rules (list[Rule]) – The list of rules.

classmethod from_data(data: bytes) → RuleList

Create a RuleList object from the given raw data.

Parameters:: data (bytes) – The data to create the RuleList object from.
Returns:: The created RuleList object.
Return type:: RuleList

class samp_query.ServerInfo(name: str, password: bool, players: int, max_players: int, gamemode: str, language: str, encodings: Encodings)

Bases: object

Represents server information.

Parameters:

name (str) – The name of the server.
password (bool) – Indicates if the server requires a password to join.
players (int) – The number of players on the server.
max_players (int) – The maximum number of players allowed on the server.
gamemode (str) – The current gamemode of the server.
language (str) – The language used by the server.

classmethod from_data(data: bytes) → ServerInfo

Create a ServerInfo object from the given raw data.

Parameters:: data (bytes) – The data to create the ServerInfo object from.
Returns:: The created ServerInfo object.
Return type:: ServerInfo

samp_query.encode_codepage(string: str) → bytes

Encode the given string into bytes using the first possible codepage.

Parameters:: string (str) – The string to encode.
Returns:: The encoded bytes.
Return type:: bytes
Raises:: UnicodeEncodeError – If no suitable codepage is found.

samp_query.pack_string(string: str, len_type: str) → bytes

Pack a string into bytes with a length prefix.

Parameters:

string (str) – The string to pack.
len_type (str) – The format specifier for the length prefix.

Returns:

The packed bytes.

Return type:

bytes

samp_query.unpack_string(data: bytes, len_type: str) → tuple[str, bytes, str]

Unpack a string from bytes with a length prefix.

Parameters:

data (bytes) – The data to unpack.
len_type (str) – The format specifier for the length prefix.

Returns:

The unpacked string, the remaining data, and the detected encoding.

Return type:

tuple[str, bytes]