Synchronous Clients#

Added in version 0.2.0.

This covers the synchronous I/O client provided by little-a2s.

class little_a2s.A2S(sock)#

Bases: object

A synchronous client for A2S queries.

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.settimeout(1)
sock.connect(("127.0.0.1", 27015))
with A2S(sock) as a2s:
    print(a2s.info())
    print(a2s.players())
    print(a2s.rules())

This follows the Source format. For the Goldsource equivalent, see A2SGoldsource.

This class supports the context manager protocol which automatically closes the socket upon exit.

This class is not thread-safe.

Parameters:: sock (socket) – The UDP socket to send and receive queries from. The socket can be connected to a remote address beforehand with connect(), if you want to skip addr arguments in send methods. You may also want to set a timeout with settimeout(). Alternatively, use from_addr(), from_ipv4(), or from_ipv6() to construct the socket for you.

Added in version 0.2.0.

Changed in version 0.5.0: Removed the challenge= parameter.

Changed in version 0.5.0: Removed the events_received() method.

Changed in version 0.6.0: Passing a socket that is not of type socket.SOCK_DGRAM will raise TypeError instead of ValueError.

classmethod from_addr(host, port, timeout=3.0, *, prefer_ipv4=True)#

Resolve the given host and create an A2S query.

Parameters:

host (str) – The IPv4 address, IPv6 address, or domain name to query.
port (int) – The port to query.
timeout (float | None) – The timeout to set on the socket.
prefer_ipv4 (bool) –
If True, prefer to resolve hostnames to IPv4 addresses. This may still connect the socket to an IPv6 address so if you need more control, consider using socket.getaddrinfo() to manually create a socket and pass it to the constructor.

Added in version 0.2.1.

Raises:

OSError – The address could not be resolved.

Return type:

Self

classmethod from_ipv4(timeout=3.0)#

Create an A2S query with a UDP IPv4 socket not connected to any address.

This allows you to use the same socket with addr arguments:

with A2S.from_ipv4() as a2s:
    info = a2s.info(("127.0.0.1", 2303))
    info = a2s.info(("127.0.0.1", 27015))

Parameters:: timeout (float | None) – The timeout to set on the socket.
Return type:: Self

Added in version 0.4.0.

classmethod from_ipv6(timeout=3.0)#

Create an A2S query with a UDP IPv6 socket not connected to any address.

This allows you to use the same socket with addr arguments:

with A2S.from_ipv6() as a2s:
    info = a2s.info(("::1", 2303))
    info = a2s.info(("::1", 27015))

Parameters:: timeout (float | None) – The timeout to set on the socket.
Return type:: Self

Added in version 0.4.0.

info(addr=None)#

Send an A2S_INFO request and wait for a response.

Changed in version 0.5.0: addr can now be a positional argument.

Parameters:

addr (tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes] | None) –

The address to send the request to. Does not apply if socket is already connected to an address, such as from from_addr().

Added in version 0.4.0.

Raises:

ChallengeError – The server sent too many challenges.
PayloadError – The server sent a malformed packet.
TimeoutError – The socket timed out.
TypeError – The addr argument was required or forbidden.

Return type:

ClientEventInfo

players(addr=None)#

Send an A2S_PLAYER request and wait for a response.

Changed in version 0.5.0: addr can now be a positional argument.

Parameters:

addr (tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes] | None) –

The address to send the request to. Does not apply if socket is already connected to an address, such as from from_addr().

Added in version 0.4.0.

Raises:

ChallengeError – The server sent too many challenges.
PayloadError – The server sent a malformed packet.
TimeoutError – The socket timed out.
TypeError – The addr argument was required or forbidden.

Return type:

ClientEventPlayers

rules(addr=None)#

Send an A2S_RULES request and wait for a response.

Changed in version 0.5.0: addr can now be a positional argument.

Parameters:

addr (tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes] | None) –

The address to send the request to. Does not apply if socket is already connected to an address, such as from from_addr().

Added in version 0.4.0.

Raises:

ChallengeError – The server sent too many challenges.
PayloadError – The server sent a malformed packet.
TimeoutError – The socket timed out.
TypeError – The addr argument was required or forbidden.

Return type:

ClientEventRules

class little_a2s.A2SGoldsource(sock)#

Bases: A2S

A synchronous client for A2S Goldsource queries.

Parameters:: sock (socket)

classmethod from_addr(host, port, timeout=3.0, *, prefer_ipv4=True)#

Resolve the given host and create an A2S query.

Parameters:

host (str) – The IPv4 address, IPv6 address, or domain name to query.
port (int) – The port to query.
timeout (float | None) – The timeout to set on the socket.
prefer_ipv4 (bool) –
If True, prefer to resolve hostnames to IPv4 addresses. This may still connect the socket to an IPv6 address so if you need more control, consider using socket.getaddrinfo() to manually create a socket and pass it to the constructor.

Added in version 0.2.1.

Raises:

OSError – The address could not be resolved.

Return type:

Self

classmethod from_ipv4(timeout=3.0)#

Create an A2S query with a UDP IPv4 socket not connected to any address.

This allows you to use the same socket with addr arguments:

with A2S.from_ipv4() as a2s:
    info = a2s.info(("127.0.0.1", 2303))
    info = a2s.info(("127.0.0.1", 27015))

Parameters:: timeout (float | None) – The timeout to set on the socket.
Return type:: Self

Added in version 0.4.0.

classmethod from_ipv6(timeout=3.0)#

Create an A2S query with a UDP IPv6 socket not connected to any address.

This allows you to use the same socket with addr arguments:

with A2S.from_ipv6() as a2s:
    info = a2s.info(("::1", 2303))
    info = a2s.info(("::1", 27015))

Parameters:: timeout (float | None) – The timeout to set on the socket.
Return type:: Self

Added in version 0.4.0.

info(addr=None)#

Send an A2S_INFO request and wait for a response.

Changed in version 0.5.0: addr can now be a positional argument.

Parameters:

addr (tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes] | None) –

The address to send the request to. Does not apply if socket is already connected to an address, such as from from_addr().

Added in version 0.4.0.

Raises:

ChallengeError – The server sent too many challenges.
PayloadError – The server sent a malformed packet.
TimeoutError – The socket timed out.
TypeError – The addr argument was required or forbidden.

Return type:

ClientEventGoldsourceInfo

players(addr=None)#

Send an A2S_PLAYER request and wait for a response.

Changed in version 0.5.0: addr can now be a positional argument.

Parameters:

addr (tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes] | None) –

The address to send the request to. Does not apply if socket is already connected to an address, such as from from_addr().

Added in version 0.4.0.

Raises:

ChallengeError – The server sent too many challenges.
PayloadError – The server sent a malformed packet.
TimeoutError – The socket timed out.
TypeError – The addr argument was required or forbidden.

Return type:

ClientEventPlayers

rules(addr=None)#

Send an A2S_RULES request and wait for a response.

Changed in version 0.5.0: addr can now be a positional argument.

Parameters:

addr (tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes] | None) –

The address to send the request to. Does not apply if socket is already connected to an address, such as from from_addr().

Added in version 0.4.0.

Raises:

ChallengeError – The server sent too many challenges.
PayloadError – The server sent a malformed packet.
TimeoutError – The socket timed out.
TypeError – The addr argument was required or forbidden.

Return type:

ClientEventRules

Synchronous Clients

Contents

Synchronous Clients#