Skip to content

Commit

Permalink
Add many new docstrings; make documentation use Sphinx's autodoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@barneygale
barneygale committed Oct 10, 2015
1 parent 9c9ef6f commit cad47ed
Show file tree
Hide file tree
Showing 8 changed files with 139 additions and 210 deletions.
1 change: 1 addition & 0 deletions CHANGES.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ master

- Renamed ``quarry.util`` to `quarry.utils``
- Removed ``protocol_mode`` parameter from some proxy callbacks
- Added many new docstrings; made documentation use Sphinx's ``autodoc``

v0.2.3
------
Expand Down
75 changes: 8 additions & 67 deletions docs/sending_and_receiving_packets.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,23 @@ Receiving a Packet
------------------

To receive a packet, implement a method in your subclass of
:class:`ClientProtocol` or :class:`ServerProtocol` with a name like
:class:`~quarry.net.client.ClientProtocol` or
:class:`~quarry.net.server.ServerProtocol` with a name like
``packet_<packet name>``::

def packet_update_health(self, buff):
health = buff.unpack('f')
food = buff.unpack_varint()
saturation = buff.unpack('f')

You are passed a :class:`Buffer` instance, which contains the payload of the
packet. If you hook a packet, you should ensure you read the entire payload.
You are passed a :class:`~quarry.utils.buffer.Buffer` instance, which contains
the payload of the packet. If you hook a packet, you should ensure you read the
entire payload.

Sending a Packet
----------------

Call :meth:`Protocol.send_packet` to send a packet::
Call :meth:`~quarry.net.protocol.Protocol.send_packet` to send a packet::

def packet_keep_alive(self, buff):
# Read the keep alive ID
Expand All @@ -36,66 +38,5 @@ to this class is available as ``self.buff_type``.
Buffer Methods
--------------

.. class:: Buffer

.. method:: discard(self):

Discard the entire buffer.

.. method:: read(self, length=None)

Read *length* bytes from the buffer, or all bytes if *length* is
``None``.

.. method:: unpack(self, fmt)

Unpack a struct from the buffer. The format accepted is the same as
for ``struct.unpack()``.

.. method:: unpack_string(self)

Unpack a Minecraft string (varint-prefixed utf8) from the buffer.

.. method:: unpack_json(self)

Unpack a Minecraft string and interpret it as JSON.

.. method:: unpack_chat(self)

Unpack a Minecraft chat message. Minecraft uses a JSON format to
send chat messages; this method retrieves a plaintext representation
with colours and styles stripped.

.. method:: unpack_varint(self)

Unpacks a VarInt from the buffer.

.. method:: unpack_uuid(self)

Unpacks a UUID from the buffer.

.. method:: pack(cls, fmt, *data)

Pack *data* into a struct. The format accepted is the same as for
``struct.pack()``.

.. method:: pack_string(cls, text)

Pack a Minecraft string (varint-prefixed utf8).

.. method:: pack_json(cls, obj)

Dump an object to JSON and pack it to a Minecraft string.

.. method:: pack_chat(cls, text)

Pack a Minecraft chat message. This method accepts plaintext; to send
colours and other formatting use :meth:`pack_json`.

.. method:: pack_varint(cls, number)

Packs a VarInt.

.. method:: pack_uuid(cls, uuid)

Packs a UUID.
.. autoclass:: quarry.utils.buffer.Buffer
:members:
75 changes: 6 additions & 69 deletions docs/writing_a_client.rst
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
Writing a Client
================

.. module:: quarry.net.client

Skeleton client
---------------

Expand Down Expand Up @@ -59,74 +61,9 @@ API Reference
Quarry's default packet handlers call certain methods when events occur. You
might want to call ``super()`` for these methods if you reimplement them.

.. class:: ClientProtocol()

.. attribute:: buff_type

A reference to the :class:`Buffer` class. This is useful when
constructing a packet payload for use in :meth:`send_packet`.

.. attribute:: logger

A reference to the logger.

.. attribute:: tasks

A reference to a :class:`Tasks` instance. This object has methods for
setting up repeating or delayed callbacks.

.. attribute:: remote_addr

The remote endpoint's address. Use ``.host`` and ``.port`` to retrieve
the IP address and port.

.. method:: connection_made(self)

Called when the connection is made.

.. method:: connection_lost(self)

Called when the connection is lost.

.. method:: packet_received(self, name, buff)

Called when a packet is received from the remote. Usually this method
dispatches the packet to a method named ``packet_<packet name>``, or
calls :meth:`packet_unhandled` if no such methods exists. You might
want to override this to implement your own dispatch logic or logging.

.. method:: packet_unhandled(self, name, buff)

Called when a packet is received that is not hooked. The default
implementation silently discards the packet.

.. method:: send_packet(self, name, data=b"")

Call this to send a packet to the remote.

.. method:: player_joined(self):

Called when we join the game. If the server is in online mode, this
means the server accepted our session.

.. method:: player_left(self):

Called when we leave the game.

.. method:: auth_ok(self, data):

Called if the Mojang session server responds to our query. Note that
this method does not indicate that the server accepted our session; in
this case :meth:`player_joined` is called.

.. method:: auth_failed(self, err):

Called if the Mojang session server does not respond to our auth query
or responds with an error.

.. method:: status_response(self, data):

If we're connecting in "status" mode, this is called when the server
sends us information about itself.
.. autoclass:: ClientProtocol
:members:
:inherited-members:
:exclude-members: makeConnection, logPrefix

.. _twisted: https://twistedmatrix.com
71 changes: 4 additions & 67 deletions docs/writing_a_server.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,70 +18,7 @@ To write a server, subclass :class:`ServerFactory` and

API Reference
-------------

.. class:: ServerProtocol()

.. attribute:: buff_type

A reference to the :class:`Buffer` class. This is useful when
constructing a packet payload for use in :meth:`send_packet`.

.. attribute:: logger

A reference to the logger.

.. attribute:: tasks

A reference to a :class:`Tasks` instance. This object has methods for
setting up repeating or delayed callbacks.

.. attribute:: remote_addr

The remote endpoint's address. Use ``.host`` and ``.port`` to retrieve
the IP address and port.

.. method:: connection_made(self)

Called when the connection is made.

.. method:: connection_lost(self)

Called when the connection is lost.

.. method:: connection_timed_out(self)

Called when the connection has been idle too long.

.. method:: packet_received(self, name, buff)

Called when a packet is received from the remote. Usually this method
dispatches the packet to a method named ``packet_<packet name>``, or
calls :meth:`packet_unhandled` if no such methods exists. You might
want to override this to implement your own dispatch logic or logging.

.. method:: packet_unhandled(self, name, buff)

Called when a packet is received that is not hooked. The default
implementation silently discards the packet.

.. method:: send_packet(self, name, data=b"")

Call this to send a packet to the remote.

.. method:: player_joined(self):

Called when the player joins the game.

.. method:: player_left(self):

Called when the player leaves the game.

.. method:: auth_ok(self, data):

Called if the Mojang session server confirms that the connecting client
owns the username they claim to.

.. method:: auth_failed(self, err):

Called if the Mojang session server does not respond to our auth query
or responds with an error.
.. autoclass:: quarry.net.server.ServerProtocol
:members:
:inherited-members:
:exclude-members: makeConnection, logPrefix
16 changes: 16 additions & 0 deletions quarry/net/client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,17 @@ def switch_protocol_mode(self, mode):
### Callbacks -------------------------------------------------------------

def connection_made(self):
"""Called when the connection is established"""
Protocol.connection_made(self)
self.switch_protocol_mode(self.protocol_mode_next)

def auth_ok(self, data):
"""
Called if the Mojang session server responds to our query. Note that
this method does not indicate that the server accepted our session; in
this case :meth:`player_joined` is called.
"""

# Send encryption response
p_shared_secret = crypto.encrypt_secret(
self.public_key,
Expand All @@ -75,14 +82,23 @@ def auth_ok(self, data):
self.logger.debug("Encryption enabled")

def player_joined(self):
"""
Called when we join the game. If the server is in online mode, this
means the server accepted our session.
"""
Protocol.player_joined(self)
self.logger.info("Joined the game.")

def player_left(self):
"""Called when we leave the game."""
Protocol.player_left(self)
self.logger.info("Left the game.")

def status_response(self, data):
"""
If we're connecting in "status" mode, this is called when the server
sends us information about itself.
"""
self.close()

### Packet handlers -------------------------------------------------------
Expand Down
32 changes: 25 additions & 7 deletions quarry/net/protocol.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,23 @@ class ProtocolError(Exception):
class Protocol(protocol.Protocol, PacketDispatcher, object):
"""Shared logic between the client and server"""

#: Usually a reference to the :class:`Buffer` class. This is useful when
#: constructing a packet payload for use in :meth:`send_packet`
buff_type = None

#: A reference to the logger
logger = None

#: A reference to a :class:`Tasks` instance. This object has methods for
#: setting up repeating or delayed callbacks
tasks = None

recv_direction = None
send_direction = None
protocol_version = packets.default_protocol_version
protocol_mode = "init"
compression_threshold = None
compression_enabled = False

in_game = False
closed = False

Expand Down Expand Up @@ -156,7 +166,7 @@ def log_packet(self, prefix, name):
### General callbacks -----------------------------------------------------

def setup(self):
"""Called when the object's initialiser is finished"""
"""Called when the Protocol's initialiser is finished"""

pass

Expand Down Expand Up @@ -204,12 +214,12 @@ def auth_failed(self, err):
### Player callbacks ------------------------------------------------------

def player_joined(self):
"""Called when the protocol mode has switched to "play" """
"""Called when the player joins the game"""

self.in_game = True

def player_left(self):
"""Called when the player leaves"""
"""Called when the player leaves the game"""

pass

Expand Down Expand Up @@ -277,7 +287,12 @@ def data_received(self, data):
self.connection_timer.restart()

def packet_received(self, buff, name):
""" Dispatches packet to registered handler """
"""
Called when a packet is received from the remote. Usually this method
dispatches the packet to a method named ``packet_<packet name>``, or
calls :meth:`packet_unhandled` if no such methods exists. You might
want to override this to implement your own dispatch logic or logging.
"""

self.log_packet(". recv", name)

Expand All @@ -287,12 +302,15 @@ def packet_received(self, buff, name):
self.packet_unhandled(buff, name)

def packet_unhandled(self, buff, name):
"""Called when a packet has no registered handler"""
"""
Called when a packet is received that is not hooked. The default
implementation silently discards the packet.
"""

buff.discard()

def send_packet(self, name, data=b""):
""" Sends a packet """
"""Sends a packet to the remote."""

if self.closed:
return
Expand Down
Loading

0 comments on commit cad47ed

Please sign in to comment.