Protocol documentation

This is the documentation for components related to interactions with the minecraft protocol and connection establishing.

mcproto.protocol.base_io.BaseAsyncReader

Bases: ABC

Base class holding asynchronous read buffer/connection interactions.

mcproto.protocol.base_io.BaseAsyncReader._read_varuint async

_read_varuint(*, max_bits: int | None = None) -> int

Read an arbitrarily big unsigned integer in a variable length format.

This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.

Reading will be limited up to integer values of max_bits bits, and trying to read bigger values will raise an IOError. Note that setting max_bits to for example 32 bits doesn't mean that at most 4 bytes will be read, in this case we would actually read at most 5 bytes, due to the variable encoding overhead.

Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.

mcproto.protocol.base_io.BaseAsyncReader.read abstractmethod async

read(length: int) -> bytes

Underlying read method, obtaining the raw data.

All of the reader functions will eventually call this method.

mcproto.protocol.base_io.BaseAsyncReader.read_ascii async

read_ascii() -> str

Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.

mcproto.protocol.base_io.BaseAsyncReader.read_bytearray async

read_bytearray() -> bytes

Read an arbitrary sequence of bytes, prefixed with a varint of it's size.

mcproto.protocol.base_io.BaseAsyncReader.read_optional async

read_optional(reader: Callable[[], Awaitable[R]]) -> R | None

Read a bool showing if a value is present, if so, also reads this value with reader function.

• When False is read, the function will not read anything and None is returned.
• When True is read, the reader function is called, and it's return value is forwarded.

mcproto.protocol.base_io.BaseAsyncReader.read_utf async

read_utf() -> str

Read a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).

The maximum amount of UTF-8 characters is limited to 32767.

Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be read + 3 additional bytes from the varint encoding overhead.

Raises:

Type

Description

IOError

If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all, and IOError will be raised immediately. If the received string has more than the maximum amount of characters (32767). Note that in this case, the string will still get read in it's entirety, since it fits into the maximum bytes limit (131068), which was simply read at once. This limitation is here only to replicate the behavior of minecraft's implementation.

mcproto.protocol.base_io.BaseAsyncReader.read_value async

read_value(fmt: INT_FORMATS_TYPE) -> int

read_value(fmt: FLOAT_FORMATS_TYPE) -> float

read_value(fmt: Literal[BOOL]) -> bool

read_value(fmt: Literal[CHAR]) -> str

read_value(fmt: StructFormat) -> object

Read a value as given struct format (fmt) in big-endian mode.

The amount of bytes to read will be determined based on the struct format automatically.

mcproto.protocol.base_io.BaseAsyncReader.read_varint async

read_varint() -> int

Read a 32-bit signed integer in a variable length format.

For more information about variable length format check _read_varuint.

mcproto.protocol.base_io.BaseAsyncReader.read_varlong async

read_varlong() -> int

Read a 64-bit signed integer in a variable length format.

For more information about variable length format check _read_varuint.

mcproto.protocol.base_io.BaseAsyncWriter

Bases: ABC

Base class holding asynchronous write buffer/connection interactions.

mcproto.protocol.base_io.BaseAsyncWriter._write_varuint async

_write_varuint(value: int, /, *, max_bits: int | None = None) -> None

Write an arbitrarily big unsigned integer in a variable length format.

This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.

Writing will be limited up to integer values of max_bits bits, and trying to write bigger values will raise a ValueError. Note that setting max_bits to for example 32 bits doesn't mean that at most 4 bytes will be sent, in this case it would actually take at most 5 bytes, due to the variable encoding overhead.

Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.

mcproto.protocol.base_io.BaseAsyncWriter.write abstractmethod async

write(data: bytes | bytearray) -> None

Underlying write method, sending/storing the data.

All of the writer functions will eventually call this method.

mcproto.protocol.base_io.BaseAsyncWriter.write_ascii async

write_ascii(value: str) -> None

Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.

mcproto.protocol.base_io.BaseAsyncWriter.write_bytearray async

write_bytearray(data: bytes | bytearray) -> None

Write an arbitrary sequence of bytes, prefixed with a varint of it's size.

mcproto.protocol.base_io.BaseAsyncWriter.write_optional async

write_optional(value: T | None, /, writer: Callable[[T], Awaitable[R]]) -> R | None

Write a bool showing if a value is present, if so, also writes this value with writer function.

• When value is None, a bool of False will be written, and None is returned.
• When value is not None, a bool of True is written, after which the writer function is called, and the return value is forwarded.

mcproto.protocol.base_io.BaseAsyncWriter.write_utf async

write_utf(value: str) -> None

Write a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).

The maximum amount of UTF-8 characters is limited to 32767.

Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be written + 3 additional bytes from the varint encoding overhead.

Raises:

Type	Description
ValueError	If the given string value has more characters than the allowed maximum (32767).

mcproto.protocol.base_io.BaseAsyncWriter.write_value async

write_value(fmt: INT_FORMATS_TYPE, value: int) -> None

write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -> None

write_value(fmt: Literal[BOOL], value: bool) -> None

write_value(fmt: Literal[CHAR], value: str) -> None

write_value(fmt: StructFormat, value: object) -> None

Write a given value as given struct format (fmt) in big-endian mode.

mcproto.protocol.base_io.BaseAsyncWriter.write_varint async

write_varint(value: int) -> None

Write a 32-bit signed integer in a variable length format.

For more information about variable length format check _write_varuint.

mcproto.protocol.base_io.BaseAsyncWriter.write_varlong async

write_varlong(value: int) -> None

Write a 64-bit signed integer in a variable length format.

For more information about variable length format check _write_varuint.

mcproto.protocol.base_io.BaseSyncReader

Bases: ABC

Base class holding synchronous read buffer/connection interactions.

mcproto.protocol.base_io.BaseSyncReader._read_varuint

_read_varuint(*, max_bits: int | None = None) -> int

Read an arbitrarily big unsigned integer in a variable length format.

This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.

Reading will be limited up to integer values of max_bits bits, and trying to read bigger values will raise an IOError. Note that setting max_bits to for example 32 bits doesn't mean that at most 4 bytes will be read, in this case we would actually read at most 5 bytes, due to the variable encoding overhead.

Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.

mcproto.protocol.base_io.BaseSyncReader.read abstractmethod

read(length: int) -> bytes

Underlying read method, obtaining the raw data.

All of the reader functions will eventually call this method.

mcproto.protocol.base_io.BaseSyncReader.read_ascii

read_ascii() -> str

Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.

mcproto.protocol.base_io.BaseSyncReader.read_bytearray

read_bytearray() -> bytes

Read an arbitrary sequence of bytes, prefixed with a varint of it's size.

mcproto.protocol.base_io.BaseSyncReader.read_optional

read_optional(reader: Callable[[], R]) -> R | None

Read a bool showing if a value is present, if so, also reads this value with reader function.

• When False is read, the function will not read anything and None is returned.
• When True is read, the reader function is called, and it's return value is forwarded.

mcproto.protocol.base_io.BaseSyncReader.read_utf

read_utf() -> str

Read a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).

The maximum amount of UTF-8 characters is limited to 32767.

Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be read + 3 additional bytes from the varint encoding overhead.

Raises:

Type

Description

IOError

If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all, and IOError will be raised immediately. If the received string has more than the maximum amount of characters (32767). Note that in this case, the string will still get read in it's entirety, since it fits into the maximum bytes limit (131068), which was simply read at once. This limitation is here only to replicate the behavior of minecraft's implementation.

mcproto.protocol.base_io.BaseSyncReader.read_value

read_value(fmt: INT_FORMATS_TYPE) -> int

read_value(fmt: FLOAT_FORMATS_TYPE) -> float

read_value(fmt: Literal[BOOL]) -> bool

read_value(fmt: Literal[CHAR]) -> str

read_value(fmt: StructFormat) -> object

Read a value into given struct format in big-endian mode.

The amount of bytes to read will be determined based on the struct format automatically.

mcproto.protocol.base_io.BaseSyncReader.read_varint

read_varint() -> int

Read a 32-bit signed integer in a variable length format.

For more information about variable length format check _read_varuint.

mcproto.protocol.base_io.BaseSyncReader.read_varlong

read_varlong() -> int

Read a 64-bit signed integer in a variable length format.

For more information about variable length format check _read_varuint.

mcproto.protocol.base_io.BaseSyncWriter

Bases: ABC

Base class holding synchronous write buffer/connection interactions.

mcproto.protocol.base_io.BaseSyncWriter._write_varuint

_write_varuint(value: int, /, *, max_bits: int | None = None) -> None

Write an arbitrarily big unsigned integer in a variable length format.

This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.

Writing will be limited up to integer values of max_bits bits, and trying to write bigger values will raise a ValueError. Note that setting max_bits to for example 32 bits doesn't mean that at most 4 bytes will be sent, in this case it would actually take at most 5 bytes, due to the variable encoding overhead.

Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.

mcproto.protocol.base_io.BaseSyncWriter.write abstractmethod

write(data: bytes | bytearray) -> None

Underlying write method, sending/storing the data.

All of the writer functions will eventually call this method.

mcproto.protocol.base_io.BaseSyncWriter.write_ascii

write_ascii(value: str) -> None

Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.

mcproto.protocol.base_io.BaseSyncWriter.write_bytearray

write_bytearray(data: bytes | bytearray) -> None

Write an arbitrary sequence of bytes, prefixed with a varint of it's size.

mcproto.protocol.base_io.BaseSyncWriter.write_optional

write_optional(value: T | None, /, writer: Callable[[T], R]) -> R | None

Write a bool showing if a value is present, if so, also writes this value with writer function.

• When value is None, a bool of False will be written, and None is returned.
• When value is not None, a bool of True is written, after which the writer function is called, and the return value is forwarded.

mcproto.protocol.base_io.BaseSyncWriter.write_utf

write_utf(value: str) -> None

Write a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).

The maximum amount of UTF-8 characters is limited to 32767.

Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be written + 3 additional bytes from the varint encoding overhead.

Raises:

Type	Description
ValueError	If the given string value has more characters than the allowed maximum (32767).

mcproto.protocol.base_io.BaseSyncWriter.write_value

write_value(fmt: INT_FORMATS_TYPE, value: int) -> None

write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -> None

write_value(fmt: Literal[BOOL], value: bool) -> None

write_value(fmt: Literal[CHAR], value: str) -> None

write_value(fmt: StructFormat, value: object) -> None

Write a given value as given struct format (fmt) in big-endian mode.

mcproto.protocol.base_io.BaseSyncWriter.write_varint

write_varint(value: int) -> None

Write a 32-bit signed integer in a variable length format.

For more information about variable length format check _write_varuint.

mcproto.protocol.base_io.BaseSyncWriter.write_varlong

write_varlong(value: int) -> None

Write a 64-bit signed integer in a variable length format.

For more information about variable length format check _write_varuint.

mcproto.protocol.base_io.StructFormat

Bases: str, Enum

All possible write/read struct types.

See Also

struct module documentation.

mcproto.buffer.Buffer

Bases: BaseSyncWriter, BaseSyncReader, bytearray

In-memory bytearray-like buffer supporting the common read/write operations.

mcproto.buffer.Buffer.remaining property

remaining: int

Get the amount of bytes that's still remaining in the buffer to be read.

mcproto.buffer.Buffer.clear

clear(only_already_read: bool = False) -> None

Clear out the stored data and reset position.

Parameters:

Name	Type	Description	Default
only_already_read	bool	When set to True, only the data that was already marked as read will be cleared, and the position will be reset (to start at the remaining data). This can be useful for avoiding needlessly storing large amounts of data in memory, if this data is no longer useful. Otherwise, if set to False, all of the data is cleared, and the position is reset, essentially resulting in a blank buffer.	False

mcproto.buffer.Buffer.flush

flush() -> bytes

Read all of the remaining data in the buffer and clear it out.

mcproto.buffer.Buffer.read

read(length: int) -> bytes

Read data stored in the buffer.

Reading data doesn't remove that data, rather that data is treated as already read, and next read will start from the first unread byte. If freeing the data is necessary, check the clear function.

Parameters:

Name	Type	Description	Default
length	int	Amount of bytes to be read. If the requested amount can't be read (buffer doesn't contain that much data/buffer doesn't contain any data), an IOError will be reaised. If there were some data in the buffer, but it was less than requested, this remaining data will still be depleted and the partial data that was read will be a part of the error message in the IOError. This behavior is here to mimic reading from a real socket connection.	required

mcproto.buffer.Buffer.reset

reset() -> None

Reset the position in the buffer.

Since the buffer doesn't automatically clear the already read data, it is possible to simply reset the position and read the data it contains again.

mcproto.buffer.Buffer.write

write(data: bytes | bytearray) -> None

Write/Store given data into the buffer.

mcproto.connection.AsyncConnection

Bases: BaseAsyncReader, BaseAsyncWriter, ABC

Base class for all classes handling asynchronous connections.

mcproto.connection.AsyncConnection._close abstractmethod async

_close() -> None

Close the underlying connection.

mcproto.connection.AsyncConnection._read abstractmethod async

_read(length: int) -> bytes

Receive raw data from this specific connection.

Parameters:

Name	Type	Description	Default
length	int	Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an IOError will be raised.	required

mcproto.connection.AsyncConnection._write abstractmethod async

_write(data: bytes) -> None

Send raw data through this specific connection.

mcproto.connection.AsyncConnection.close async

close() -> None

Close the connection (it cannot be used after this).

mcproto.connection.AsyncConnection.enable_encryption

enable_encryption(shared_secret: bytes) -> None

Enable encryption for this connection, using the shared_secret.

After calling this method, the reading and writing process for this connection will be altered, and any future communication will be encrypted/decrypted there.

You will need to call this method after sending the LoginEncryptionResponse packet.

Parameters:

Name	Type	Description	Default
shared_secret	bytes	This is the cipher key for the AES symetric cipher used for the encryption. See generate_shared_secret.	required

mcproto.connection.AsyncConnection.make_client abstractmethod async classmethod

make_client(address: tuple[str, int], timeout: float) -> Self

Construct a client connection (Client -> Server) to given server address.

Parameters:

Name	Type	Description	Default
address	tuple[str, int]	Address of the server to connection to.	required
timeout	float	Amount of seconds to wait for the connection to be established. If a connection can't be established within this time, TimeoutError will be raised. This timeout is then also used for any further data receiving.	required

mcproto.connection.AsyncConnection.read async

read(length: int) -> bytes

Receive data sent through the connection.

Depending on encryption_enabled flag (set from enable_encryption), this might also perform a decryption of the received data.

Parameters:

Name	Type	Description	Default
length	int	Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an IOError will be raised.	required

mcproto.connection.AsyncConnection.write async

write(data: bytes | bytearray) -> None

Send given data over the connection.

Depending on encryption_enabled flag (set from enable_encryption), this might also perform an encryption of the input data.

mcproto.connection.SyncConnection

Bases: BaseSyncReader, BaseSyncWriter, ABC

Base class for all classes handling synchronous connections.

mcproto.connection.SyncConnection._close abstractmethod

_close() -> None

Close the underlying connection.

mcproto.connection.SyncConnection._read abstractmethod

_read(length: int) -> bytes

Receive raw data from this specific connection.

Parameters:

Name	Type	Description	Default
length	int	Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an IOError will be raised.	required

mcproto.connection.SyncConnection._write abstractmethod

_write(data: bytes) -> None

Send raw data through this specific connection.

mcproto.connection.SyncConnection.close

close() -> None

Close the connection (it cannot be used after this).

mcproto.connection.SyncConnection.enable_encryption

enable_encryption(shared_secret: bytes) -> None

Enable encryption for this connection, using the shared_secret.

After calling this method, the reading and writing process for this connection will be altered, and any future communication will be encrypted/decrypted there.

You will need to call this method after sending the LoginEncryptionResponse packet.

Parameters:

Name	Type	Description	Default
shared_secret	bytes	This is the cipher key for the AES symetric cipher used for the encryption. See generate_shared_secret.	required

mcproto.connection.SyncConnection.make_client abstractmethod classmethod

make_client(address: tuple[str, int], timeout: float) -> Self

Construct a client connection (Client -> Server) to given server address.

Parameters:

Name	Type	Description	Default
address	tuple[str, int]	Address of the server to connection to.	required
timeout	float	Amount of seconds to wait for the connection to be established. If a connection can't be established within this time, TimeoutError will be raised. This timeout is then also used for any further data receiving.	required

mcproto.connection.SyncConnection.read

read(length: int) -> bytes

Receive data sent through the connection.

Depending on encryption_enabled flag (set from enable_encryption), this might also perform a decryption of the received data.

Parameters:

Name	Type	Description	Default
length	int	Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an IOError will be raised.	required

mcproto.connection.SyncConnection.write

write(data: bytes | bytearray) -> None

Send given data over the connection.

Depending on encryption_enabled flag (set from enable_encryption), this might also perform an encryption of the input data.

mcproto.connection.TCPAsyncConnection

Bases: AsyncConnection, Generic[T_STREAMREADER, T_STREAMWRITER]

Asynchronous TCP connection using StreamWriter and StreamReader.

mcproto.connection.TCPAsyncConnection.socket property

socket: socket

Obtain the underlying socket behind the Transport.

mcproto.connection.TCPSyncConnection

Bases: SyncConnection, Generic[T_SOCK]

Synchronous connection using a TCP socket.

mcproto.connection.UDPAsyncConnection

Bases: AsyncConnection, Generic[T_DATAGRAM_CLIENT]

Asynchronous UDP connection using asyncio_dgram.DatagramClient.

mcproto.connection.UDPSyncConnection

Bases: SyncConnection, Generic[T_SOCK]

Synchronous connection using a UDP socket.