From abb42dcd4886705d6ba8af27f68ef605218ac67c Mon Sep 17 00:00:00 2001 From: Philip Paquette Date: Wed, 11 Sep 2019 12:58:45 -0400 Subject: Added ReadtheDocs documentation for the public API - Reformatted the docstring to be compatible - Added tests to make sure the documentation compiles properly - Added sphinx as a pip requirement Co-authored-by: Philip Paquette Co-authored-by: notoraptor --- diplomacy/tests/network/run_real_game.py | 28 +++++++++++++++------- diplomacy/tests/network/test_real_game.py | 39 ++++++++++++++++++++++++------- diplomacy/tests/test_datc.py | 2 +- 3 files changed, 51 insertions(+), 18 deletions(-) (limited to 'diplomacy/tests') diff --git a/diplomacy/tests/network/run_real_game.py b/diplomacy/tests/network/run_real_game.py index a9800b6..e243dec 100644 --- a/diplomacy/tests/network/run_real_game.py +++ b/diplomacy/tests/network/run_real_game.py @@ -18,17 +18,27 @@ """ Run tests from diplomacy.tests.network.test_real_game to test games in a real environment. Each test run a game and checks game messages and phases against an expected game data file. Current tested gama data files are JSON files located into folder diplomacy/tests/network: - 1.json - 2.json - 3.json - Need a local diplomacy server running. You must specify this server port using parameter --port=. - To run all tests: + + - 1.json + - 2.json + - 3.json + + Need a local diplomacy server running. You must specify + this server port using parameter ``--port=``. + + To run all tests: :: + python -m diplomacy.tests.network.run_real_game --port= - To run a specific test (e.g. 2.json, or 2.json and 1.json): - python -m diplomacy.tests.network.run_real_game --cases=20 --port= - python -m diplomacy.tests.network.run_real_game --cases=15,20 --port= - For help: + + To run a specific test (e.g. 2.json, or 2.json and 1.json): :: + + python -m diplomacy.tests.network.run_real_game --cases=2 --port= + python -m diplomacy.tests.network.run_real_game --cases=1,2 --port= + + For help: :: + python -m diplomacy.tests.network.run_real_game --help + """ import argparse from tornado import gen diff --git a/diplomacy/tests/network/test_real_game.py b/diplomacy/tests/network/test_real_game.py index a960b91..bd63da1 100644 --- a/diplomacy/tests/network/test_real_game.py +++ b/diplomacy/tests/network/test_real_game.py @@ -19,6 +19,7 @@ import logging import os import random +from typing import Dict from tornado import gen from tornado.concurrent import Future @@ -39,12 +40,13 @@ DEFAULT_HOSTNAME = 'localhost' DEFAULT_PORT = random.randint(9000, 10000) -class ExpectedPhase(): +class ExpectedPhase: """ Helper class to manage data from an expected phase. """ __slots__ = ['name', 'state', 'orders', 'messages'] def __init__(self, json_phase): """ Initialize expected phase. + :param json_phase: JSON dict representing a phase. Expected fields: name, state, orders, messages. """ self.name = json_phase['name'] @@ -63,12 +65,13 @@ class ExpectedPhase(): return [message for message in self.messages if message.sender == power_name or message.recipient in (power_name, GLOBAL)] -class ExpectedMessages(): +class ExpectedMessages: """ Expected list of messages sent and received by a power name. """ __slots__ = ['power_name', 'messages', 'next_messages_to_send'] def __init__(self, power_name, messages): """ Initialize the expected messages. + :param power_name: power name which exchanges these messages :param messages: messages exchanged """ @@ -100,13 +103,14 @@ class ExpectedMessages(): self.next_messages_to_send.extend(self.messages[:next_message_to_receive]) del self.messages[:next_message_to_receive] -class ExpectedData(): +class ExpectedData: """ Expected data for a power in a game. """ __slots__ = ['messages', 'phases', '__phase_index', 'playing'] def __init__(self, power_name, phases, phase_index): """ Initialize expected data for a game power. + :param power_name: name of power for which those data are expected. :param phases: list of expected phases. :param phase_index: index of current expected phase in given phases. @@ -130,12 +134,13 @@ class ExpectedData(): self.messages = ExpectedMessages( self.messages.power_name, self.phases[self.__phase_index].get_power_related_messages(self.power_name)) -class CaseData(): +class CaseData: """ Helper class to store test data. """ FILE_FOLDER_NAME = os.path.abspath(os.path.dirname(__file__)) def __init__(self, case_file_name, hostname=DEFAULT_HOSTNAME, port=DEFAULT_PORT): """ Initialize game test. + :param case_file_name: File name of JSON file containing expected game data. JSON file must be located in folder FILE_FOLDER_NAME. :param hostname: hostname to use to load server. @@ -157,7 +162,7 @@ class CaseData(): self.admin_channel = None self.admin_game = None self.user_games = {} - self.future_games_ended = {} # type: dict{str, Future} + self.future_games_ended = {} # type: Dict[str, Future] self.hostname = hostname self.port = port @@ -169,6 +174,7 @@ class CaseData(): @gen.coroutine def on_power_phase_update(self, game, notification=None): """ User game notification callback for game phase updated. + :param game: game :param notification: notification :type game: NetworkGame @@ -187,6 +193,7 @@ class CaseData(): @gen.coroutine def on_power_state_update(self, game, notification): """ User game notification callback for game state update. + :param game: game :param notification: notification :type game: NetworkGame @@ -198,6 +205,7 @@ class CaseData(): @gen.coroutine def send_messages_if_needed(game, expected_messages): """ Take messages to send in top of given messages list and send them. + :param game: a NetworkGame object. :param expected_messages: an instance of ExpectedMessages. :type game: NetworkGame @@ -222,6 +230,7 @@ def send_messages_if_needed(game, expected_messages): @gen.coroutine def send_current_orders(game): """ Send expected orders for current phase. + :param game: a Network game object. :type game: NetworkGame """ @@ -242,6 +251,7 @@ def send_current_orders(game): def on_message_received(game, notification): """ User game notification callback for messages received. + :param game: a NetworkGame object, :param notification: a notification received by this game. :type game: NetworkGame @@ -286,6 +296,7 @@ def on_message_received(game, notification): def on_admin_game_phase_update(admin_game, notification=None): """ Admin game notification callback for game phase update. + :param admin_game: admin game :param notification: notification :type admin_game: NetworkGame @@ -370,6 +381,7 @@ def on_admin_game_phase_update(admin_game, notification=None): def on_admin_game_state_update(admin_game, notification): """ Admin game notification callback for game state update. + :param admin_game: admin game :param notification: notification :type admin_game: NetworkGame @@ -380,6 +392,7 @@ def on_admin_game_state_update(admin_game, notification): def on_admin_powers_controllers(admin_game, notification): """ Admin game notification callback for powers controllers received (unexpected). + :param admin_game: game :param notification: notification :type admin_game: NetworkGame @@ -390,6 +403,7 @@ def on_admin_powers_controllers(admin_game, notification): def on_admin_game_status_update(admin_game, notification): """ Admin game notification callback for game status update. + :param admin_game: admin game :param notification: notification :type admin_game: NetworkGame @@ -399,9 +413,11 @@ def on_admin_game_status_update(admin_game, notification): @gen.coroutine def play_phase(game, expected_messages): """ Play a phase for a user game: - 1) Send messages - 2) wait for messages to receive - 3) send current orders. + + #. Send messages + #. wait for messages to receive + #. send current orders. + :param game: user game :param expected_messages: expected messages :type game: NetworkGame @@ -418,6 +434,7 @@ def play_phase(game, expected_messages): def on_game_status_update(game, notification): """ User game notification callback for game status update. Used to start the game locally when game started on server. + :param game: game :param notification: notification :type game: NetworkGame @@ -434,6 +451,7 @@ def on_game_status_update(game, notification): @gen.coroutine def verify_current_phase(game): """ Check and play current phase. + :param game: a NetWork game object. :type game: NetworkGame """ @@ -455,6 +473,7 @@ def verify_current_phase(game): def get_user_game_fn(case_data, power_name): """ Return a coroutine procedure that loads and play a user game for given power name. + :param case_data: case data :param power_name: str :return: a procedure. @@ -471,6 +490,7 @@ def get_user_game_fn(case_data, power_name): def get_future_game_done_fn(power_name): """ Return a callback to call when a power game is finished. Callback currently just prints a message to tell that power game is terminated. + :param power_name: power name of associated game. :return: a callable that receives the future done when game is finished. """ @@ -484,6 +504,7 @@ def get_future_game_done_fn(power_name): @gen.coroutine def load_power_game(case_data, power_name): """ Load and play a power game from admin game for given power name. + :type case_data: CaseData """ print('Loading game for power', power_name) @@ -519,6 +540,7 @@ def load_power_game(case_data, power_name): def main(case_data): """ Test real game environment with one game and all power controlled (no dummy powers). This method may be called form a non-test code to run a real game case. + :param case_data: test data :type case_data: CaseData """ @@ -567,6 +589,7 @@ def run(case_data, **server_kwargs): Load a server (with optional given server kwargs), call function main(case_data) as client code and wait for main function to terminate. + :type case_data: CaseData """ diff --git a/diplomacy/tests/test_datc.py b/diplomacy/tests/test_datc.py index 8c40363..093ed14 100644 --- a/diplomacy/tests/test_datc.py +++ b/diplomacy/tests/test_datc.py @@ -24,7 +24,7 @@ from diplomacy.utils.order_results import OK, NO_CONVOY, BOUNCE, VOID, CUT, DISL # ----------------- # DATC TEST CASES # ----------------- -class TestDATC(): +class TestDATC: """ DATC test cases""" # pylint: disable=too-many-public-methods -- cgit v1.2.3