Internal Data

This page contains some internal objects, classes, functions, etc. These are not a part of the Public API and you should not use them, as we do not guarantee their backwards compatibility between different library versions. They are only documented here for linkable reference to them.

class ServerPinger(connection: TCPSocketConnection, address: Address, version: int = 47, ping_token: int | None = None)

handshake() → None

read_status() → JavaStatusResponse

test_ping() → float

class AsyncServerPinger(connection: TCPAsyncSocketConnection, address: Address, version: int = 47, ping_token: int | None = None)

Bases: ServerPinger

async read_status() → JavaStatusResponse

async test_ping() → float

class BedrockServerStatus(address: Address, timeout: float = 3)

request_status_data = b'\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\x00\xfe\xfe\xfe\xfe\xfd\xfd\xfd\xfd\x124Vx\x00\x00\x00\x00\x00\x00\x00\x00'

static parse_response(data: bytes, latency: float) → BedrockStatusResponse

read_status() → BedrockStatusResponse

async read_status_async() → BedrockStatusResponse

class Address(host: str, port: int)

Bases: _AddressBase

Extension of a NamedTuple of host and port, for storing addresses.

This class inherits from tuple, and is fully compatible with all functions which require pure (host, port) address tuples, but on top of that, it includes some neat functionalities, such as validity ensuring, alternative constructors for easy quick creation and methods handling IP resolving.

Note

The class is not a part of a Public API, but attributes host and port are a part of Public API.

host: str

The hostname or IP address of the server. Is a part of Public API.

port: int

The port of the server. Is a part of Public API.

classmethod from_tuple(tup: tuple[str, int]) → Self

Construct the class from a regular tuple of (host, port), commonly used for addresses.

classmethod from_path(path: Path, *, default_port: int | None = None) → Self

Construct the class from a Path object.

If path has a port specified, use it, if not fall back to default_port kwarg. In case default_port isn’t provided and port wasn’t specified, raise ValueError.

classmethod parse_address(address: str, *, default_port: int | None = None) → Self

Parses a string address like 127.0.0.1:25565 into host and port parts.

If the address has a port specified, use it, if not, fall back to default_port kwarg.

Raises:

ValueError – Either the address isn’t valid and can’t be parsed, or it lacks a port and default_port wasn’t specified.

resolve_ip(lifetime: float | None = None) → IPv4Address | IPv6Address

Resolves a hostname’s A record into an IP address.

If the host is already an IP, this resolving is skipped and host is returned directly.

Parameters:

lifetime – How many seconds a query should run before timing out. Default value for this is inherited from dns.resolver.resolve().

Raises:

dns.exception.DNSException – One of the exceptions possibly raised by dns.resolver.resolve(). Most notably this will be dns.exception.Timeout and dns.resolver.NXDOMAIN

async async_resolve_ip(lifetime: float | None = None) → IPv4Address | IPv6Address

Resolves a hostname’s A record into an IP address.

See the docstring for resolve_ip() for further info. This function is purely an async alternative to it.

minecraft_srv_address_lookup(address: str, *, default_port: int | None = None, lifetime: float | None = None) → Address

Lookup the SRV record for a Minecraft server.

Firstly it parses the address, if it doesn’t include port, tries SRV record, and if it’s not there, falls back on default_port.

This function essentially mimics the address field of a Minecraft Java server. It expects an address like 192.168.0.100:25565, if this address does contain a port, it will simply use it. If it doesn’t, it will try to perform an SRV lookup, which if found, will contain the info on which port to use. If there’s no SRV record, this will fall back to the given default_port.

Parameters:

• address – The same address which would be used in minecraft’s server address field. Can look like: 127.0.0.1, or 192.168.0.100:12345, or mc.hypixel.net, or example.com:12345.

• lifetime – How many seconds a query should run before timing out. Default value for this is inherited from dns.resolver.resolve().

Raises:

ValueError – Either the address isn’t valid and can’t be parsed, or it lacks a port, SRV record isn’t present, and default_port wasn’t specified.

async async_minecraft_srv_address_lookup(address: str, *, default_port: int | None = None, lifetime: float | None = None) → Address

Just an async alternative to minecraft_srv_address_lookup(), check it for more details.

resolve_a_record(hostname: str, lifetime: float | None = None) → str

Perform a DNS resolution for an A record to given hostname

Parameters:

hostname – The address to resolve for.

Returns:

The resolved IP address from the A record

Raises:

dns.exception.DNSException – One of the exceptions possibly raised by dns.resolver.resolve(). Most notably this will be dns.exception.Timeout, dns.resolver.NXDOMAIN and dns.resolver.NoAnswer

async async_resolve_a_record(hostname: str, lifetime: float | None = None) → str

Asynchronous alternative to resolve_a_record().

For more details, check it.

resolve_srv_record(query_name: str, lifetime: float | None = None) → tuple[str, int]

Perform a DNS resolution for SRV record pointing to the Java Server.

Parameters:

query_name – The address to resolve for.

Returns:

A tuple of host string and port number

Raises:

dns.exception.DNSException – One of the exceptions possibly raised by dns.resolver.resolve(). Most notably this will be dns.exception.Timeout, dns.resolver.NXDOMAIN and dns.resolver.NoAnswer

async async_resolve_srv_record(query_name: str, lifetime: float | None = None) → tuple[str, int]

Asynchronous alternative to resolve_srv_record().

For more details, check it.

resolve_mc_srv(hostname: str, lifetime: float | None = None) → tuple[str, int]

Resolve SRV record for a minecraft server on given hostname.

Parameters:

hostname (str) – The address, without port, on which an SRV record is present.

Returns:

Obtained target and port from the SRV record, on which the server should live on.

Raises:

dns.exception.DNSException – One of the exceptions possibly raised by dns.resolver.resolve(). Most notably this will be dns.exception.Timeout, dns.resolver.NXDOMAIN and dns.resolver.NoAnswer.

async async_resolve_mc_srv(hostname: str, lifetime: float | None = None) → tuple[str, int]

Asynchronous alternative to resolve_mc_srv().

For more details, check it.

class BaseStatusResponse(players: BaseStatusPlayers, version: BaseStatusVersion, motd: Motd, latency: float)

Bases: ABC

Class for storing shared data from a status response.

players: BaseStatusPlayers

The players information.

version: BaseStatusVersion

The version information.

motd: Motd

Message Of The Day. Also known as description.

See also

MOTD Parsing.

latency: float

Latency between a server and the client (you). In milliseconds.

property description: str

Alias to the mcstatus.motd.Motd.to_minecraft() method.

abstract classmethod build(*args, **kwargs) → Self

Build BaseStatusResponse and check is it valid.

Parameters:

• args – Arguments in specific realisation.

• kwargs – Keyword arguments in specific realisation.

Returns:

BaseStatusResponse object.

class BaseStatusPlayers(online: int, max: int)

Bases: ABC

Class for storing information about players on the server.

online: int

Current number of online players.

max: int

The maximum allowed number of players (aka server slots).

class BaseStatusVersion(name: str, protocol: int)

Bases: ABC

A class for storing version information.

name: str

The version name, like 1.19.3.

See Minecraft wiki for complete list.

protocol: int

The protocol version, like 761.

See Minecraft wiki.