Protocol documentation¶
This is the documentation for components related to interactions with the minecraft protocol and connection establishing.
Bases: ABC
Base class holding asynchronous read buffer/connection interactions.
abstractmethod
async
¶
Underlying read method, obtaining the raw data.
All of the reader functions will eventually call this method.
async
¶
read_ascii() -> str
Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.
async
¶
read_bytearray() -> bytes
Read an arbitrary sequence of bytes, prefixed with a varint of it's size.
async
¶
Read a bool showing if a value is present, if so, also reads this value with reader function.
- When
Falseis read, the function will not read anything andNoneis returned. - When
Trueis read, thereaderfunction is called, and it's return value is forwarded.
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 IOError:
* If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all,
and :exc: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.
async
¶
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.
Bases: ABC
Base class holding asynchronous write buffer/connection interactions.
abstractmethod
async
¶
Underlying write method, sending/storing the data.
All of the writer functions will eventually call this method.
async
¶
write_ascii(value: str) -> None
Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.
async
¶
Write an arbitrary sequence of bytes, prefixed with a varint of it's size.
async
¶
Write a bool showing if a value is present, if so, also writes this value with writer function.
- When
valueisNone, a bool ofFalsewill be written, andNoneis returned. - When
valueis notNone, a bool ofTrueis written, after which thewriterfunction is called, and the return value is forwarded.
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 ValueError:
If the given string value has more characters than the allowed maximum (32767).
async
¶
write_value(fmt: INT_FORMATS_TYPE, value: int) -> None
write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -> None
write_value(fmt: StructFormat, value: object) -> None
Write a given value as given struct format (fmt) in big-endian mode.
Bases: ABC
Base class holding synchronous read buffer/connection interactions.
abstractmethod
¶
Underlying read method, obtaining the raw data.
All of the reader functions will eventually call this method.
read_ascii() -> str
Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.
read_bytearray() -> bytes
Read an arbitrary sequence of bytes, prefixed with a varint of it's size.
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
Falseis read, the function will not read anything andNoneis returned. - When
Trueis read, thereaderfunction is called, and it's return value is forwarded.
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 IOError:
* If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all,
and :exc: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.
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.
Bases: ABC
Base class holding synchronous write buffer/connection interactions.
abstractmethod
¶
Underlying write method, sending/storing the data.
All of the writer functions will eventually call this method.
write_ascii(value: str) -> None
Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.
Write an arbitrary sequence of bytes, prefixed with a varint of it's size.
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
valueisNone, a bool ofFalsewill be written, andNoneis returned. - When
valueis notNone, a bool ofTrueis written, after which thewriterfunction is called, and the return value is forwarded.
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 ValueError:
If the given string value has more characters than the allowed maximum (32767).
write_value(fmt: INT_FORMATS_TYPE, value: int) -> None
write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -> None
write_value(fmt: StructFormat, value: object) -> None
Write a given value as given struct format (fmt) in big-endian mode.
Bases: BaseSyncWriter, BaseSyncReader, bytearray
In-memory bytearray-like buffer supporting the common read/write operations.
property
¶
remaining: int
Get the amount of bytes that's still remaining in the buffer to be read.
clear(only_already_read: bool = False) -> None
Clear out the stored data and reset position.
:param only_already_read:
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.
flush() -> bytes
Read all of the remaining data in the buffer and clear it out.
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 :meth:.clear function.
:param length: 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 :exc:`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 :exc:`IOError`. This behavior is here to mimic reading from a real
socket connection.
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.
Bases: BaseAsyncReader, BaseAsyncWriter, ABC
Base class for all classes handling asynchronous connections.
async
¶
Close the connection (it cannot be used after this).
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
:class:~mcproto.packets.login.login.LoginEncryptionResponse packet.
:param shared_secret: This is the cipher key for the AES symetric cipher used for the encryption.
See :func:`mcproto.encryption.generate_shared_secret`.
abstractmethod
async
classmethod
¶
Construct a client connection (Client -> Server) to given server address.
:param address: Address of the server to connection to.
:param timeout:
Amount of seconds to wait for the connection to be established.
If connection can't be established within this time, :exc:TimeoutError will be raised.
This timeout is then also used for any further data receiving.
async
¶
Receive data sent through the connection.
Depending on :attr:encryption_enabled flag (set from :meth:enable_encryption),
this might also perform a decryption of the received data.
:param length:
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 :exc:IOError
will be raised.
Bases: BaseSyncReader, BaseSyncWriter, ABC
Base class for all classes handling synchronous connections.
Close the connection (it cannot be used after this).
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
:class:~mcproto.packets.login.login.LoginEncryptionResponse packet.
:param shared_secret: This is the cipher key for the AES symetric cipher used for the encryption.
See :func:`mcproto.encryption.generate_shared_secret`.
abstractmethod
classmethod
¶
Construct a client connection (Client -> Server) to given server address.
:param address: Address of the server to connection to.
:param timeout:
Amount of seconds to wait for the connection to be established.
If connection can't be established within this time, :exc:TimeoutError will be raised.
This timeout is then also used for any further data receiving.
Receive data sent through the connection.
Depending on :attr:encryption_enabled flag (set from :meth:enable_encryption),
this might also perform a decryption of the received data.
:param length:
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 :exc:IOError
will be raised.
Bases: AsyncConnection, Generic[T_STREAMREADER, T_STREAMWRITER]
Asynchronous TCP connection using :class:~asyncio.StreamWriter and :class:~asyncio.StreamReader.
property
¶
Obtain the underlying socket behind the :class:~asyncio.Transport.
Bases: AsyncConnection, Generic[T_DATAGRAM_CLIENT]
Asynchronous UDP connection using :class:~asyncio_dgram.DatagramClient.