API (__init__): rename parameter token to session

Author: feberts

.github/workflows/test_api.py

@@ -16,38 +16,38 @@ def fail(msg):
 # ========== join ==========
 
 GAME = 'Echo'
-TOKEN = 'test'
+SESSION = 'test'
 NAME = 'bob'
 
 try:
-    game_err = GameServerAPI(SERVER, PORT, 'InvalidGame', TOKEN, 1)
+    game_err = GameServerAPI(SERVER, PORT, 'InvalidGame', SESSION, 1)
     my_id = game_err.join()
     fail('no exception when trying to start non-existent game')
 except GameServerError:
     pass
 
 try:
-    game_err = GameServerAPI(SERVER, 9999, GAME, TOKEN, 1)
+    game_err = GameServerAPI(SERVER, 9999, GAME, SESSION, 1)
     my_id = game_err.join()
     fail('no exception despite invalid port')
 except GameServerError:
     pass
 
 try:
-    game_err = GameServerAPI('127.0.0.13', PORT, GAME, TOKEN, 1)
+    game_err = GameServerAPI('127.0.0.13', PORT, GAME, SESSION, 1)
     my_id = game_err.join()
     fail('no exception despite invalid ip')
 except GameServerError:
     pass
 
 try:
-    game_err = GameServerAPI(SERVER, PORT, GAME, TOKEN)
+    game_err = GameServerAPI(SERVER, PORT, GAME, SESSION)
     my_id = game_err.join()
     fail('no exception when trying to join non-existent session')
 except GameServerError:
     pass
 
-game = GameServerAPI(SERVER, PORT, GAME, TOKEN, 1, NAME)
+game = GameServerAPI(SERVER, PORT, GAME, SESSION, 1, NAME)
 
 try:
     game.move(msg='invalid')
@@ -58,7 +58,7 @@ def fail(msg):
 my_id = game.join()
 
 try:
-    game_err = GameServerAPI(SERVER, PORT, GAME, TOKEN)
+    game_err = GameServerAPI(SERVER, PORT, GAME, SESSION)
     my_id = game_err.join()
     fail('no exception when trying to join full session')
 except GameServerError:
@@ -119,13 +119,13 @@ def fail(msg):
 # ========== observe ==========
 
 try:
-    observer = GameServerAPI(SERVER, PORT, GAME, TOKEN, name='invalid')
+    observer = GameServerAPI(SERVER, PORT, GAME, SESSION, name='invalid')
     observer.observe()
     fail('observer: no exception despite invalid name')
 except GameServerError:
     pass
 
-observer = GameServerAPI(SERVER, PORT, GAME, TOKEN, name=NAME)
+observer = GameServerAPI(SERVER, PORT, GAME, SESSION, name=NAME)
 observer.observe()
 
 game.move(msg='hello observer')

README.md

@@ -53,13 +53,13 @@ Here is a short demo of the API usage:
 ```py
 from game_server_api import GameServerAPI
 
-game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe', players=2,
-                     token='mygame') # pass 'auto' to auto-join a session (default)
+game = GameServerAPI(server='127.0.0.1', port=4711, game='Yahtzee', players=2,
+                     session='mygame') # pass 'auto' to auto-join a session (default)
 
 my_id = game.join()    # start/join a session - each client is assigned an ID
 game.move(position=5)  # perform a move - the function accepts keyword arguments (**kwargs)
-state = game.state()   # returns a dictionary representing the game state,
-                       # including the ID of the current player(s)
+state = game.state()   # returns a dictionary representing the game state, including
+                       # the ID of the current player(s)
 ```
 
 The [API module](client/game_server_api.py) itself is documented in detail. You can also take a look at the demo clients and the [wiki](https://github.com/feberts/python-game-server/wiki).

client/chat_client.py

@@ -12,7 +12,7 @@
 
 from game_server_api import GameServerAPI, GameServerError, IllegalMove
 
-game = GameServerAPI(server='127.0.0.1', port=4711, game='Chat', token='mychat', players=2)
+game = GameServerAPI(server='127.0.0.1', port=4711, game='Chat', session='mychat', players=2)
 
 def thread_output(text_area):
     while True:

client/echo_client.py

@@ -12,7 +12,7 @@
 
 from game_server_api import GameServerAPI, GameServerError, IllegalMove
 
-game = GameServerAPI(server='127.0.0.1', port=4711, game='Echo', token='mygame', players=1)
+game = GameServerAPI(server='127.0.0.1', port=4711, game='Echo', session='mygame', players=1)
 
 my_id = game.join()
 state = game.state()

client/game_server_api.py

@@ -46,16 +46,16 @@ class GameServerAPI:
     This class provides API functions to communicate with the game server.
     """
 
-    def __init__(self, server, port, game, token='auto', players=None, name=''):
+    def __init__(self, server, port, game, session='auto', players=None, name=''):
         """
         Parameters needed in order to connect to the server and to start or join
         a game session are passed to this constructor. Parameter game specifies
         the game to be started. It corresponds to the name of the game class on
         the server. To be able to join a specific game session, all participants
-        need to agree on a token and pass it to the constructor. The token is
-        used to identify the game session. Alternatively, you can have the
-        server automatically assign you to a session by passing 'auto' as the
-        token (this is the default). Refer to function join for more
+        need to agree on a session token and pass it to the constructor. The
+        token is used to identify the game session. Alternatively, you can have
+        the server automatically assign you to a session by passing 'auto' as
+        the token (this is the default). Refer to function join for more
         information.
 
         The optional parameter players is required by function join in order to
@@ -73,7 +73,7 @@ def __init__(self, server, port, game, token='auto', players=None, name=''):
         server (str): server
         port (int): port number
         game (str): name of the game
-        token (str): name of the session (optional), 'auto' for auto-join (default)
+        session (str): name of the game session (optional), 'auto' for auto-join (default)
         players (int): total number of players (optional)
         name (str): player name (optional)
 
@@ -83,7 +83,7 @@ def __init__(self, server, port, game, token='auto', players=None, name=''):
         assert type(server) == str and len(server) > 0, self._error('server')
         assert type(port) == int and 0 <= port <= 65535, self._error('port')
         assert type(game) == str and len(game) > 0, self._error('game')
-        assert type(token) == str and len(token) > 0, self._error('token')
+        assert type(session) == str and len(session) > 0, self._error('session')
         assert players is None or type(players) == int and players > 0, self._error('players')
         assert type(name) == str, self._error('name')
 
@@ -93,7 +93,7 @@ def __init__(self, server, port, game, token='auto', players=None, name=''):
 
         # game session:
         self._game = game
-        self._token = token
+        self._session = session
         self._players = players
         self._name = name
         self._player_id = None
@@ -117,16 +117,16 @@ def join(self):
 
         There are two ways to start or join a game session:
 
-        - By providing a shared token to the constructor. All clients using the
-          same token will join this specific game session. If such a session
-          exists but is already fully occupied by players, it is terminated and
-          a new session is started.
-        - By passing the string 'auto' as the token. This causes the server to
-          automatically assign you to an open session. If no session exists that
-          can be joined, a new one is started. Existing sessions are never
-          terminated. This method of starting and joining sessions does not
-          interfere with the above method. To achieve this, the server creates
-          unique tokens internally.
+        - By providing a shared session token to the constructor. All clients
+          using the same token will join this specific game session. If such a
+          session exists but is already fully occupied by players, it is
+          terminated and a new session is started.
+        - By passing the string 'auto' as the session token. This causes the
+          server to automatically assign you to an open session. If no session
+          exists that can be joined, a new one is started. Existing sessions are
+          never terminated. This method of starting and joining sessions does
+          not interfere with the above method. To achieve this, the server
+          creates unique tokens internally.
 
         The game starts as soon as the required number of clients has joined the
         game. The function then returns the player ID. The server assigns IDs in
@@ -141,15 +141,15 @@ def join(self):
         response, err, _ = self._send({
             'type':'join',
             'game':self._game,
-            'token':self._token,
+            'session':self._session,
             'players':self._players,
             'name':self._name})
 
         if err: raise GameServerError(err)
 
         self._player_id = response['player_id']
         self._key = response['key']
-        self._token = response['token']
+        self._session = response['session']
         self._request_size_max = response['request_size_max']
 
         return self._player_id
@@ -180,7 +180,7 @@ def move(self, **kwargs):
         _, err, status = self._send({
             'type':'move',
             'game':self._game,
-            'token':self._token,
+            'session':self._session,
             'player_id':self._player_id,
             'key':self._key,
             'move':kwargs})
@@ -204,17 +204,20 @@ def state(self):
 
         Independent of the game, the dictionary always contains these two keys:
 
-        'current': a list of player IDs, indicating whose player's turn it is
-        'gameover': a boolean value indicating whether the game is over or still active
+        - 'current': a list of player IDs, indicating whose player's turn it is
+        - 'gameover': a boolean value indicating whether the game is over or
+          still active
 
         This function will block until the game state changes. Only then does
         the server respond with the updated state. This is more efficient than
         polling. To avoid deadlocks, the function never blocks in these
         situations:
 
-        - when the game has just started to allow clients to get the initial state
+        - when the game has just started to allow clients to get the initial
+          state
         - after a move was performed to allow clients to get the new state
-        - when the game was restarted and a client still has to get the old game's state
+        - when the game was restarted and a client still has to get the old
+          game's state
 
         Returns:
         dict: game state
@@ -227,7 +230,7 @@ def state(self):
         state, err, _ = self._send({
             'type':'state',
             'game':self._game,
-            'token':self._token,
+            'session':self._session,
             'player_id':self._player_id,
             'key':self._key,
             'observer':self._observer})
@@ -258,13 +261,13 @@ def observe(self):
         if type(self._name) != str or len(self._name) == 0:
             raise GameServerError('a valid name must be passed to the constructor')
 
-        if self._token == 'auto':
+        if self._session == 'auto':
             raise GameServerError('observer mode not available for auto-join sessions')
 
         response, err, _ = self._send({
             'type':'observe',
             'game':self._game,
-            'token':self._token,
+            'session':self._session,
             'name':self._name})
 
         if err: raise GameServerError(err)
@@ -291,7 +294,7 @@ def restart(self):
         _, err, _ = self._send({
             'type':'restart',
             'game':self._game,
-            'token':self._token,
+            'session':self._session,
             'player_id':self._player_id,
             'key':self._key})
 

client/more_examples/api_wrapper/tictactoe_api.py

@@ -15,8 +15,8 @@ class TicTacToeAPI:
     This class provides API wrapper functions for tic-tac-toe.
     """
 
-    def __init__(self, token, name=''):
-        self._api = GameServerAPI('127.0.0.1', 4711, 'TicTacToe', token, 2, name)
+    def __init__(self, session, name=''):
+        self._api = GameServerAPI('127.0.0.1', 4711, 'TicTacToe', session, 2, name)
         self.my_id = None
 
     def join(self):

client/more_examples/api_wrapper/tictactoe_client.py

@@ -9,7 +9,7 @@
 
 from tictactoe_api import TicTacToeAPI, GameServerError, IllegalMove
 
-game = TicTacToeAPI(token='mygame')
+game = TicTacToeAPI(session='mygame')
 
 symbols = ('x', 'o')
 

client/more_examples/api_wrapper/yahtzee_api.py

@@ -15,8 +15,8 @@ class YahtzeeAPI:
     This class provides API wrapper functions for Yahtzee.
     """
 
-    def __init__(self, token, players, name=''):
-        self._api = GameServerAPI('127.0.0.1', 4711, 'Yahtzee', token, players, name)
+    def __init__(self, session, players, name=''):
+        self._api = GameServerAPI('127.0.0.1', 4711, 'Yahtzee', session, players, name)
         self.my_id = None
 
     def join(self):

client/more_examples/api_wrapper/yahtzee_client.py

@@ -9,7 +9,7 @@
 
 from yahtzee_api import YahtzeeAPI, GameServerError, IllegalMove
 
-game = YahtzeeAPI(token='mygame', players=1)
+game = YahtzeeAPI(session='mygame', players=1)
 
 def print_scorecard(scorecard):
     print('\n' * 100)

client/more_examples/observer_mode/input_client.py

@@ -11,7 +11,7 @@
 
 from game_server_api import GameServerAPI, GameServerError, IllegalMove
 
-game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe', token='mygame', players=2, name='bob')
+game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe', session='mygame', players=2, name='bob')
 
 def user_input(prompt):
     while True: