12. API - Connections and Batches¶
The connection module defines the Connection
class, which represents
the network connection to the Minecraft server. Its primary purpose for users
of the library is to initiate batch sending via the
Connection.batch_start()
method.
Note
All items in this module are available from the picraft
namespace
without having to import picraft.connection
directly.
The following items are defined in the module:
12.1. Connection¶
-
class
picraft.connection.
Connection
(host, port, timeout=0.2, ignore_errors=False, encoding=u'ascii')[source]¶ Represents the connection to the Minecraft server.
The host parameter specifies the hostname or IP address of the Minecraft server, while port specifies the port to connect to (these typically take the values “127.0.0.1” and 4711 respectively).
The timeout parameter specifies the maximum time that the client will wait after sending a command before assuming that the command has succeeded (see the The Minecraft network protocol section for more information). If ignore_errors is
True
, act like the official reference implementation and ignore all errors for commands which do not return data.Users will rarely need to construct a
Connection
object themselves. An instance of this class is constructed byWorld
to handle communication with the game server (connection
).The most important aspect of this class is its ability to “batch” transmissions together. Typically, the
send()
method is used to transmit requests to the Minecraft server. When this is called normally (outside of a batch), it immediately transmits the requested data. However, ifbatch_start()
has been called first, the data is not sent immediately, but merely appended to the batch. Thebatch_send()
method can then be used to transmit all requests simultaneously (or alternatively,batch_forget()
can be used to discard the list). See the docs of these methods for more information.-
ignore_errors
¶ If
False
(the default), use thetimeout
to determine when responses have been successful. IfTrue
assume any response without an expected reply is successful (this is the behaviour of the reference implementation; it is faster but less “safe”).
-
timeout
¶ The length of time in seconds to wait for a response (positive or negative) from the server when
ignore_errors
isFalse
.
-
encoding
¶ The encoding that will be used for messages transmitted to, and received from the server. Defaults to
'ascii'
.
-
batch_forget
()[source]¶ Terminates a batch transmission without sending anything.
This method is called after
batch_start()
andsend()
have been used to build up a list of batch commands. All commands in the batch will be cleared without sending anything to the server.If no batch is currently in progress, a
BatchNotStarted
exception will be raised.
-
batch_send
()[source]¶ Sends the batch transmission.
This method is called after
batch_start()
andsend()
have been used to build up a list of batch commands. All the commands will be combined and sent to the server as a single transmission.If no batch is currently in progress, a
BatchNotStarted
exception will be raised.
-
batch_start
()[source]¶ Starts a new batch transmission.
When called, this method starts a new batch transmission. All subsequent calls to
send()
will append data to the batch buffer instead of actually sending the data.To terminate the batch transmission, call
batch_send()
orbatch_forget()
. If a batch has already been started, aBatchStarted
exception is raised.Note
This method can be used as a context manager (the-with-statement) which will cause a batch to be started, and implicitly terminated with
batch_send()
orbatch_forget()
depending on whether an exception is raised within the enclosed block.
-
close
()[source]¶ Closes the connection.
This method can be used to close down the connection to the game server. It is typically called from
close()
rather than being called directly.
-
send
(buf)[source]¶ Transmits the contents of buf to the connected server.
If no batch has been initiated (with
batch_start()
), this method immediately communicates the contents of buf to the connected Minecraft server. If buf is a unicode string, the method attempts to encode the content in a byte-encoding prior to transmission (the encoding used is theencoding
attribute of the class which defaults to “ascii”).If a batch has been initiated, the contents of buf are appended to the latest batch that was started (batches can be nested; see
batch_start()
for more information).
-
transact
(buf)[source]¶ Transmits the contents of buf, and returns the reply string.
This method immediately communicates the contents of buf to the connected server, then reads a line of data in reply and returns it.
Note
This method ignores the batch mechanism entirely as transmission is required in order to obtain the response. As this method is typically used to implement “getters”, this is not usually an issue but it is worth bearing in mind.
-
server_version
¶ Returns an object (currently just a string) representing the version of the Minecraft server we’re talking to. Presently this is just
'minecraft-pi'
or'raspberry-juice'
.
-