From 9aa369c7da351915a535e5ed2edfe82d0a1a60c9 Mon Sep 17 00:00:00 2001 From: Ammar Askar Date: Mon, 19 Dec 2016 05:26:12 -0500 Subject: [PATCH] Fix outdated documentation --- docs/authentication.rst | 42 +++++++++++++----------------- docs/connecting.rst | 33 ++++++++++++++--------- docs/index.rst | 3 ++- minecraft/authentication.py | 4 +-- minecraft/networking/connection.py | 10 +++---- 5 files changed, 46 insertions(+), 46 deletions(-) diff --git a/docs/authentication.rst b/docs/authentication.rst index 35373c9..709684c 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -1,29 +1,28 @@ Authentication ============== -.. currentmodule:: authentication +.. currentmodule:: minecraft.authentication .. _Yggdrasil: http://wiki.vg/Authentication .. _LoginResponse: http://wiki.vg/Authentication#Authenticate The authentication module contains functions and classes to facilitate -interfacing with Mojang's Yggdrasil_ service. +interfacing with Mojang's Yggdrasil_ authentication service. Logging In ~~~~~~~~~~~~~~~~~~~~ The most common use for this module in the context of a client will be to -log in to a Minecraft account. The convenience method +log in to a Minecraft account. The first step to doing this is creating +an instance of the AuthenticationToken class after which you may use the +authenticate method with the user's username and password in order to make the AuthenticationToken valid. -.. autofunction:: login_to_minecraft +.. autoclass:: AuthenticationToken + :members: authenticate -should be used which will return a LoginResponse object. See LoginResponse_ for more details on the returned attributes - -.. autoclass:: LoginResponse - :members: - -or raise a YggdrasilError on failure, for example if an incorrect username/password -is provided or the web request failed +Upon success, the function returns True, on failure a YggdrasilError +is raised. This happens, for example if an incorrect username/password +is provided or the web request failed. .. autoexception:: YggdrasilError :members: @@ -32,15 +31,13 @@ is provided or the web request failed Arbitary Requests ~~~~~~~~~~~~~~~~~~~~ -You may make any arbitary request to the Yggdrasil service with +You may make any arbitary request to the Yggdrasil service with the _make_request +method passing in the AUTH_SERVER as the server parameter. -.. automodule:: authentication - :members: BASE_URL +.. automodule:: minecraft.authentication + :members: AUTH_SERVER -.. autofunction:: make_request - -.. autoclass:: Response - :members: +.. autofunction:: _make_request --------------- @@ -48,11 +45,8 @@ You may make any arbitary request to the Yggdrasil service with --------------- An example of making an arbitary request can be seen here:: - url = authentication.BASE_URL + "session/minecraft/join" - server_id = encryption.generate_verification_hash(packet.server_id, secret, packet.public_key) - payload = {'accessToken': self.connection.login_response.access_token, - 'selectedProfile': self.connection.login_response.profile_id, - 'serverId': server_id} + payload = {'username': username, + 'password': password} - authentication.make_request(url, payload) + authentication._make_request(authentication.AUTH_SERVER, "signout", payload) diff --git a/docs/connecting.rst b/docs/connecting.rst index 07da75a..708e787 100644 --- a/docs/connecting.rst +++ b/docs/connecting.rst @@ -1,54 +1,61 @@ Connecting to Servers ====================== -.. module:: network.connection +.. module:: minecraft.networking.connection -Your primary dealings when connecting to a server will deal with the Connection class +Your primary dealings when connecting to a server will be with the Connection class -.. autoclass:: network.connection.Connection +.. autoclass:: Connection :members: Writing Packets ~~~~~~~~~~~~~~~~~~~~ The packet class uses a lot of magic to work, here is how to use them. -Look up the particular packet you need to deal with, for my example let's go with the ``KeepAlivePacket`` +Look up the particular packet you need to deal with, for this example +let's go with the ``KeepAlivePacket`` -.. autoclass:: network.packets.KeepAlivePacket +.. autoclass:: minecraft.networking.packets.KeepAlivePacket :undoc-members: :inherited-members: - :exclude-members: read, write + :exclude-members: read, write, context, get_definition, get_id, id, packet_name, set_values -Pay close attention to the definition attribute, we're gonna be using that to assign values within the packet:: +Pay close attention to the definition attribute, and how our class variable corresponds to +the name given from the definition:: packet = KeepAlivePacket() packet.keep_alive_id = random.randint(0, 5000) connection.write_packet(packet) -and just like that, the packet will be written out to the server +and just like that, the packet will be written out to the server. + +It is possible to implement your own custom packets by subclassing +:class:`minecraft.networking.packets.Packet`. Read the docstrings and +follow the examples in packets.py for more details on how to do advanced tasks +like having a packet that is compatible across multiple protocol versions. Listening for Certain Packets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's look at how to listen for certain packets, the relevant method being -.. automethod:: network.connection.Connection.register_packet_listener +.. automethod:: Connection.register_packet_listener An example of this can be found in the ``start.py`` headless client, it is recreated here:: - connection = Connection(address, port, login_response) + connection = Connection(options.address, options.port, auth_token=auth_token) connection.connect() def print_chat(chat_packet): print "Position: " + str(chat_packet.position) print "Data: " + chat_packet.json_data - from network.packets import ChatMessagePacket + from minecraft.networking.packets import ChatMessagePacket connection.register_packet_listener(print_chat, ChatMessagePacket) The field names ``position`` and ``json_data`` are inferred by again looking at the definition attribute as before -.. autoclass:: network.packets.ChatMessagePacket +.. autoclass:: minecraft.networking.packets.ChatMessagePacket :undoc-members: :inherited-members: - :exclude-members: read, write \ No newline at end of file + :exclude-members: read, write, context, get_definition, get_id, id, packet_name, set_values \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3c55025..38cee5b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,8 @@ Welcome to pyCraft's documentation! between a Minecraft server as a client. The authentication package contains utilities to manage communicating -with Mojang's in order to log in with a minecraft account, edit profiles etc +with Mojang's authentication servers in order to log in with a minecraft +account, edit profiles etc The Connection class under the networking package handles connecting to a server, sending packets, listening for packets etc diff --git a/minecraft/authentication.py b/minecraft/authentication.py index bb9df63..4e9c31a 100644 --- a/minecraft/authentication.py +++ b/minecraft/authentication.py @@ -1,10 +1,8 @@ -""" -Handles authentication with the Mojang authentication server. -""" import requests import json from .exceptions import YggdrasilError +#: The base url for Ygdrassil requests AUTH_SERVER = "https://authserver.mojang.com" SESSION_SERVER = "https://sessionserver.mojang.com/session/minecraft" # Need this content type, or authserver will complain diff --git a/minecraft/networking/connection.py b/minecraft/networking/connection.py index 99ca067..96b71dd 100644 --- a/minecraft/networking/connection.py +++ b/minecraft/networking/connection.py @@ -66,7 +66,7 @@ class Connection(object): :param address: address of the server to connect to :param port(int): port of the server to connect to - :param auth_token: :class:`authentication.AuthenticationToken` object. + :param auth_token: :class:`minecraft.authentication.AuthenticationToken` object. If None, no authentication is attempted and the server is assumed to be running in offline mode. :param username: Username string; only applicable in offline mode. @@ -81,15 +81,15 @@ class Connection(object): use in connecting to the server. :param handle_exception: A function to be called when an exception occurs in the client's networking thread, - taking 2 arguments: the exception object `e' - as in `except Exception as e', and a 3-tuple + taking 2 arguments: the exception object 'e' + as in 'except Exception as e', and a 3-tuple given by sys.exc_info(); or None for the default behaviour of raising the exception from its original context; or False for no action. In any case, the networking thread will terminate, the exception will be - available via the `exception' and `exc_info' - attributes of the `Connection' instance. + available via the 'exception' and 'exc_info' + attributes of the 'Connection' instance. """ self._write_lock = Lock()