experiment_server 0.3.4__tar.gz → 0.3.5__tar.gz

{experiment_server-0.3.4 → experiment_server-0.3.5}/PKG-INFO

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: experiment_server
-Version: 0.3.4
+Version: 0.3.5
 Summary: Server for experiments to get configuarations from
-Home-page: https://shariff-faleel.com/experiment_server/
 License: MIT
 Keywords: experiment,study-design
 Author: Ahmed Shariff
@@ -19,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: Jinja2 (>=3.1.2)
 Requires-Dist: asyncio (>=3.4.3)
 Requires-Dist: click (>=6.0)
@@ -33,6 +33,7 @@ Requires-Dist: toml (>=0.10.2)
 Requires-Dist: tornado (>=6.2)
 Requires-Dist: watchdog (>=2.1.9)
 Project-URL: Documentation, https://shariff-faleel.com/experiment_server/documentation/
+Project-URL: Homepage, https://shariff-faleel.com/experiment_server/
 Project-URL: Repository, https://github.com/ahmed-shariff/experiment_server
 Description-Content-Type: text/markdown
 
@@ -85,18 +86,41 @@ See example `.toml` below for how the configuration can be defined.
 # The `configuration` table contains the settings of the study/experiment itself
 [configuration]
 # The `order` is an array of block names or an array of array of block names.
+# The `order` also can be a dictionary/table. If it is a dictionary/table, the keys should
+# be participant indices starting from 1. The values should be a list of block names.
+# The keys are the participant indices - when experiment manager is queries with a given
+# participant index, the dictionary/table will be used as a lookup table and the
+# corresponding list of blocks will be used. When a participant index larger than the
+# highest participant index is queries through experiment manager, the modulus of the
+# index will be used to determine which list of conditions should be used.
+# In the following example order with a table/dictionary, participant index 4 would get
+# the blocks assigned to participant index 1:
+# order = {1= ["conditionA", "conditionB", "conditionA", "conditionB"], 2= ["conditionB", "conditionA", "conditionB", "conditionA"], 3= ["conditionB", "conditionB", "conditionA", "conditionA"]}
 order = [["conditionA", "conditionB", "conditionA", "conditionB"]]
-# The `groups` and `within_groups` are optional keys that allows you to define how the
-# conditions specified in `order` will be managed. `groups` would dictate how the top 
-# level array of `order` will be handled. `within_groups` would dictate how the conditions
-# in the nested arrays (if specified) would be managed. These keys can have one 
-# of the following values.
+
+
+# The `groups_strategy` and `within_groups_strategy` are optional keys that allows you to
+# define how the conditions specified in `order` will be managed. `groups_strategy` would
+# dictate how the top level array of `order` will be handled. `within_groups_strategy`
+# would dictate how the conditions in the nested arrays (if specified) would be
+# managed. These keys can have one of the following values.
 # - "latin_square": Apply latin square to balance the values.
 # - "randomize": For each participant randomize the order of the values in the array.
 # - "as_is": Use the order of the values as specified.
 # When not specified, the default value is "as_is" for both keys.
-groups = "latin_square"
-within_groups= "randomize"
+groups_strategy = "latin_square"
+within_groups_strategy = "randomize"
+
+# The following are optional keys. `init_blocks` is a list of blocks which will be
+# appended to the start and `final_blocks` are a list of blocks that would be appended to
+# the end. The respective strategies dictate the ordering withing the list of init or
+# final blocks. For init and final blocks only the "randomize" and "as_is" are
+# supported. By default, their values are "as_is".
+init_blocks = ["initialBlock"]
+final_blocks = ["finalBlockA", "finalBlockB"]
+init_blocks_strategy = "as_is"
+final_blocks_strategy = "randomize"
+
 # The random seed to use for any randomization. Default seed is 0. The seed will be
 # the value of random_seed + participant_index
 random_seed = 0
@@ -146,6 +170,15 @@ See [toml spec](https://toml.io/en/v1.0.0) for more information on the format of
 The above config file, after being processed, would result in the following list of blocks for participant number 1:
 ```json
 [
+  {
+    "name": "initialBlock",
+    "config": {
+      "param1": 1,
+      "participant_index": 1,
+      "name": "initialBlock",
+      "block_id": 0
+    }
+  },
   {
     "name": "conditionB",
     "extends": "conditionA",
@@ -157,11 +190,11 @@ The above config file, after being processed, would result in the following list
       "param1": 1,
       "param2": [
         1,
-        2
+        3
       ],
       "participant_index": 1,
       "name": "conditionB",
-      "block_id": 0
+      "block_id": 1
     }
   },
   {
@@ -174,11 +207,11 @@ The above config file, after being processed, would result in the following list
         2
       ],
       "param3": [
-        3
+        1
       ],
       "participant_index": 1,
       "name": "conditionA",
-      "block_id": 1
+      "block_id": 2
     }
   },
   {
@@ -187,15 +220,15 @@ The above config file, after being processed, would result in the following list
       "trialsPerItem": 3,
       "param1": 1,
       "param2": [
-        1,
-        1
+        2,
+        3
       ],
       "param3": [
         2
       ],
       "participant_index": 1,
       "name": "conditionA",
-      "block_id": 2
+      "block_id": 3
     }
   },
   {
@@ -208,12 +241,30 @@ The above config file, after being processed, would result in the following list
       "trialsPerItem": 3,
       "param1": 1,
       "param2": [
-        3,
-        1
+        2,
+        3
       ],
       "participant_index": 1,
       "name": "conditionB",
-      "block_id": 3
+      "block_id": 4
+    }
+  },
+  {
+    "name": "finalBlockA",
+    "config": {
+      "param1": 1,
+      "participant_index": 1,
+      "name": "finalBlockA",
+      "block_id": 5
+    }
+  },
+  {
+    "name": "finalBlockB",
+    "config": {
+      "param1": 1,
+      "participant_index": 1,
+      "name": "finalBlockB",
+      "block_id": 6
     }
   }
 ]

{experiment_server-0.3.4 → experiment_server-0.3.5}/README.md

@@ -47,18 +47,41 @@ See example `.toml` below for how the configuration can be defined.
 # The `configuration` table contains the settings of the study/experiment itself
 [configuration]
 # The `order` is an array of block names or an array of array of block names.
+# The `order` also can be a dictionary/table. If it is a dictionary/table, the keys should
+# be participant indices starting from 1. The values should be a list of block names.
+# The keys are the participant indices - when experiment manager is queries with a given
+# participant index, the dictionary/table will be used as a lookup table and the
+# corresponding list of blocks will be used. When a participant index larger than the
+# highest participant index is queries through experiment manager, the modulus of the
+# index will be used to determine which list of conditions should be used.
+# In the following example order with a table/dictionary, participant index 4 would get
+# the blocks assigned to participant index 1:
+# order = {1= ["conditionA", "conditionB", "conditionA", "conditionB"], 2= ["conditionB", "conditionA", "conditionB", "conditionA"], 3= ["conditionB", "conditionB", "conditionA", "conditionA"]}
 order = [["conditionA", "conditionB", "conditionA", "conditionB"]]
-# The `groups` and `within_groups` are optional keys that allows you to define how the
-# conditions specified in `order` will be managed. `groups` would dictate how the top 
-# level array of `order` will be handled. `within_groups` would dictate how the conditions
-# in the nested arrays (if specified) would be managed. These keys can have one 
-# of the following values.
+
+
+# The `groups_strategy` and `within_groups_strategy` are optional keys that allows you to
+# define how the conditions specified in `order` will be managed. `groups_strategy` would
+# dictate how the top level array of `order` will be handled. `within_groups_strategy`
+# would dictate how the conditions in the nested arrays (if specified) would be
+# managed. These keys can have one of the following values.
 # - "latin_square": Apply latin square to balance the values.
 # - "randomize": For each participant randomize the order of the values in the array.
 # - "as_is": Use the order of the values as specified.
 # When not specified, the default value is "as_is" for both keys.
-groups = "latin_square"
-within_groups= "randomize"
+groups_strategy = "latin_square"
+within_groups_strategy = "randomize"
+
+# The following are optional keys. `init_blocks` is a list of blocks which will be
+# appended to the start and `final_blocks` are a list of blocks that would be appended to
+# the end. The respective strategies dictate the ordering withing the list of init or
+# final blocks. For init and final blocks only the "randomize" and "as_is" are
+# supported. By default, their values are "as_is".
+init_blocks = ["initialBlock"]
+final_blocks = ["finalBlockA", "finalBlockB"]
+init_blocks_strategy = "as_is"
+final_blocks_strategy = "randomize"
+
 # The random seed to use for any randomization. Default seed is 0. The seed will be
 # the value of random_seed + participant_index
 random_seed = 0
@@ -108,6 +131,15 @@ See [toml spec](https://toml.io/en/v1.0.0) for more information on the format of
 The above config file, after being processed, would result in the following list of blocks for participant number 1:
 ```json
 [
+  {
+    "name": "initialBlock",
+    "config": {
+      "param1": 1,
+      "participant_index": 1,
+      "name": "initialBlock",
+      "block_id": 0
+    }
+  },
   {
     "name": "conditionB",
     "extends": "conditionA",
@@ -119,11 +151,11 @@ The above config file, after being processed, would result in the following list
       "param1": 1,
       "param2": [
         1,
-        2
+        3
       ],
       "participant_index": 1,
       "name": "conditionB",
-      "block_id": 0
+      "block_id": 1
     }
   },
   {
@@ -136,11 +168,11 @@ The above config file, after being processed, would result in the following list
         2
       ],
       "param3": [
-        3
+        1
       ],
       "participant_index": 1,
       "name": "conditionA",
-      "block_id": 1
+      "block_id": 2
     }
   },
   {
@@ -149,15 +181,15 @@ The above config file, after being processed, would result in the following list
       "trialsPerItem": 3,
       "param1": 1,
       "param2": [
-        1,
-        1
+        2,
+        3
       ],
       "param3": [
         2
       ],
       "participant_index": 1,
       "name": "conditionA",
-      "block_id": 2
+      "block_id": 3
     }
   },
   {
@@ -170,12 +202,30 @@ The above config file, after being processed, would result in the following list
       "trialsPerItem": 3,
       "param1": 1,
       "param2": [
-        3,
-        1
+        2,
+        3
       ],
       "participant_index": 1,
       "name": "conditionB",
-      "block_id": 3
+      "block_id": 4
+    }
+  },
+  {
+    "name": "finalBlockA",
+    "config": {
+      "param1": 1,
+      "participant_index": 1,
+      "name": "finalBlockA",
+      "block_id": 5
+    }
+  },
+  {
+    "name": "finalBlockB",
+    "config": {
+      "param1": 1,
+      "participant_index": 1,
+      "name": "finalBlockB",
+      "block_id": 6
     }
   }
 ]

{experiment_server-0.3.4 → experiment_server-0.3.5}/experiment_server/_api.py

@@ -11,6 +11,14 @@ from experiment_server.utils import ExperimentServerExcetion, FileModifiedWatche
 
 class ParticipantState:
     def __init__(self, config, participant_index, active):
+        """
+        Track a single participant's progress through an experiment configuration.
+
+        Args:
+            config (List[Dict[str, Any]]): Ordered list of block dictionaries for this participant.
+            participant_index (int): 1-based participant index.
+            active (bool): True if participant is currently between START and END (inclusive of blocks).
+        """
         self.participant_index = participant_index
         self._block_id: int = -1
         self.config = config
@@ -18,10 +26,19 @@ class ParticipantState:
 
     @property
     def block_id(self) -> int:
+        """Current zero-based index of the active block, -1 if before START, len(config) if after END."""
         return self._block_id
 
     @block_id.setter
     def block_id(self, block_id: int):
+        """
+        Set the current block index and update the active flag.
+
+        If block_id < 0 -> mark as not active (before start).
+        If block_id >= len(config) -> mark as not active (after end).
+        Otherwise active = True.
+        An assertion ensures consistency between block_id and the block's own 'config.block_id'.
+        """
         if block_id < 0:
             self._block_id = -1
             self.active = False
@@ -36,30 +53,42 @@ class ParticipantState:
 
     @property
     def block(self) -> Dict[str, Any]|None:
+        """Return the current block dict or None if before START or after END."""
         if self.block_id >= len(self.config) or self.block_id < 0:
             return None
-        else:
-            return self.config[self.block_id]
+        return self.config[self.block_id]
 
     @property
     def block_name(self) -> str:
+        """Human-readable block position: 'START', 'END' or the current block name."""
         if self.block_id >= len(self.config):
             return "END"
-        elif self.block_id < 0:
+        if self.block_id < 0:
             return "START"
         return self.config[self.block_id]["name"]
 
     def move_to_next_block(self) -> str:
+        """Advance to the next block and return its block_name."""
         self.block_id += 1
         return self.block_name
 
-    def status_string(self):
-        return f'Participant index: {self.participant_index}    \nBlock: {self._block_id} / {len(self.config)}    \n Name: {self.block["name"] if self.block is not None else "N/A"}'
+    def status_string(self) -> str:
+        """Single-line status summary suitable for logs or simple UIs."""
+        name = self.block["name"] if self.block is not None else "N/A"
+        return f'Participant index: {self.participant_index}    \nBlock: {self._block_id} / {len(self.config)}    \n Name: {name}'
 
 
 class Experiment:
-    """Load and manage experiemnt from a local file."""
-    def __init__(self, config_file:str, default_participant_index:int=1) -> None:
+    """Load and manage an experiment configuration file and participant states."""
+
+    def __init__(self, config_file: str, default_participant_index: int = 1) -> None:
+        """
+        Initialize experiment state and watch the configuration file for changes.
+
+        Args:
+            config_file (str): Path to the TOML configuration file.
+            default_participant_index (int): Default 1-based index used when none is provided.
+        """
         assert default_participant_index > 0, "Default participant index should be >0"
         self.global_state: Dict[int, ParticipantState] = {}
         self.default_participant_index = default_participant_index
@@ -67,90 +96,99 @@ class Experiment:
         self.config_file = config_file
 
         if default_participant_index not in self.global_state:
-            self.global_state[default_participant_index] = ParticipantState(process_config_file(config_file, default_participant_index),
-                                                                            default_participant_index,
-                                                                            False)
+            self.global_state[default_participant_index] = ParticipantState(
+                process_config_file(config_file, default_participant_index),
+                default_participant_index,
+                False,
+            )
 
     def _config_file_modified_callback(self):
+        """Reload configurations for all known participants when the file changes."""
         logger.info("Reloading config")
         for participantState in self.global_state.values():
             config = process_config_file(self.config_file, participantState.participant_index)
             participantState.config = config
 
     def get_next_participant(self) -> int:
-        """Return the index of the next participant."""
+        """Allocate and return the next participant index (max existing + 1)."""
         new_participant_index = max(self.global_state.keys()) + 1
         self.add_participant_index(new_participant_index)
         return new_participant_index
 
     def add_participant_index(self, participant_index) -> bool:
-        """Add a participant with `participant_index`.
-        If `participant_index` already exists, returns False, else return True"""
+        """
+        Add a participant by index.
+
+        Returns True if added, False if the index already exists.
+        """
         if participant_index in self.global_state:
             return False
-        self.global_state[participant_index] = ParticipantState(process_config_file(self.config_file, participant_index),
-                                                                participant_index,
-                                                                False)
+        self.global_state[participant_index] = ParticipantState(
+            process_config_file(self.config_file, participant_index),
+            participant_index,
+            False,
+        )
         return True
 
     def get_participant_state(self, participant_index) -> ParticipantState:
+        """
+        Return the ParticipantState for the given index.
+
+        If participant_index is None, uses the default. Raises ExperimentServerExcetion if not present.
+        """
         if participant_index is None:
             participant_index = self.default_participant_index
         if participant_index not in self.global_state:
             raise ExperimentServerExcetion(f"participant with index {participant_index} is not set. Consider using `add_participant_index`")
         return self.global_state[participant_index]
 
-    def get_state(self, participant_index:int|None=None):
+    def get_state(self, participant_index:int|None=None) -> bool:
+        """Return whether the participant is active."""
         if participant_index is None:
             participant_index = self.default_participant_index
         return self.global_state[participant_index].active
 
     def move_to_next(self, participant_index:int|None=None) -> str:
-        """Moves the pointer to the current block to the next block for `participant_index`.
-        if `participant_index` is None, seld.default_participant_index is used.
-        """
+        """Advance the participant to the next block and return the new block_name."""
         if participant_index is None:
             participant_index = self.default_participant_index
         return self.global_state[participant_index].move_to_next_block()
 
     def get_config(self, participant_index:int|None=None) -> Union[Dict[str, Any], None]:
-        """Return the config of the current block for `participant_index`. 
-        if `participant_index` is None, seld.default_participant_index is used.
-        If the experiment has not started (`move_to_next` has not
-        been called atleast once), this will return `None`."""
+        """
+        Return the current block's config for the participant, or None if experiment not started or finished.
+        """
         if participant_index is None:
             participant_index = self.default_participant_index
         block = self.global_state[participant_index].block
         if block is None:
             return None
-        else:
-            return block["config"]
+        return block["config"]
 
     def reset_participant(self, participant_index:int|None=None) -> bool:
-        """Reset the participant's config to that was loaded from the file."""
+        """Reload the participant's configuration from file and replace their stored config."""
         if participant_index is None:
             participant_index = self.default_participant_index
         self.global_state[participant_index].config = process_config_file(self.config_file, participant_index)
         return True
 
     def get_blocks_count(self, participant_index:int|None=None) -> int:
-        """Return the total number of blocks."""
+        """Return the number of blocks for the participant."""
         if participant_index is None:
             participant_index = self.default_participant_index
         return len(self.global_state[participant_index].config)
 
     def get_all_configs(self, participant_index:int|None=None) -> List[dict]:
-        """Return all configs in order for `participant_index`.
-        if `participant_index` is None, seld.default_participant_index is used.
-        """
+        """Return the list of all block 'config' dicts for the participant in order."""
         if participant_index is None:
             participant_index = self.default_participant_index
         return [c["config"] for c in self.global_state[participant_index].config]
 
     def move_to_block(self, block_id: int, participant_index:int|None=None) -> str:
-        """For `participant_index` move the pointer of the current
-        block to the block in index a `block_id` in the list of
-        blocks. If `participant_index` is None, seld.default_participant_index is used.
+        """
+        Move the participant pointer to a specific block index and return its block_name.
+
+        block_id must be an integer.
         """
         assert isinstance(block_id, int), "`block` should be an int"
         if participant_index is None:
@@ -159,9 +197,10 @@ class Experiment:
         return self.global_state[participant_index].block_name
 
     def move_all_to_block(self, block_id: int) -> str:
-        """For active participants move the pointer of the current
-        block to the block in index a `block_id` in the list of
-        blocks.
+        """
+        Move every participant's pointer to `block_id`.
+
+        Returns the block_name of the first participant after the move.
         """
         assert isinstance(block_id, int), "`block` should be an int"
         for participantState in self.global_state.values():
@@ -169,12 +208,17 @@ class Experiment:
         return list(self.global_state.values())[0].block_name
 
 
-def _generate_config_json(config_file: Union[str, Path], participant_indices:Iterable[int], out_dir: Union[str, Path, None] = None) -> None:
+def _generate_config_json(config_file: Union[str, Path], participant_indices: Iterable[int], out_dir: Union[str, Path, None]=None) -> None:
     """
-    Write out the json config from the `config_file` for participants in `participant_indices`
-    in the `out_dir`. The `out_dir` should be a directory or should be None.
-    If it is None, it will write the config's, one line per participant. If the passed directory
-    does not exist, it will be created.
+    Emit the resolved JSON configuration for the given participant indices.
+
+    If out_dir is provided, writes one file per participant named "<config_stem>-participant_<i>.json".
+    If out_dir is None, writes each participant's JSON to stdout (one line per participant).
+
+    Args:
+        config_file: Path to the TOML configuration file.
+        participant_indices: Iterable of 1-based participant indices to generate.
+        out_dir: Optional directory to write files into. Created if missing.
     """
     if out_dir is not None:
         out_dir = Path(out_dir)

{experiment_server-0.3.4 → experiment_server-0.3.5}/experiment_server/_client.py

@@ -6,6 +6,34 @@ from experiment_server.utils import ExperimentServerExcetion
 
 
 class Client:
+    """
+    HTTP client for the Experiment Server API.
+
+    Usage:
+    - Instantiate with optional server_host and server_port.
+    - Methods operate on a per-participant basis when applicable (provide
+      participant_index or omit to use the server's default participant).
+
+    Parameters
+    - server_host (str): Hostname or IP of the server (default "127.0.0.1").
+    - server_port (str|int): Port of the server (default "5000").
+
+    Return value for API methods
+    - All public API methods return a tuple (success: bool, data: dict|str).
+      On success data is the parsed JSON response (or "" if empty). On failure
+      success is False and data contains an error message.
+
+    Main methods
+    - move_to_next(participant_index=None)
+    - get_config(participant_index=None)
+    - server_is_active(participant_index=None)
+    - get_blocks_count(participant_index=None)
+    - get_all_configs(participant_index=None)
+    - move_to_block(block_id, participant_index=None)
+    - new_participant()
+    - add_participant(participant_index)
+    - shutdown()
+    """
     def __init__(self, server_host:str ="127.0.0.1", server_port:Union[str, int]="5000") -> None:
         self._server_url = f"http://{server_host}:{server_port}"