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.

final class JavaClient(connection: 'TCPSocketConnection', address: 'Address', version: 'int', ping_token: 'int' = None)

Bases: _BaseJavaClient

connection: TCPSocketConnection

handshake() → None

Write the initial handshake packet to the connection.

read_status() → JavaStatusResponse

Send the status request and read the response.

test_ping() → float

Send a ping token and measure the latency.

final class AsyncJavaClient(connection: 'TCPAsyncSocketConnection', address: 'Address', version: 'int', ping_token: 'int' = None)

Bases: _BaseJavaClient

connection: TCPAsyncSocketConnection

async handshake() → None

Write the initial handshake packet to the connection.

async read_status() → JavaStatusResponse

Send the status request and read the response.

async test_ping() → float

Send a ping token and measure the latency.

final class LegacyClient(connection: BaseSyncConnection)

Bases: _BaseLegacyClient

read_status() → LegacyStatusResponse

Send the status request and read the response.

final class AsyncLegacyClient(connection: BaseAsyncConnection)

Bases: _BaseLegacyClient

async read_status() → LegacyStatusResponse

Send the status request and read the response.

final class BedrockClient(address: Address, timeout: float = 3)

Bases: object

request_status_data: ClassVar[bytes] = 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.

port: int

The port of the server.

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

Parse 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

Resolve 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

Resolve 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.

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.

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_resolve_a_record(hostname: str, lifetime: float | None = None) → str

Asynchronous alternative to resolve_a_record().

For more details, check it.

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.

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_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

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.

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

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.

abstractmethod classmethod build(*args: Any, **kwargs: Any) → Self

Build BaseStatusResponse and check is it valid.

Parameters:

• args – Arguments in specific realisation.

• kwargs – Keyword arguments in specific realisation.

Returns:

BaseStatusResponse object.

as_dict() → dict[str, Any]

Return the dataclass as JSON-serializable dict.

Do note that this method doesn’t return string but dict, so you can do some processing on returned value.

Difference from raw is in that, raw returns raw response in the same format as we got it. This method returns the response in a more user-friendly JSON serializable format (for example, motd is returned as a Minecraft string and not dict).

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.