diplomacy.communication.requests

Client -> Server requests.

This module contains the definition of request (as classes) that a client can send to Diplomacy server implemented in this project.

The client -> server communication follows this procedure:

• Client sends a request to server. All requests have parameters that must be filled by client before being sent.
• Server replies with a response, which is either an error response or a valid response.
• Client receives and handles server response.
  • If server response is an error, client converts it to a typed exception and raises it.
  • If server response is a valid response, client return either the response data directly, or make further treatments and return a derived data.

Diplomacy package actually provides 2 clients: the Python client and the web front-end.

Web front-end provides user-friendly forms to collect required request parameters, makes all request calls internally, and then uses them to update graphical user interface. So, when using front-end, you don’t need to get familiar with underlying protocol, and documentation in this module won’t be really useful for you.

Python client consists of three classes (Connection, Channel and NetworkGame) which provide appropriate methods to automatically send requests, handle server response, and either raise an exception (if server returns an error) or return a client-side wrapped data (if server returns a valid response) where requests were called. Thus, these methods still need to receive request parameters, and you need to know what kind of data they can return. So, if you use Python client, you will need the documentation in this module, which describes, for each request:

• the request parameters (important)
• the server valid responses (less interesting)
• the Python client returned values (important)

All requests classes inherit from _AbstractRequest which require parameters name (from parant class NetworkData), request_id and re_sent. These parameters are automatically filled by the client.

From parent class _AbstractRequest, we get 3 types of requests:

• public requests, which directly inherit from _AbstractRequest.
• channel requests, inherited from _AbstractChannelRequest, which requires additional parameter token. Token is retrieved by client when he connected to server using connection request SignIn, and is then used to create a Channel object. Channel object will be responsible for sending all other channel requests, automatically filling token field for these requests.
• game requests, intherited from _AbstractGameRequest, which itself inherit from _AbstractChannelRequest, and requires additional parameters game_id, game_role and phase (game short phase name). Game ID, role and phase are retrieved for a specific game by the client when he joined a game through one of featured Channel methods which return a NetworkGame object. Network game will then be responsible for sending all other game requests, automatically filling game ID, role and phase for these requests.

Then, all other requests derived directly from either abstract request class, abstract channel request class, or abstract game request class, may require additional parameters, and if so, these parameters will need to be filled by the user, by passing them to related client methods.

Check Connection for available public request methods (and associated requests).

Check Channel for available channel request methods (and associated requests).

Check NetworkGame for available game request methods (and associated requests).

Then come here to get parameters and returned values for associated requests.

class diplomacy.communication.requests.GetDaidePort(**kwargs)

Bases: diplomacy.communication.requests._AbstractRequest

Public request to get DAIDE port opened for a game.

Parameters:game_id (str) – ID of game for which yu want to get DAIDE port Returns:

• Server: DataPort
• Client: int - DAIDE port

Raises:diplomacy.utils.exceptions.DaidePortException – if there is no DAIDE port associated to given game ID.

class diplomacy.communication.requests.SignIn(**kwargs)

Bases: diplomacy.communication.requests._AbstractRequest

Connection request. Log in or sign in to server.

Parameters:

• username (str) – account username
• password (str) – account password

Returns:

• Server: DataToken
• Client: a Channel object presenting user connected to the server. If any sign in error occurs, raise an appropriate ResponseException.

class diplomacy.communication.requests.CreateGame(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to create a game.

Parameters:

• game_id (str, optional) – game ID. If not provided, a game ID will be generated.
• n_controls (int, optional) – number of controlled powers required to start the game. A power becomes controlled when a player joins the game to control this power. Game won’t start as long it does not have this number of controlled powers. Game will stop (to forming state) if the number of controlled powers decrease under this number (e.g. when powers are kicked, eliminated, or when a player controlling a power leaves the game). If not provided, set with the number of powers on the map (e.g. 7 on standard map).
• deadline (int, optional) – (default 300) time (in seconds) for the game to wait before processing a phase. 0 means no deadline, ie. game won’t process a phase until either all powers submit orders and turn off wait flag, or a game master forces game to process.
• registration_password (str, optional) – password required to join the game. If not provided, anyone can join the game.
• power_name (str, optional) –

  power to control once game is created.

  • If provided, the user who send this request will be joined to the game as a player controlling this power.
  • If not provided, the user who send this request will be joined to the game as an omniscient observer (ie. able to see everything in the game, including user messages). Plus, as game creator, user will also be a game master, ie. able to send master requests, e.g. to force game processing.
• state (dict, optional) – game initial state (for expert users).
• map_name (str, optional) – (default 'standard') map to play on. You can retrieve maps available on server by sending request GetAvailableMaps.
• rules (list, optional) – list of strings - game rules (for expert users).

Returns:

• Server: DataGame
• Client: a NetworkGame object representing a client version of the game created and joined. Either a power game (if power name given) or an omniscient game.

class diplomacy.communication.requests.DeleteAccount(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to delete an account.

Parameters:username (str, optional) –

name of user to delete account

• if not given, then account to delete will be the one of user sending this request.
• if provided, then user submitting this request must have administrator privileges.

Returns:None

class diplomacy.communication.requests.GetDummyWaitingPowers(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to get games with dummy waiting powers. A dummy waiting power is a dummy (not controlled) power:

• not yet eliminated,
• without orders submitted (for current game phase),
• but able to submit orders (for current game phase),
• and who is waiting for orders.

It’s a non-controlled orderable free power, which is then best suited to be controlled by an automated player (e.g. a bot, or a learning algorithm).

Parameters:buffer_size (int) – maximum number of powers to return. Returns:

• Server: DataGamesToPowerNames
• Client: a dictionary mapping a game ID to a list of dummy waiting power names, such that the total number of power names in the entire dictionary does not exceed given buffer size.

class diplomacy.communication.requests.GetAvailableMaps(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to get maps available on server.

Returns:

• Server: DataMaps
• Client: a dictionary associating a map name to a dictionary of information related to the map. You can especially check key 'powers' to get the list of map power names.

class diplomacy.communication.requests.GetPlayablePowers(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to get the list of playable powers for a game. A playable power is a dummy (uncontrolled) power not yet eliminated.

Parameters:game_id (str) – ID of game to get playable powers Returns:

• Server: DataPowerNames
• Client: set of playable power names for given game ID.

class diplomacy.communication.requests.JoinGame(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to join a game.

Parameters:

• game_id (str) – ID of game to join
• power_name (str, optional) – if provided, name of power to control. Otherwise, user wants to observe game without playing.
• registration_password (str, optional) – password to join game. If omitted while game requires a password, server will return an error.

Returns:

• Server: DataGame
• Client: a NetworkGame object representing the client game, which is either:
  • a power game (if power name was given), meaning that this network game allows user to play a power
  • an observer game, if power was not given and user does not have omniscient privileges for this game. Observer role allows user to watch game phases changes, orders submitted and orders results for each phase, but he can not see user messages and he can not send any request that requires game master privileges.
  • an omniscient game, if power was not given and user does have game master privileges. Omniscient role allows user to see everything in the game, including user messages. If user does only have omniscient privileges for this game, he can’t do anything more, If he does have up to game master privileges, then he can also send requests that require game master privileges.

class diplomacy.communication.requests.JoinPowers(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to join many powers of a game with one request.

This request is mostly identical to JoinGame, except that list of power names is mandatory. It’s useful to allow the user to control many powers while still working with 1 client game instance.

Parameters:

• game_id (str) – ID of game to join
• power_names (list, optional) – list of power names to join
• registration_password (str, optionl) – password to join the game

Returns:

None. If request succeeds, then the user is registered as player for all given power names. The user can then simply join game to one of these powers (by sending a JoinGame request), and he will be able to manage all the powers through the client game returned by JoinGame.

class diplomacy.communication.requests.ListGames(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to find games.

Parameters:

• game_id (str, optional) – if provided, look for games with game ID either containing or contained into this game ID.
• status (str, optional) – if provided, look for games with this status.
• map_name (str, optional) – if provided, look for games with this map name.
• include_protected (bool optional) – (default True) tell if we must look into games protected by a password
• for_omniscience (bool, optional) – (default False) tell if we look for games where request user can be at least omniscient.

Returns:

• Server: DataGames
• Client: a list of DataGameInfo objects, each containing a bunch of information about a game found. If no game found, list will be empty.

class diplomacy.communication.requests.GetGamesInfo(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to get information for a given list of game indices.

Parameters:games (list) – list of game ID. Returns:

• Server: DataGames
• Client: a list of DataGameInfo objects.

class diplomacy.communication.requests.Logout(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to logout. Returns nothing.

class diplomacy.communication.requests.UnknownToken(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to tell server that a channel token is unknown.

Note

Client does not even wait for a server response when sending this request, which acts more like a “client notification” sent to server.

class diplomacy.communication.requests.SetGrade(**kwargs)

Bases: diplomacy.communication.requests._AbstractChannelRequest

Channel request to modify the grade of a user. Require admin privileges to change admin grade, and at least game master privileges to change omniscient or moderator grade.

Parameters:

• grade (str) – grade to update ('omniscient', 'admin' or 'moderator')
• grade_update (str) – how to make update ('promote' or 'demote')
• username (str) – user for which the grade must be modified
• game_id (str, optional) – ID of game for which the grade must be modified. Required only for 'moderator' and 'omniscient' grade.

Returns:

None

class diplomacy.communication.requests.ClearCenters(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to clear supply centers. See method Game.clear_centers().

Parameters:power_name (str, optional) – if given, clear centers for this power. Otherwise, clear centers for all powers. Returns:None

class diplomacy.communication.requests.ClearOrders(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to clear orders.

Parameters:power_name (str, optional) – if given, clear orders for this power. Otherwise, clear orders for all powers. Returns:None

class diplomacy.communication.requests.ClearUnits(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to clear units.

Parameters:power_name (str, optional) – if given, clear units for this power. Otherwise, clear units for all powers. Returns:None

class diplomacy.communication.requests.DeleteGame(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to delete a game. Require game master privileges. Returns nothing.

class diplomacy.communication.requests.GetAllPossibleOrders(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to get all possible orders. Return (server and client) a DataPossibleOrders object containing possible orders and orderable locations.

class diplomacy.communication.requests.GetPhaseHistory(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to get a list of game phase data from game history for given phases interval. A phase can be either None, a phase name (string) or a phase index (integer). See Game.get_phase_history() about how phases are used to retrieve game phase data.

Parameters:

• from_phase (str | int, optional) – phase from which to look in game history
• to_phase (str | int, optional) – phase up to which to look in game history

Returns:

• Server: DataGamePhases
• Client: a list of GamePhaseData objects corresponding to game phases found between from_phase and to_phase in game history.

class diplomacy.communication.requests.LeaveGame(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to leave a game (logout from game). If request power name is set (ie. request user was a player), then power will become uncontrolled. Otherwise, user will be signed out from its observer (or omniscient) role. Returns nothing.

class diplomacy.communication.requests.ProcessGame(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to force a game processing. Require master privileges. Return nothing.

class diplomacy.communication.requests.QuerySchedule(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to get info about current scheduling for a game in server. Returns (server and client) a DataGameSchedule object.

class diplomacy.communication.requests.SaveGame(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to get game exported in JSON format.

Returns:

• Server: DataSavedGame
• Client: dict - the JSON dictionary.

class diplomacy.communication.requests.SendGameMessage(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game message to send a user request.

Parameters:message (Message) – message to send. See Message for more info. message sender must be request user role (ie. power role, in such case). Message time sent must not be defined, it will be allocated by server. Returns:

• Server: DataTimeStamp
• Client: nothing (returned timestamp is just used to update message locally)

class diplomacy.communication.requests.SetDummyPowers(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to set dummy powers. Require game master privileges. If given powers are controlled, related players are kicked and powers become dummy (uncontrolled).

Parameters:

• power_names (list, optional) – list of power names to set dummy. If not provided, will be all map power names.
• username – if provided, only power names controlled by this user will be set dummy.

Returns:

None

class diplomacy.communication.requests.SetGameState(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to set a game state (for exper users). Require game master privileges.

Parameters:

• state (dict) – game state
• orders (dict) – dictionary mapping a power name to a list of orders strings
• results (dict) – dictionary mapping a unit to a list of order result strings
• messages (dict) – dictionary mapping a timestamp to a message

Returns:

None

class diplomacy.communication.requests.SetGameStatus(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to force game status (only if new status differs from previous one). Require game master privileges.

Parameters:status (str) –

game status to set. Either 'forming', 'active', 'paused', 'completed' or 'canceled'.

• If new status is 'completed', game will be forced to draw.
• If new status is 'active', game will be forced to start.
• If new status is 'paused', game will be forced to pause.
• If new status is 'canceled', game will be canceled and become invalid.

Returns:None

class diplomacy.communication.requests.SetOrders(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to set orders for a power.

Parameters:

• power_name (str, optional) – power name. If not given, request user must be a game player, and power is inferred from request game role.
• orders (list) – list of power orders.
• wait (bool, optional) – if provided, wait flag to set for this power.

Returns:

None

class diplomacy.communication.requests.SetWaitFlag(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to set orders for a power.

Parameters:

• power_name (str, optional) – power name. If not given, request user must be a game player, and power if inferred from request game role.
• wait (bool) – wait flag to set.

Returns:

None

class diplomacy.communication.requests.Synchronize(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to force synchronization of client game with server game. If necessary, server will send appropriate notifications to client game so that it can be up to date with server game state.

Parameters:timestamp (int) – timestamp since which client game needs to synchronize. Returns:(server and client) a DataGameInfo object.

class diplomacy.communication.requests.Vote(**kwargs)

Bases: diplomacy.communication.requests._AbstractGameRequest

Game request to vote for draw decision. If number of pro-draw votes > number of con-draw votes for current phase, then server will automatically draw the game and send appropriate notifications. Votes are reset after a game processing.

Parameters:

• power_name (str, optional) – power name who wants to vote. If not provided, request user must be a game player, and power name will be inferred from request game role.
• vote (str) – vote to set. Either 'yes' (power votes for draw), 'no' (power votes against draw), or 'neutral' (power does not want to decide).

Returns:

None

diplomacy.communication.requests.parse_dict(json_request)

Parse a JSON dictionary expected to represent a request. Raise an exception if parsing failed.

Parameters:json_request (dict) – JSON dictionary. Returns:a request class instance. Return type:_AbstractRequest | _AbstractChannelRequest | _AbstractGameRequest