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 parametertoken
. Token is retrieved by client when he connected to server using connection requestSignIn
, and is then used to create aChannel
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 parametersgame_id
,game_role
andphase
(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 featuredChannel
methods which return aNetworkGame
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)[source]¶ 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. - Server:
-
class
diplomacy.communication.requests.
SignIn
(**kwargs)[source]¶ 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 appropriateResponseException
.
-
class
diplomacy.communication.requests.
CreateGame
(**kwargs)[source]¶ 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 requestGetAvailableMaps
. - 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)[source]¶ 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)[source]¶ 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)[source]¶ 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.
- Server:
-
class
diplomacy.communication.requests.
GetPlayablePowers
(**kwargs)[source]¶ 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.
- Server:
-
class
diplomacy.communication.requests.
JoinGame
(**kwargs)[source]¶ 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)[source]¶ 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 byJoinGame
.
-
class
diplomacy.communication.requests.
ListGames
(**kwargs)[source]¶ 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)[source]¶ 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.
- Server:
-
class
diplomacy.communication.requests.
Logout
(**kwargs)[source]¶ Bases:
diplomacy.communication.requests._AbstractChannelRequest
Channel request to logout. Returns nothing.
-
class
diplomacy.communication.requests.
UnknownToken
(**kwargs)[source]¶ 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)[source]¶ 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
- grade (str) – grade to update (
-
class
diplomacy.communication.requests.
ClearCenters
(**kwargs)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Bases:
diplomacy.communication.requests._AbstractGameRequest
Game request to delete a game. Require game master privileges. Returns nothing.
-
class
diplomacy.communication.requests.
GetAllPossibleOrders
(**kwargs)[source]¶ 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)[source]¶ 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 betweenfrom_phase
andto_phase
in game history.
-
class
diplomacy.communication.requests.
LeaveGame
(**kwargs)[source]¶ 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)[source]¶ Bases:
diplomacy.communication.requests._AbstractGameRequest
Game request to force a game processing. Require master privileges. Return nothing.
-
class
diplomacy.communication.requests.
QuerySchedule
(**kwargs)[source]¶ 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)[source]¶ Bases:
diplomacy.communication.requests._AbstractGameRequest
Game request to get game exported in JSON format.
Returns: - Server:
DataSavedGame
- Client: dict - the JSON dictionary.
- Server:
-
class
diplomacy.communication.requests.
SendGameMessage
(**kwargs)[source]¶ 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)
- Server:
-
class
diplomacy.communication.requests.
SetDummyPowers
(**kwargs)[source]¶ 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)[source]¶ 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)[source]¶ 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 - If new status is
-
class
diplomacy.communication.requests.
SetOrders
(**kwargs)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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