API Reference

Below is the API reference for mctools. Each feature is broken up into a different section. The average user shouldn’t have to worry about these, and should instead use the higher level client classes and functions. You can find tutorials on how to use them elsewhere in this documentation.

Exceptions

Exception objects for mctools.

exception mctools.errors.MCToolsError

Base class for mctools exceptions.

exception mctools.errors.PINGError

Base class for PING errors

exception mctools.errors.PINGMalformedPacketError(message)

Exception raised if the ping packet received is malformed/broken, or not what we were expecting.

exception mctools.errors.ProtoConnectionClosed(message)

Exception raised when the connection is closed by the socket we are connected to.

This occurs when we receive empty bytes from ‘recv()’, as this means that the remote socket is done writing, meaning that our connection is closed.

exception mctools.errors.ProtocolError

Base class for protocol errors.

A protocol error is raised when an issue arises with the python socket object. These exceptions will be raised for ALL clients, as they all use the same backend.

exception mctools.errors.RCONAuthenticationError(message)

Exception raised when user is not authenticated to the RCON server. This is raised when a user tries to send a RCON command, and the server refuses to communicate.

Parameters:
  • message (str) – Explanation of the error
  • server_id – ID given to us by the server
exception mctools.errors.RCONCommunicationError(message)

Exception raised if the client has trouble communicating with the RCON server. For example, if we don’t receive any information when we want a packet.

Parameters:message (str) – Explanation of the error
exception mctools.errors.RCONError

Base class for RCON errors.

exception mctools.errors.RCONLengthError(message, length)

Exception raised if the client attempts to send a packet that is too big, greater than length 1460.

exception mctools.errors.RCONMalformedPacketError(message)

Exception raised if the packet we received is malformed/broken, or not what we were expecting.

Parameters:message (str) – Explanation of the error

MClient Reference

Main Minecraft Connection Clients - Easy to use API for the underlying modules Combines the following: - Protocol Implementations - Packet implementations - Formatting tools

class mctools.mclient.BaseClient

Parent class for Minecraft Client implementations. This class has the following formatting constants, which every client inherits:

  • BaseClient.RAW - Tells the client to not format any content.
  • BaseClient.REPLACE - Tells the client to replace format characters.
  • BaseClient.Remove - Tells the client to remove format characters.

You can use these constants in the ‘format_method’ parameter in each client.

gen_reqid()

Generates a request ID using system time.

Returns:System time as an integer
get_formatter()

Returns the formatter used by this instance, Allows the user to change formatter operations.

Returns:FormatterCollection used by the client.
Return type:FormatterCollection
is_connected()

Determine if we are connected to the remote entity, whatever that may be. This raises a ‘NotImplementedError’ exception, as this function should be overridden in the child class.

Returns:True if connected, False if not.
Raises:NotImplementedError: If function is called.
raw_send(*args)

For sending packets with user defined values, instead of the wrappers from client. This raises a ‘NotImplementedError’ exception, as this function should be overridden in the child class.

Parameters:args – Arguments specified, varies from client to client.
Raises:NotImplementedError: If function is called.
set_timeout(timeout)

Sets the timeout for the underlying socket object.

Parameters:timeout (int) – Value in seconds to set the timeout to
start()

Starts the client, and any protocol objects/formatters in use. (Good idea to put a call to Protocol.start() here). This raises a ‘NotImplementedError’ exception, as this function should be overridden in the child class.

Raises:NotImplementedError: If function is called.
stop()

Stops the client, and any protocol objects/formatters in use. (Again, good idea to put a call to Protocol.stop() here). This raises a ‘NotImplementedError’ exception, as this function should be overridden in the child class.

Raises:NotImplementedError: If function is called.
class mctools.mclient.PINGClient(host: str, port: int = 25565, reqid: int = None, format_method: int = 1, timeout: int = 60, proto_num: int = 0)

Ping client, allows for user to interact with the Minecraft server via the Server List Ping protocol.

Parameters:
  • host (str) – Hostname of the Minecraft server
  • port (int) – Port of the Minecraft server
  • reqid (int) – Request ID to use, leave as ‘None’ to generate one based on system time
  • format_method (int) – Format method to use. You should specify this using the Client constants
  • timeout (int) – Sets the timeout value for socket operations
  • proto_num (int) – Protocol number to use, can specify which version we are emulating. Defaults to 0, which is the latest.
get_stats(format_method: int = None, return_packet: bool = False) → Union[dict, mctools.packet.PINGPacket]

Gets stats from the Minecraft server.

Parameters:
  • format_method (int) – Determines the format method we should use. If ‘None’, then we use the global value. You should use the Client constants to define this.
  • return_packet (bool) – Determines if we should return the entire packet. If not, return the payload
Returns:

Dictionary containing stats, or PINGPacket depending on ‘return_packet’
Return type:

dict, PINGPacket

New in version 1.1.0.

The ‘format_method’ and ‘return_packet’ parameters

New in version 1.2.0.

We now automatically stop this client after the operation

is_connected() → bool

Determines if we are connected.

Returns:True if connected, False if otherwise.
Return type:bool
ping() → float

Pings the Minecraft server and calculates the latency.

New in version 1.2.0.

We now automatically stop this client after the operation

Returns:Time elapsed(in milliseconds).
Return type:float
raw_send(pingnum: Optional[int, None], packet_type: str, proto: int = None, host: str = None, port: int = 0, noread: bool = False) → mctools.packet.PINGPacket

Creates a PingPacket and sends it to the Minecraft server

Parameters:
  • pingnum (int, None) – Pingnumber of the packet(For ping packets only)
  • packet_type (str) – Type of packet we are working with
  • proto (int) – Protocol number of the Minecraft server(For handshake only)
  • host (str) – Hostname of the Minecraft server(For handshake only)
  • port (int) – Port of the Minecraft server(For handshake only)
  • noread (bool) – Determining if we are expecting a response
Returns:

PINGPacket if noread if False, otherwise None
Return type:

PINGPacket, None
start()

Starts the connection to the Minecraft server. This is called automatically where appropriate, so you shouldn’t have to worry about calling this.

stop()

Stops the connection to the Minecraft server. This function should always be called when ceasing network communications, as not doing so could cause problems server-side.

class mctools.mclient.QUERYClient(host: str, port: int = 25565, reqid: int = None, format_method: int = 1, timeout: int = 60)

Query client, allows for user to interact with the Minecraft server via the Query protocol.

Parameters:
  • host (str) – Hostname of the Minecraft server
  • port (int) – Port of the Minecraft server
  • reqid (int) – Request ID to use, leave as ‘None’ to generate one based on system time
  • format_method (int) – Format method to use. You should specify this using the Client constants
  • timeout (int) – Sets the timeout value for socket operations
get_basic_stats(format_method: int = None, return_packet: bool = False) → Union[dict, mctools.packet.QUERYPacket]

Gets basic stats from the Query server.

Parameters:
  • format_method (int) – Determines the format method we should use. If ‘None’, then we use the global value. You should use the Client constants to define this
  • return_packet (bool) – Determines if we should return the entire packet. If not, return the payload
Returns:

Dictionary of basic stats, or QUERYPacket, depending on ‘return_packet’.
Return type:

dict, QUERYPacket

New in version 1.1.0.

The ‘format_method’ and ‘return_packet’ parameters

get_challenge() → mctools.packet.QUERYPacket

Gets the challenge token from the Query server. It is necessary to get a token before every operation, as the Query tokens change every 30 seconds.

Returns:QueryPacket containing challenge token.
Return type:QUERYPacket
get_full_stats(format_method: int = None, return_packet: bool = False) → Union[dict, mctools.packet.QUERYPacket]

Gets full stats from the Query server.

Parameters:
  • format_method (int) – Determines the format method we should use. If ‘None’, then we use the global value. You should use the Client constants to define this.
  • return_packet (bool) – Determines if we should return the entire packet. If not, return the payload
Returns:

Dictionary of full stats, or QUERYPacket, depending on ‘return_packet’.
Return type:

dict

New in version 1.1.0.

The ‘format_method’ and ‘return_packet’ parameters

is_connected() → bool

Determines if we are connected. (UPD doesn’t really work that way, so we simply return if we have been started).

Returns:True if started, False for otherwise.
Return type:bool
raw_send(reqtype: int, chall: Optional[str, None], packet_type: str) → mctools.packet.QUERYPacket

Creates a packet from the given arguments and sends it. Returns a response.

Parameters:
  • reqtype (int) – Request type
  • chall (str, None) – Challenge Token
  • packet_type (str) – Packet type(chall, short, full)
Returns:

QUERYPacket containing response
Return type:

QUERYPacket
start()

Starts the Query object. This is called automatically where appropriate, so you shouldn’t have to worry about calling this.

stop()

Stops the connection to the Query server. In this case, it is not strictly necessary to stop the connection, as QueryClient uses the UDP protocol. It is still recommended to stop the instance any way, so you can be explicit in your code as to when you are going to stop communicating over the network.

class mctools.mclient.RCONClient(host, port=25575, reqid=None, format_method=1, timeout=60)

RCON client, allows for user to interact with the Minecraft server via the RCON protocol.

Parameters:
  • host (str) – Hostname of the Minecraft server (Can be an IP address or domain name, anything your computer can resolve)
  • port (int) – Port of the Minecraft server
  • reqid (int) – Request ID to use, leave as ‘None’ to generate an ID based on system time
  • format_method – Format method to use. You should specify this using the Client constants
  • format_method – int
  • timeout (int) – Sets the timeout value for socket operations
authenticate(password) → bool

Convenience function, does the same thing that ‘login’ does, authenticates you with the RCON server.

Parameters:password (str) – Password to authenticate with
Returns:True if successful, False if failure
Return type:bool
command(com: str, check_auth: bool = True, format_method: int = None, return_packet: bool = False, frag_check: bool = True, length_check: bool = True) → Union[mctools.packet.RCONPacket, str]

Sends a command to the RCON server and gets a response.

Note

Be sure to authenticate before sending commands to the server! Most servers will simply refuse to talk to you if you do not authenticate.

Parameters:
  • com (str) – Command to send
  • check_auth (bool) – Value determining if we should check authentication status before sending our command
  • format_method (int) – Determines the format method we should use. If ‘None’, then we use the global value You should use the Client constants to define this.
  • return_packet (bool) – Determines if we should return the entire packet. If not, return the payload
  • frag_check (bool) –

    Determines if we should check and handle packet fragmentation

    Warning

    Disabling fragmentation checks could lead to instability! Do so at your own risk!

  • length_check (bool) –

    Determines if we should check and handle outgoing packet length

    Warning

    Disabling length checks could lead to instability! Do so at your own risk!
Returns:

Response text from server
Return type:

str, RCONPacket
Raises:

RCONAuthenticationError: If we are not authenticated to the RCON server, and authentication checking is enabled. We also raise this if the server refuses to serve us, regardless of weather auth checking is enabled. RCONMalformedPacketError: If the packet we received is broken or is not the correct packet. RCONLengthError: If the outgoing packet is larger than 1460 bytes

New in version 1.1.0.

The ‘check_auth’, ‘format_method’, ‘return_packet’, and ‘frag_check’ parameters

New in version 1.1.2.

The ‘length_check’ parameter

is_authenticated() → bool

Determines if we are authenticated.

Returns:True if authenticated, False if not.
Return type:bool
is_connected() → bool

Determines if we are connected.

Returns:True if connected, False if not.
Return type:bool
login(password) → bool

Authenticates with the RCON server using the given password. If we are already authenticated, then we simply return True.

Parameters:password (str) – RCON Password
Returns:True if successful, False if failure
Return type:bool
raw_send(reqtype: int, payload: str, frag_check: bool = True, length_check: bool = True) → mctools.packet.RCONPacket

Creates a RCON packet based off the following parameters and sends it. This function is used for all networking operations.

We automatically check if a packet is fragmented(We check it’s length). If this is the case, then we send a junk packet, and we keep reading packets until the server acknowledges the junk packet. This operation can take some time depending on network speed, so we offer the option to disable this feature, with the risk that their might be stability issues.

We also check if the packet being sent is too big, and raise an exception of this is the case. This can be disabled by passing False to the ‘length_check’ parameter, although this is not recommended.

Warning

Use this function at you own risk! You should really call the high level functions, as not doing so could mess up the state/connection of the client.

Parameters:
  • reqtype (int) – Request type
  • payload (str) – Payload to send
  • frag_check (bool) – Determines if we should check and handle packet fragmentation.

Warning

Disabling fragmentation checks could lead to instability! Do so at your own risk!

Parameters:length_check (bool) – Determines if we should check for outgoing packet length

Warning

Disabling length checks could lead to instability! Do so at your own risk!

Returns:RCONPacket containing response from server
Return type:RCONPacket
Raises:RCONAuthenticationError: If the server refuses to server us and we are not authenticated. RCONMalformedPacketError: If the request ID’s do not match of the packet is otherwise malformed.

New in version 1.1.0.

The ‘frag_check’ parameter

New in version 1.1.2.

The ‘length_check’ parameter

start()

Starts the connection to the RCON server. This is called automatically where appropriate, so you shouldn’t have to worry about calling this.

stop()

Stops the connection to the RCON server. This function should always be called when ceasing network communications, as not doing so could cause problems server-side.

Packet Reference

Packet classes to hold RCON and Query data

class mctools.packet.BasePacket

Parent class for packet implementations.

classmethod from_bytes(byts)

Classmethod to create a packet from bytes. Rises an NotImplementedError excpetion, as this function should be overidden in the child class.

Parameters:byts – Bytes from remote entity
Returns:Packet object
class mctools.packet.PINGPacket(pingnum, packet_type, data: dict = None, proto=None, host=None, port=0)

Class representing a Server List Ping Packet(Or ping for short).

Parameters:
  • pingnum (int) – Number to use for ping operations
  • packet_type (str) – Type of packet we are working with
  • data (dict, None) – Ping data from Minecraft server
  • proto (str, None) – Protocol Version used
  • host (str, None) – Hostname of the Minecraft server
  • port (int) – Port number of the Minecraft server
classmethod from_bytes(byts)

Creates a PINGPacket from bytes.

Parameters:byts – Bytes to decode
Returns:PINGPacket
class mctools.packet.QUERYPacket(reqtype, reqid, chall, data_type, data: dict = None)

Class representing a Query Packet.

Parameters:
  • reqtype (int) – Type of Query packet
  • reqid (int) – Request ID of the Query packet
  • chall (str, None) – Challenge token from Query server
  • data_type (str) – What type of data we contain
  • data (dict) – Data from the Query server
classmethod from_bytes(byts)

Creates a Query packet from bytes.

Parameters:byts – Bytes from Query server
Returns:QUERYPacket.
class mctools.packet.RCONPacket(reqid, reqtype, payload, length=0)

Class representing a RCON packet.

Parameters:
  • reqid (int) – Request ID of the RCON packet
  • reqtype (int) – Request type of the RCON packet
  • payload (str) – Payload of the RCON packet
classmethod from_bytes(byts)

Creates a RCON packet from bytes.

Parameters:byts – Bytes from RCON server
Returns:RCONPacket

Encoding Reference

Encoding/Decoding Tools for RCON and Query.

class mctools.encoding.BaseEncoder

Parent class for encoder implementation.

static decode(data)

Decodes data, and returns it in workable form(Whatever that may be) Raises ‘NotImplementedError’ exception, as this function should be overridden in the child class.

Parameters:data – Data to be decoded
Returns:Data in workable format
static encode(data)

Encodes data, and returns it in byte form. Raises ‘NotImplementedError’ exception, as this function should be overridden in the child class.

Parameters:data – Data to be encoded
Returns:Bytestring
class mctools.encoding.PINGEncoder

Ping encoder/decoder.

static decode(byts) → Tuple[dict, None, str]

Decodes a ping packet. NOTE: Bytes provided should NOT include the length, that is interpreted and used by the PINGProtocol.

Parameters:byts – Bytes to decode
Returns:Tuple of decoded values
static decode_sock(sock) → int

Decodes a var(int/long) of variable length or value. We use a socket to continuously pull values until we reach a valid value, as the length of these var(int/long)s can be either very long or very short.

Parameters:sock – Socket object to get bytes from.
Returns:Decoded integer
Return type:int
static decode_varint(byts) → Tuple[int, int]

Decodes varint bytes into an integer. We also return the amount of bytes read.

Parameters:byts – Bytes to decode
Returns:result, bytes read
Return type:int, int
static encode(data)

Encodes a Ping packet.

Parameters:data – Data to be encoded, in tuple form
Returns:Bytes
static encode_varint(num: int) → bytes

Encodes a number into varint bytes.

Parameters:num (int) – Number to encode
Returns:Bytes
class mctools.encoding.QUERYEncoder

Query encoder/decoder

static decode(byts)

Decodes packets from the Query protocol. This gets really messy, as the payload can be many different things. We also figure out what kind of data we are working with, and return that.

Parameters:byts – Bytes to decode
Returns:Tuple containing decoded items - reqtype, reqid, chall, data, type
static encode(data)

Encodes a Query Packet.

Parameters:data – Tuple of data to encode
Returns:Encoded data
class mctools.encoding.RCONEncoder

RCON Encoder/Decoder.

static decode(byts)

Decodes raw bytestring packet from the RCON server. NOTE: DOES NOT DECODE LENGTH! The ‘length’ vale is omitted, as it is interpreted by the RCONProtocol. If your bytestring contains the encoded length, simply remove the first 4 bytes.

Parameters:byts – Bytestring
Returns:Tuple containing values
static encode(data)

Encodes a RCON packet.

Parameters:data – Tuple containing packet data
Returns:Bytestring of encoded data

Protocol Reference

Low-level protocol stuff for RCON, Query and Server List Ping.

class mctools.protocol.BaseProtocol

Parent Class for protocol implementations. Every protocol instance should inherit this class!

read()

Method to receive data from remote entity This raises a NotImplementedErrorException, as it should be overridden in the child class.

Returns:Data received, data type is arbitrary
read_tcp(length)

Reads data over the TCP protocol.

Parameters:length (int) – Amount of data to read
Returns:Read bytes
read_udp()

Reads data over the UDP protocol.

Returns:Bytes read
send(data)

Method to send data to remote entity, data type is arbitrary. This raises a NotImplementedErrorException, as it should be overridden in the child class.

Parameters:data – Some data in some format.
set_timeout(timeout)

Sets the timeout value for the underlying socket object.

Parameters:timeout (int) – Value in seconds to set the timeout to

New in version 1.1.0.

This method now works before the protocol object is started

start()

Method to start the connection to remote entity. This raises a NotImplementedErrorException, as it should be overridden in the child class.

stop()

Method to stop the connection to remote entity. This raises a NotImplementedErrorException, as it should be overridden in the child class.

write_tcp(byts)

Writes data over the TCP protocol.

Parameters:byts – Bytes to send
Returns:Data read
write_udp(byts, host, port)

Writes data over the UPD protocol.

Parameters:
  • byts – Bytes to write
  • host – Hostanme of remote host
  • port – Portname of remote host
Returns:
class mctools.protocol.PINGProtocol(host, port, timeout)

Protocol implementation for server list ping - uses TCP sockets.

Parameters:
  • host (str) – Hostname of the Minecraft server
  • port (int) – Port number of the Minecraft server
  • timeout (int) – Timeout value used for socket operations
read()

Read data from the Minecraft server and convert it into a PINGPacket.

Returns:PINGPacket
Return type:PINGPacket
send(pack)

Sends a ping packet to the Minecraft server.

Parameters:pack (PINGPacket) – PINGPacket
start()

Starts the connection to the Minecraft server.

stop()

Stopping the connection to the Minecraft server.

class mctools.protocol.QUERYProtocol(host, port, timeout)

Protocol implementation for Query - Uses UDP sockets.

Parameters:
  • host (str) – The hostname of the Query server.
  • port (int) – Port number of the Query server
  • timeout (int) – Timeout value for socket operations
read()

Gets a Query packet from the Query server.

Returns:QUERYPacket
Return type:QUERYPacket
send(pack)

Sends a packet to the Query server.

Parameters:pack (QUERYPacket) – Packet to send
start()

Sets the protocol object as ready to communicate.

stop()

Sets the protocol object as not ready to communicate.

class mctools.protocol.RCONProtocol(host, port, timeout)

Protocol implementation fot RCON - Uses TCP sockets.

Parameters:
  • host (str) – Hostname of RCON server
  • port (int) – Port number of the RCON server
  • timeout (int) – Timeout value for socket operations.
read()

Gets a RCON packet from the RCON server.

Parameters:timeout (int, None) – Timeout value specific to this operation.
Returns:RCONPacket containing payload
Return type:RCONPacket
send(pack, length_check=False)

Sends a packet to the RCON server.

Parameters:
  • pack (RCONPacket) – RCON Packet
  • length_check (bool) – Boolean determining if we should check packet length

New in version 1.1.2.

The ‘length_check’ parameter

start()

Starts the connection to the RCON server.

stop()

Stops the connection to the RCON server.

Formatting Tools Reference

Formatters to alter response output - makes everything look pretty

class mctools.formattertools.BaseFormatter

Parent class for formatter implementations.

static clean(text)

Removes format chars, instead of replacing them with actual values. Great for if the user does not want/have color support, And wants to remove the unneeded format chars.

Parameters:text (str) – Text to be formatted
Returns:Formatted text
Return type:str
static format(text)

Formats text in any way fit. Note: This should not remove format chars, that’s what remove is for, Simply replace them with their required values.

Parameters:text (str) – Text to be formatted
Returns:Formatted text
Return type:str
static get_id()

Should return an integer representing the formatter ID. This is important, as it determines how the formatters are sorted. Sorting goes from least - greatest, meaning that formatters with a lower ID get executed first.

Returns:Formatter ID
Return type:int
class mctools.formattertools.ChatObjectFormatter

A formatter that handles the formatting scheme of ChatObjects. This description scheme differs from primitive chat objects, as it doesn’t use formatting characters. It instead uses a collection of dictionaries to define what colors and attributes should be used.

static clean(text)

Cleans a description directory, and returns the cleaned text.

Parameters:text (dict) – Dictonary to be formatted
Returns:Cleaned text
Return type:str
static format(chat, color=None, attrib=None)

Formats a description dictionary, and returns the formatted text. This gets tricky, as the server could define a variable number of child dicts that have their own attributes/extra content. So, we must implement some recursion to be able to parse and understand the entire string.

Parameters:
  • chat (dict) – Dictionary to be formatted
  • color (str) – Parent text color, only used in recursive operations
  • attrib (str) – Parent attributes, only used in recursive operations
Returns:

Formatted text
Return type:

str
class mctools.formattertools.DefaultFormatter
Formatter with good default operation:
  • format() - Replaces all formatter codes with ascii values
  • clean() - Removes all formatter codes

This formatter ONLY handles formatting codes and text attributes.

static clean(text)

Removes all format codes. Does not use color/text effects.

Parameters:text (str) – Text to be formatted.
Returns:Formatted text.
Return type:str
static format(text)

Replaces all format codes with their intended values (Color, text effect, ect).

Parameters:text (str) – Text to be formatted.
Returns:Formatted text.
Return type:str
static get_id()

Returns this formatters ID, which is 10.

Returns:Formatter ID
Return type:int
class mctools.formattertools.FormatterCollection

A collection of formatters - Allows for formatting text with multiple formatters, and determining which formatter is relevant to the text.

This class offers the following constants:

  • FormatterCollection.QUERY - Used for identifying Query protocol content.
  • FormatterCollection.PING - Used for identifying Server List Ping protocol content.
add(form, command, ignore=None)

Adds a formatter, MUST inherit the BaseFormatter class. Your formatter must either be instantiated upon adding it, or the ‘clean’ and ‘format’ methods are static, as FormatterCollection will not attempt to instantiate your object.

Parameters:
  • form – Formatter to add.
  • command (str, list) – Command(s) to register the formatter with. May be a string or list. Supply an empty string(‘’) to affiliate with every command, or a list to affiliate with multiple.
  • ignore (str, list) – Commands to ignore, formatter will not format them, leave blank to accept everything. May be string or list. Supply ‘None’ to allow all commands, or a list to affiliate with multiple.
Returns:

True for success, False for Failure.
Return type:

bool
clean(text, command)

Runs the text through the clean() method of every formatter. These formatters will remove characters, without replacing them, Most likely format chars. We only send non-string data to specific formatters.

Parameters:
  • text (str) – Text to be formatted.
  • command (str) – Command issued - determines which formatters are relevant. You may leave command blank to affiliate with every formatter.
Returns:

Formatted text.
Return type:

str
clear()

Removes all formatters from the list.

format(text, command)

Runs the text through the format() function of relevant fomatters. These formatters will be removing and replacing characters, Most likely format chars.

Parameters:
  • text (str) – Text to be formatted
  • command (str) – Command issued - determines which formatters are relevant. You may leave command blank to affiliate with every formatter.
Returns:

Formatted text.
Return type:

str
get()

Returns the list of formatters. Can be used to check loaded formatters, or manually edit list. Be aware, that manually editing the list means that the formatters may have some unstable operations.

Returns:List of formatters.
Return type:list
remove(form)

Removes a specified formatter from the list.

Parameters:form (BaseFormatter) – Formatter to remove
Returns:True on success, False on failure
Return type:bool
class mctools.formattertools.PINGFormatter

Formatter for formatting responses from the server via Server List Ping protocol. We only format relevant content, such as description and player names. We also use special formatters, such as ChatObjectFormatter, and SampleDescriptionFormatter.

static clean(stat_dict)

Cleaned a dictionary of stats from the Minecraft server.

Parameters:stat_dict (dict) – Dictionary to format
Returns:Formatted statistics dictionary.
Return type:dict
static format(stat_dict)

Formats a dictionary of stats from the Minecraft server.

Parameters:stat_dict (dict) – Dictionary to format
Returns:Formatted statistics dictionary.
Return type:dict
class mctools.formattertools.QUERYFormatter

Formatter for formatting responses from the Query server. Will only format certain parts, as servers SHOULD follow a specific implementation for Query.

static clean(text)

Removes format chars from the response.

Parameters:text (dict) – Response from Query server
Returns:Formatted content.
Return type:dict
static format(text)

Replaces format chars with actual values.

Parameters:text (dict) – Response from Query server(Ideally in dict form).
Returns:Formatted content.
Return type:dict
class mctools.formattertools.SampleDescriptionFormatter

Some servers like to put special messages in the ‘sample players’ field. This formatter attempts to handle this, and sort valid players and null players into separate categories.

static clean(text)

Does the same operation as format. This is okay because we don’t change up any values or alter the content, we just organise them, and the color formatter will handle it later.

Parameters:text (list, str) – Valid players, Message encoded in the sample list
Returns:Dictionary containing message, and valid users.
static format(text)

Formats a sample list of users, removing invalid ones and adding them to a message sublist. We return the message in the playerlist, and also return valid players.

Parameters:text (list, str) – Valid players, Message encoded in the sample list
Returns:Dictionary containing message, and valid users.