experiment_server 0.3.0__tar.gz → 0.3.2__tar.gz

{experiment_server-0.3.0 → experiment_server-0.3.2}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.1
 Name: experiment-server
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -30,12 +31,16 @@ Requires-Dist: tabulate (>=0.8.9)
 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: Repository, https://github.com/ahmed-shariff/experiment_server
 Description-Content-Type: text/markdown
 
 # Overview
 
 This is a Python application that allows you to create/maintain/manage study configurations away from your implementations. `experiment-server` has several different interfaces (see below) to allow using it in a range of different scenarios. I've used it with Python, js and [Unity projects](https://github.com/ahmed-shariff/experiment_server/wiki/Using-with-Unity). See the [wiki](https://github.com/ahmed-shariff/experiment_server/wiki) for examples.
 
+Documentation is available at [https://shariff-faleel.com/experiment_server/](https://shariff-faleel.com/experiment_server/)
+
 # Content
 
 - [Overview](#overview)
@@ -230,20 +235,35 @@ $ experiment-server run sample_config.toml
 See more options with `--help`
 
 The server exposes the following REST API:
-- [GET] `/api/blocks-count` - Return the number of blocks in the configuration loaded.
+
+- [GET] `/api/blocks-count` / `/api/blocks-count/:participant-id` - Return the number of blocks in the configuration loaded. For a given config, the `blocks-count` will be the same for all participants. 
+
 - [GET] `/api/block-id` / `/api/block-id/:participant-id` - Returns the current block-id. If `participant-id` is provided, the blcok-id of the participant will be returned, if not the default participant's block-id will be returned. Note that the block-id is 0 indexed. i.e., the first block's block-id is 0. 
+
 - [GET] `/api/active` / `/api/active/:participant-id` - Returns the status for `participant-id`, if `participant-id` is not provided, will return the status of the default participant. Will be `false` if the participant was just initialized or the participant has gone through all blocks. To initialize the participant's status (or move to a given block), use the `move-to-next` or `move-to-block` endpoints.
-- [GET] `/api/config` / `api/active/:participant-id` - Return the config for `participant-id`, if `participant-id` is not provided, will return the config for the default participant.
+
+- [GET] `/api/config` / `api/config/:participant-id` - Return the config for `participant-id`, if `participant-id` is not provided, will return the config for the default participant.
+
 - [GET] `/api/summary-data` / `/api/summary-data/:participant-id` - Returns the summary of the configs for `participant-id`, if `participant-id` is not provided, returns the summary of the configs for the default participant. Currently, the summary is a JSON with the following keys 
+
   - "participant_index"
+
   - "config_length"
-- [GET] `/api/all-configs` / `/api/all-configs/:participant-id` - Returns all the configs as a list for the `participant-id`, if `participant-id` is not provided, returns the configs for the default participant. This is akin having the results of the `config` endpoint in one list.
+
+- [GET] `/api/all-configs` / `/api/all-configs/:participant-id` - Returns all the configs as a list for the `participant-id`, if `participant-id` is not provided, returns the configs for the default participant.This is akin having all the results from calling the `config` endpoint for each block in one list.
+
 - [GET] `/api/status-string` / `/api/status-string/:participant-id` - Returns status string for `participant-id`, if `participant-id` is not provided, returns statu string the default participant.
+
 - [POST] `/api/move-to-next` / `/api/move-to-next/:participant-id` - Move `participant-id` to the next block, if `participant-id` is not provided, move the default participant to the next block. If the participant was not initialized (`active` is false), will make be marked as active (`active` will be set to true). If the block the participant was in was the last block, they will be marked as not active (`active` will be set to false).
+
 - [POST] `/api/move-to-block/:block-id` / `/api/move-to-block/:participant-id/:block-id` - Move `participant-id` to the block number indicated by `block-id`, if `participant-id` is not provided, move the default participant to the block number indicated by `block-id`. If the participant was not initialized (`active` is false), will make be marked as active (`active` will be set to true). Will fail if the `block-id` is below 0 or above the length of the config.
+
 - [POST] `/api/move-all-to-block/:block-id` - Move all active participants (`active` returns true) to the block number indicated by `block-id`.
+
 - [POST] `/api/shutdown` - Shuts-down the server.
+
 - [PUT] `/api/new-participant` - Adds a new participant and returns the new participant-id. The new participant-id will be the largest current participant-id +1.
+
 - [PUT] `/api/add-participant/:participant-id` - Add a new participant with `participant-id`. If there is already a participant with the `participant-id`, this will fail. 
 
 For a Python application, `experiment_server.Client` can be used to access configs from the server. Also, the server can be launched programmatically using `experiment_server.server_process` which returns a [`Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process) object.
@@ -252,7 +272,7 @@ For a Python application, `experiment_server.Client` can be used to access confi
 
 The server also provides a simple web interface, which can be accessed at `/` or `/index`. This interface allows to manage and monitor the flow of the experiment:
 
-![web UI screenshot](media/screenshot.png)
+![web UI screenshot](https://raw.githubusercontent.com/ahmed-shariff/experiment_server/master/media/screenshot.png)
 
 
 ## Loading experiment through API

{experiment_server-0.3.0 → experiment_server-0.3.2}/README.md

@@ -2,6 +2,8 @@
 
 This is a Python application that allows you to create/maintain/manage study configurations away from your implementations. `experiment-server` has several different interfaces (see below) to allow using it in a range of different scenarios. I've used it with Python, js and [Unity projects](https://github.com/ahmed-shariff/experiment_server/wiki/Using-with-Unity). See the [wiki](https://github.com/ahmed-shariff/experiment_server/wiki) for examples.
 
+Documentation is available at [https://shariff-faleel.com/experiment_server/](https://shariff-faleel.com/experiment_server/)
+
 # Content
 
 - [Overview](#overview)
@@ -196,20 +198,35 @@ $ experiment-server run sample_config.toml
 See more options with `--help`
 
 The server exposes the following REST API:
-- [GET] `/api/blocks-count` - Return the number of blocks in the configuration loaded.
+
+- [GET] `/api/blocks-count` / `/api/blocks-count/:participant-id` - Return the number of blocks in the configuration loaded. For a given config, the `blocks-count` will be the same for all participants. 
+
 - [GET] `/api/block-id` / `/api/block-id/:participant-id` - Returns the current block-id. If `participant-id` is provided, the blcok-id of the participant will be returned, if not the default participant's block-id will be returned. Note that the block-id is 0 indexed. i.e., the first block's block-id is 0. 
+
 - [GET] `/api/active` / `/api/active/:participant-id` - Returns the status for `participant-id`, if `participant-id` is not provided, will return the status of the default participant. Will be `false` if the participant was just initialized or the participant has gone through all blocks. To initialize the participant's status (or move to a given block), use the `move-to-next` or `move-to-block` endpoints.
-- [GET] `/api/config` / `api/active/:participant-id` - Return the config for `participant-id`, if `participant-id` is not provided, will return the config for the default participant.
+
+- [GET] `/api/config` / `api/config/:participant-id` - Return the config for `participant-id`, if `participant-id` is not provided, will return the config for the default participant.
+
 - [GET] `/api/summary-data` / `/api/summary-data/:participant-id` - Returns the summary of the configs for `participant-id`, if `participant-id` is not provided, returns the summary of the configs for the default participant. Currently, the summary is a JSON with the following keys 
+
   - "participant_index"
+
   - "config_length"
-- [GET] `/api/all-configs` / `/api/all-configs/:participant-id` - Returns all the configs as a list for the `participant-id`, if `participant-id` is not provided, returns the configs for the default participant. This is akin having the results of the `config` endpoint in one list.
+
+- [GET] `/api/all-configs` / `/api/all-configs/:participant-id` - Returns all the configs as a list for the `participant-id`, if `participant-id` is not provided, returns the configs for the default participant.This is akin having all the results from calling the `config` endpoint for each block in one list.
+
 - [GET] `/api/status-string` / `/api/status-string/:participant-id` - Returns status string for `participant-id`, if `participant-id` is not provided, returns statu string the default participant.
+
 - [POST] `/api/move-to-next` / `/api/move-to-next/:participant-id` - Move `participant-id` to the next block, if `participant-id` is not provided, move the default participant to the next block. If the participant was not initialized (`active` is false), will make be marked as active (`active` will be set to true). If the block the participant was in was the last block, they will be marked as not active (`active` will be set to false).
+
 - [POST] `/api/move-to-block/:block-id` / `/api/move-to-block/:participant-id/:block-id` - Move `participant-id` to the block number indicated by `block-id`, if `participant-id` is not provided, move the default participant to the block number indicated by `block-id`. If the participant was not initialized (`active` is false), will make be marked as active (`active` will be set to true). Will fail if the `block-id` is below 0 or above the length of the config.
+
 - [POST] `/api/move-all-to-block/:block-id` - Move all active participants (`active` returns true) to the block number indicated by `block-id`.
+
 - [POST] `/api/shutdown` - Shuts-down the server.
+
 - [PUT] `/api/new-participant` - Adds a new participant and returns the new participant-id. The new participant-id will be the largest current participant-id +1.
+
 - [PUT] `/api/add-participant/:participant-id` - Add a new participant with `participant-id`. If there is already a participant with the `participant-id`, this will fail. 
 
 For a Python application, `experiment_server.Client` can be used to access configs from the server. Also, the server can be launched programmatically using `experiment_server.server_process` which returns a [`Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process) object.
@@ -218,7 +235,7 @@ For a Python application, `experiment_server.Client` can be used to access confi
 
 The server also provides a simple web interface, which can be accessed at `/` or `/index`. This interface allows to manage and monitor the flow of the experiment:
 
-![web UI screenshot](media/screenshot.png)
+![web UI screenshot](https://raw.githubusercontent.com/ahmed-shariff/experiment_server/master/media/screenshot.png)
 
 
 ## Loading experiment through API

{experiment_server-0.3.0 → experiment_server-0.3.2}/experiment_server/__init__.py

@@ -28,4 +28,4 @@ from experiment_server._server import server_process
 from experiment_server._client import Client
 from experiment_server._api import Experiment
 
-__all__ = [server_process, Client, Experiment]
+__all__ = ['server_process', 'Client', 'Experiment']

{experiment_server-0.3.0 → experiment_server-0.3.2}/experiment_server/_client.py

@@ -34,38 +34,71 @@ class Client:
         return self._request(end_point, "PUT")
 
     def move_to_next(self, participant_index:int|None=None) -> Tuple[bool, dict]:
+        """ 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."""
         url = _process_participant_index("move-to-next", participant_index)
         return self._post(url)
 
     def get_config(self, participant_index:int|None=None) -> Tuple[bool, dict]:
+        """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`."""
         url = _process_participant_index("config", participant_index)
         return self._get(url)
 
-    def server_is_active(self) -> Tuple[bool, dict]:
-        return self._get("active")
+    def server_is_active(self, participant_index:int|None=None) -> Tuple[bool, dict]:
+        """Returns the status for `participant-id`, if
+        `participant-id` is not provided, will return the status of
+        the default participant. Will be `false` if the participant
+        was just initialized or the participant has gone through all
+        blocks. To initialize the participant's status (or move to a
+        given block), use the `move-to-next` or `move-to-block`"""
+        url = _process_participant_index("active", participant_index)
+        return self._get(url)
     
     def get_blocks_count(self, participant_index:int|None=None) -> Tuple[bool, dict]:
+        """Return the number of blocks in the configuration
+        loaded. For a given config, the `blocks-count` will be the
+        same for all participants."""
         url = _process_participant_index("blocks-count", participant_index)
         return self._get(url)
 
     def get_all_configs(self, participant_index:int|None=None) -> Tuple[bool, dict]:
+        """Returns all the configs as a list for the `participant_index`,
+        if `participant_index` is not provided, returns the configs for
+        the default participant. This is akin having all the results
+        from calling `config` for each block in one list."""
         url = _process_participant_index("all-configs", participant_index)
         return self._get(url)
 
     def move_to_block(self, block_id:int, participant_index:int|None=None) -> Tuple[bool, dict]:
+        """Move `participant-id` to the block number indicated by
+        `block_id`, if `participant_index` is not provided, move the
+        default participant to the block number indicated by
+        `block_id`. If the participant was not initialized (`active`
+        is false), will make be marked as active (`active` will be set
+        to true). Will fail if the `block_id` is below 0 or above the
+        length of the config."""
         assert isinstance(block_id, int), "`block` should be a int"
         url = _process_participant_index("move-to-block", participant_index)
         return self._post(f"{url}/{block_id}")
 
     def new_participant(self) -> Tuple[bool, dict]:
+        """Adds a new participant and returns the new
+        participant_index. The new participant_index will be the largest
+        current participant_index +1."""
         return self._put("new-participant");
 
     def add_participant(self, participant_index:int) -> Tuple[bool, dict]:
+        """Add a new participant with `participant_index`. If there is already
+        a participant with the `participant_index`, this will fail. """
         assert participant_index is not None
         url = _process_participant_index("add-participant", participant_index)
         return self._put(url);
 
     def shutdown(self) -> Tuple[bool, dict]:
+        """Shuts down the server."""
         return self._post("shutdown")
 
 

{experiment_server-0.3.0 → experiment_server-0.3.2}/experiment_server/_server.py

@@ -43,6 +43,13 @@ def _server(config_file, default_participant_index, host="127.0.0.1", port=5000)
 
 
 def server_process(config_file, default_participant_index=None, host="127.0.0.1", port="5000"):
+    """Returns a Process object which can be used to launch experiment_server.
+    For example:
+    ```py
+    p = server_process(config_file=config_file)
+    p.start()
+    ```
+    """
     p = Process(target=_server,
                 kwargs={
                     "default_participant_index":default_participant_index,
@@ -275,7 +282,7 @@ class ExperimentHandler(RequestHandler):
             return
 
         if action == "blocks-count":
-            self.write(json.dumps(self.experiment.get_blocks_count()))
+            self.write(json.dumps(self.experiment.get_blocks_count(participant_id)))
         elif action == "block-id":
             self.write(json.dumps(self.experiment.get_participant_state(participant_id).block_id))
         elif action == "active":

{experiment_server-0.3.0 → experiment_server-0.3.2}/experiment_server/cli.py

@@ -56,8 +56,21 @@ def generate_config_json(config_file, participant_index, participant_range, out_
 @cli.command(aliases=["n", "new"])
 @click.argument("new-file-location")
 def new_config_file(new_file_location):
-    """Create a new config file."""
+    """Create a new config file.
+
+    If parameter does not end with `.toml` assums it is a directory and create a directory.
+    If parameter is directory, creates a file named `new_config.toml` in the directory.
+    If parents do not exists, create them all!.
+    """
     out_location = Path(new_file_location)
+
+    if out_location.suffix is not ".toml":
+        if out_location.exists():
+            logger.error(f"{out_location} exists and does not end with `.toml`")
+            return
+        else:
+            out_location.mkdir(parents=True, exist_ok=True)
+
     if out_location.is_dir():
         out_location = out_location / "new_config.toml"
 

{experiment_server-0.3.0 → experiment_server-0.3.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "experiment_server"
-version = "0.3.0"
+version = "0.3.2"
 description = "Server for experiments to get configuarations from"
 
 license = "MIT"
@@ -11,6 +11,9 @@ authors = ["Ahmed Shariff <shariff.mfa@outlook.com>"]
 readme = "README.md"
 
 keywords = [ "experiment", "study-design" ]
+homepage = "https://shariff-faleel.com/experiment_server/"
+documentation = "https://shariff-faleel.com/experiment_server/documentation/"
+repository = "https://github.com/ahmed-shariff/experiment_server"
 
 classifiers = [
     "Development Status :: 1 - Planning",
@@ -53,6 +56,10 @@ deepdiff = ">=5.8.1"
 [tool.poetry.group.dev.dependencies]
 mypy = ">=0.990"
 debugpy = ">=1.6.3"
+mkdocs = "^1.5.3"
+pymdown-extensions = "^10.7.1"
+mkdocstrings = {extras = ["python"], version = "^0.24.1"}
+mkdocs-material = "^9.5.15"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]