cave-utils 2.0.0b3__tar.gz → 2.0.2__tar.gz

{cave_utils-2.0.0b3 → cave_utils-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cave_utils
-Version: 2.0.0b3
+Version: 2.0.2
 Summary: Python wrapper for api use in the cave_app
 Author-email: Connor Makowski <conmak@mit.edu>
 Project-URL: Homepage, https://github.com/mit-cave/cave_utils
@@ -80,9 +80,8 @@ pip install cave_utils
 
 2. Remove `cave_utils` from the root `requirements.txt` file
 
-3. In your cave_app, set `LIVE_API_VALIDATION=True` in the `.env` file
-    - This will validate your data every time an api command is called for each session
-    - Outputs will be stored in `logs/validation/{session_name}.log`
+3. In your cave_app, set `LIVE_API_VALIDATION_PRINT=True` in the `.env` file
+    - This will validate your data every time an API command is called for each session
 
 4. Use the following command to run your cave_app:
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils"`
@@ -94,7 +93,7 @@ pip install cave_utils
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils" -it`
 2. Then install cave utils in the docker container:
     `pip install -e /cave_utils`
-3. Then run some tests (eg `validate_all_examples.py`): 
+3. Then run some tests (eg `validate_all_examples.py`):
     `python cave_api/tests/validate_all_examples.py`
 
 # Generate Documentation

{cave_utils-2.0.0b3 → cave_utils-2.0.2}/README.md

@@ -64,9 +64,8 @@ pip install cave_utils
 
 2. Remove `cave_utils` from the root `requirements.txt` file
 
-3. In your cave_app, set `LIVE_API_VALIDATION=True` in the `.env` file
-    - This will validate your data every time an api command is called for each session
-    - Outputs will be stored in `logs/validation/{session_name}.log`
+3. In your cave_app, set `LIVE_API_VALIDATION_PRINT=True` in the `.env` file
+    - This will validate your data every time an API command is called for each session
 
 4. Use the following command to run your cave_app:
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils"`
@@ -78,7 +77,7 @@ pip install cave_utils
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils" -it`
 2. Then install cave utils in the docker container:
     `pip install -e /cave_utils`
-3. Then run some tests (eg `validate_all_examples.py`): 
+3. Then run some tests (eg `validate_all_examples.py`):
     `python cave_api/tests/validate_all_examples.py`
 
 # Generate Documentation
@@ -102,4 +101,4 @@ pip install cave_utils
     - `pyproject.toml`
 3. Update the release
     - `source venv/bin/activate`
-    - `./update_version.sh`
+    - `./update_version.sh`

{cave_utils-2.0.0b3 → cave_utils-2.0.2}/cave_utils/api/__init__.py

@@ -23,6 +23,7 @@ from cave_utils.api.mapFeatures import mapFeatures
 from cave_utils.api.groupedOutputs import groupedOutputs
 import type_enforced
 
+
 @type_enforced.Enforcer
 class Root(ApiValidator):
     """
@@ -45,58 +46,33 @@ class Root(ApiValidator):
         **kwargs,
     ):
         """
-        Required Arguments:
-
-        - `settings:
-            - Type: dict
-            - What: General settings for your application.
-            - Note: 'settings.iconUrl' is the only required field in `settings`
-            - See: `cave_utils.api.settings`
-        - `appBar`:
-            - Type: dict
-            - What: Settings for the app bar.
-            - Note: 'appBar.data' is required, and should have at least one item in it.
-            - See: `cave_utils.api.appBar`
-
-        Optional Arguments:
+        Arguments:
 
-        - `panes`:
-            - Type: dict
-            - What: Configure panes for your application.
-            - Default: `{}`
-            - See: `cave_utils.api.panes`
-        - `pages`:
-            - Type: dict
-            - What: Configure pages for your application.
-            - Default: `{}`
-            - See: `cave_utils.api.pages`
-        - `maps`:
-            - Type: dict
-            - What: Configure map views and settings for your application.
-            - Default: `{}`
-            - See: `cave_utils.api.maps`
-        - `mapFeatures`:
-            - Type: dict
-            - What: Configure map features (interactive items on the map) for your application.
-            - Default: `{}`
-            - See: `cave_utils.api.mapFeatures`
-        - `groupedOutputs`:
-            - Type: dict
-            - What: Configure data that can be sliced and diced for charts and tables based on arbitrary groups.
-            - Default: `{}`
-            - See: `cave_utils.api.groupedOutputs`
-        - `globalOutputs`:
-            - Type: dict
-            - What: Configure data that is general to the entire application and can be compared across sessions.
-            - Default: `{}`
-            - See: `cave_utils.api.globalOutputs`
-        - `extraKwargs`:
-            - Type: dict
-            - What: Special arguments to be passed to the server.
-            - Default: `{}`
-            - See: `cave_utils.api.extraKwargs`
+        * **`settings`**: `[dict]` → General settings for your application.
+            * **Note**: `settings.iconUrl` is the only required field in `settings`
+            * **See**: `cave_utils.api.settings`
+        * **`appBar`**: `[dict]` → Configure actions for your app bar(s).
+            * **Note**: `appBar.data` is required and should have at least one item in it.
+            * **See**: `cave_utils.api.appBar`
+        * **`panes`**: `[dict]` = `{}` → Configure panes for your application.
+            * **See**: `cave_utils.api.panes`
+        * **`pages`**: `[dict]` = `{}` → Configure pages for your application.
+            * **See**: `cave_utils.api.pages`
+        * **`maps`**: `[dict]` = `{}` → Configure map views and settings for your application.
+            * **See**: `cave_utils.api.maps`
+        * **`mapFeatures`**: `[dict]` = `{}` →
+            * Configure map features (interactive items on the map) for your application.
+            * **See**: `cave_utils.api.mapFeatures`
+        * **`groupedOutputs`**: `[dict]` = `{}` →
+            * Configure data that can be sliced and diced for charts and tables based on arbitrary groups.
+            * **See**: `cave_utils.api.groupedOutputs`
+        * **`globalOutputs`**: `[dict]` = `{}` →
+            * Configure data that is general to the entire application and can be compared across sessions.
+            * **See**: `cave_utils.api.globalOutputs`
+        * **`extraKwargs`**: `[dict]` = `{}` → Special arguments to be passed to the server.
+            * **See**: `cave_utils.api.extraKwargs`
         """
-        kwargs = {k:v for k,v in kwargs.items() if k != 'associated'}
+        kwargs = {k: v for k, v in kwargs.items() if k != "associated"}
         return {
             "kwargs": kwargs,
             "accepted_values": {},
@@ -141,7 +117,13 @@ class Root(ApiValidator):
         maps_data = self.data.get("maps", dict())
         maps_validMapIds = []
         if maps_data != {}:
-            maps(data=maps_data, log=self.log, prepend_path=["maps"], mapFeatures_feature_props=mapFeatures_feature_props, **kwargs)
+            maps(
+                data=maps_data,
+                log=self.log,
+                prepend_path=["maps"],
+                mapFeatures_feature_props=mapFeatures_feature_props,
+                **kwargs,
+            )
             maps_validMapIds = list(maps_data.get("data", {}).keys())
         # Validate globalOutputs
         globalOutputs_data = self.data.get("globalOutputs", dict())
@@ -155,7 +137,7 @@ class Root(ApiValidator):
             )
             globalOuputs_validPropIds = list(globalOutputs_data.get("values", {}).keys())
         # Validate groupedOutputs
-        groupedOutputs_data = self.data.get("groupedOutputs",dict())
+        groupedOutputs_data = self.data.get("groupedOutputs", dict())
         groupedOutputs_validLevelIds = {}
         groupedOutputs_validStatIds = {}
         groupedOutputs_validGroupIds = {}
@@ -168,15 +150,24 @@ class Root(ApiValidator):
             )
             # Populate valid ids for each relevant groupedOutput to be used in pages.
             try:
-                groupedOutputs_validLevelIds = {k:list(v.get('levels').keys()) for k,v in groupedOutputs_data.get("groupings", {}).items()}
+                groupedOutputs_validLevelIds = {
+                    k: list(v.get("levels").keys())
+                    for k, v in groupedOutputs_data.get("groupings", {}).items()
+                }
             except:
                 pass
             try:
-                groupedOutputs_validStatIds = {k:list(v.get('stats').keys()) for k,v in groupedOutputs_data.get("data", {}).items()}
+                groupedOutputs_validStatIds = {
+                    k: list(v.get("stats").keys())
+                    for k, v in groupedOutputs_data.get("data", {}).items()
+                }
             except:
                 pass
             try:
-                groupedOutputs_validGroupIds = {k:list(v.get('groupLists').keys()) for k,v in groupedOutputs_data.get("data", {}).items()}
+                groupedOutputs_validGroupIds = {
+                    k: list(v.get("groupLists").keys())
+                    for k, v in groupedOutputs_data.get("data", {}).items()
+                }
             except:
                 pass
         # Validate pages
@@ -184,8 +175,8 @@ class Root(ApiValidator):
         page_validPageIds = []
         if pages_data != {}:
             pages(
-                data=pages_data, 
-                log=self.log, 
+                data=pages_data,
+                log=self.log,
                 prepend_path=["pages"],
                 # Special Kwargs to validate globalOutputs, groupedOutputs and maps are valid:
                 globalOuputs_validPropIds=globalOuputs_validPropIds,
@@ -193,18 +184,18 @@ class Root(ApiValidator):
                 groupedOutputs_validLevelIds=groupedOutputs_validLevelIds,
                 groupedOutputs_validStatIds=groupedOutputs_validStatIds,
                 groupedOutputs_validGroupIds=groupedOutputs_validGroupIds,
-                **kwargs
+                **kwargs,
             )
             page_validPageIds = list(pages_data.get("data", {}).keys())
         # Validate appBar
         appBar_data = self.data.get("appBar", dict())
         if appBar_data != {}:
             appBar(
-                data=appBar_data, 
-                log=self.log, 
-                prepend_path=["appBar"], 
+                data=appBar_data,
+                log=self.log,
+                prepend_path=["appBar"],
                 # Special kwargs to validate panes and pages are valid:
                 page_validPageIds=page_validPageIds,
                 pane_validPaneIds=pane_validPaneIds,
-                **kwargs
-            )
+                **kwargs,
+            )

cave_utils-2.0.2/cave_utils/api/appBar.py

@@ -0,0 +1,129 @@
+"""
+The app bar is a key element of the CAVE App, positioned on the left or
+right side of the screen. It provides actions that allow users to
+navigate between [pages][], launch [panes][], and interact with the
+CAVE API through [predefined][] or [custom][] commands.
+
+If specified, both left and right side app bars can be displayed
+simultaneously.
+
+[pages]: pages.html
+[panes]: panes.html
+[predefined]: #appBar_data_star.spec
+[custom]: #appBar_data_star.spec
+"""
+from cave_utils.api_utils.validator_utils import ApiValidator, CustomKeyValidator
+import type_enforced
+
+
+@type_enforced.Enforcer
+class appBar(ApiValidator):
+    """
+    The app bar is located under the path **`appBar`**.
+    """
+
+    @staticmethod
+    def spec(data: dict = dict(), **kwargs):
+        """
+        @private
+        Arguments:
+
+        * **`data`**: `[dict]` = `{}` → The data to pass to `appBar.data.*`.
+        """
+        return {"kwargs": kwargs, "accepted_values": {}}
+
+    def __extend_spec__(self, **kwargs):
+        data = self.data.get("data", {})
+        CustomKeyValidator(
+            data=data, log=self.log, prepend_path=["data"], validator=appBar_data_star, **kwargs
+        )
+
+
+@type_enforced.Enforcer
+class appBar_data_star(ApiValidator):
+    """
+    The app bar data is located under the path **`appBar.data`**.
+    """
+
+    @staticmethod
+    def spec(
+        icon: str,
+        type: str,
+        bar: str,
+        variant: [str, None] = None,
+        color: [str, None] = None,
+        order: [dict, None] = None,
+        apiCommand: [str, None] = None,
+        apiCommandKeys: [list, None] = None,
+        **kwargs,
+    ):
+        """
+        Arguments:
+
+        * **`icon`**: `[str]` → An icon to display in the center of the action element.
+            * **Note**: It must be a valid icon name from the [react-icons][] bundle, preceded by the abbreviated name of the icon library source.
+            * **Example**: `"md/MdRocket"`.
+        * **`type`**: `[str]` → The type of object displayed when the action is triggered.
+            * **Accepted Values**:
+                * `"session"`: The Session Pane
+                * `"settings"`: The Application Settings Pane
+                * `"button"`: A button that allows you to send a command to the CAVE API
+                * `"pane"`: A [custom pane][]
+                * `"page"`: A [page][]
+        * **`bar`**: `[str]` → The location of the action element.
+            * **Accepted Values**:
+                * `"upperLeft"`: Upper section of the left-side bar
+                * `"lowerLeft"`: Lower section of the left-side bar
+                * `"upperRight"`: Upper section of the right-side bar
+                * `"lowerRight"`: Lower section of the right-side bar
+        * **`variant`**: `[str]` = `None` → The variant of the button.
+            * **Accepted Values**:
+                * When **`type`** == `"pane"`:
+                    * `"modal"`: A [modal pane][]
+                    * `"wall"`: A [wall pane][]
+                * Otherwise:
+                    * `None`
+        * **`color`**: `[str]` = `<system-default-value>` &rarr;
+            * The color of the button. If omitted, the default value is set by the system.
+            * **Note**: It must be a valid RGBA string.
+            * **Example**: `"rgba(255, 255, 255, 1)"`.
+        * **`apiCommand`**: `[str]` = `None` &rarr; The name of the [API command][] to trigger.
+        * **`apiCommandKeys`**: `[list]` = `None` &rarr;
+            * The root API keys to pass to your `execute_command` function if an
+            `apiCommand` is provided. If omitted, all API keys are
+            passed to `execute_command`.
+
+        [page]: pages.html
+        [pane]: panes.html
+        [modal pane]: panes.html
+        [wall pane]: panes.html
+        [API command]: #appBar_data_star.spec
+        [react-icons]: https://react-icons.github.io/react-icons/search
+        """
+        return {
+            "kwargs": kwargs,
+            "accepted_values": {
+                "type": ["session", "settings", "button", "pane", "page"],
+                "variant": ["modal", "wall"] if type == "pane" else [],
+                "bar": ["upperLeft", "lowerLeft", "upperRight", "lowerRight"],
+            },
+        }
+
+    def __extend_spec__(self, **kwargs):
+        color = self.data.get("color")
+        if color:
+            self.__check_rgba_string_valid__(rgba_string=color, prepend_path=["color"])
+        # Validate pageIds
+        bar_type = self.data.get("type")
+        if bar_type == "page":
+            self.__check_subset_valid__(
+                subset=[kwargs.get("CustomKeyValidatorFieldId")],
+                valid_values=kwargs.get("page_validPageIds", []),
+                prepend_path=[],
+            )
+        if bar_type == "pane":
+            self.__check_subset_valid__(
+                subset=[kwargs.get("CustomKeyValidatorFieldId")],
+                valid_values=kwargs.get("pane_validPaneIds", []),
+                prepend_path=[],
+            )

cave_utils-2.0.2/cave_utils/api/extraKwargs.py

@@ -0,0 +1,33 @@
+"""
+Optionally, pass special arguments to adjust some options related to
+how the CAVE API server handles data.
+"""
+from cave_utils.api_utils.validator_utils import ApiValidator
+import type_enforced
+
+
+@type_enforced.Enforcer
+class extraKwargs(ApiValidator):
+    """
+    The special arguments are located under the path **`extraKwargs`**.
+    """
+
+    @staticmethod
+    def spec(wipeExisting: bool = False, **kwargs):
+        """
+        Arguments:
+
+        * **`wipeExisting`**: `[bool]` = `False` →
+            * If set to `True`, all existing data will be deleted just
+            before session data updates are merged. By default (set to
+            `False`), the CAVE API will merge new data with existing
+            data.
+            * **Note**: The data is merged at the root level. In this
+            case, if you update an item in `settings`, the entire
+            `settings` object must be present when you return
+            `session_data`.
+        """
+        return {
+            "kwargs": kwargs,
+            "accepted_values": {},
+        }

{cave_utils-2.0.0b3 → cave_utils-2.0.2}/cave_utils/api/globalOutputs.py

@@ -1,6 +1,6 @@
-"""
-Create global outputs for that allow for simple charts and tables. 
-These outputs should be general to the entire application and can be compared across sessions.
+"""Create outputs that allow for simple charts and tables to present some totalization or global outcome of the data.
+
+These outputs should be general to the entire application and they can be compared across sessions.
 """
 from cave_utils.api_utils.validator_utils import ApiValidator, CustomKeyValidator
 from cave_utils.api_utils.general import props, values, layout
@@ -10,34 +10,24 @@ import type_enforced
 @type_enforced.Enforcer
 class globalOutputs(ApiValidator):
     """
-    ## Api Path: globalOutputs
+    The global outputs data is located under the path **`globalOutputs`**.
     """
 
     @staticmethod
-    def spec(
-        props: dict, values: [dict, None] = None, layout: [dict, None] = None, **kwargs
-    ):
+    def spec(props: dict, values: [dict, None] = None, layout: [dict, None] = None, **kwargs):
         """
-        Required Arguments:
-
-        - `props`:
-            - Type: dict
-            - What: The props that will be rendered as global outputs.
-            - See: `cave_utils.api_utils.general.props`
-        - `values`:
-            - Type: dict
-            - What: The values that will be passed to the props.
-            - Required: False
-            - See: `cave_utils.api_utils.general.values`
+        Arguments:
 
-        Optional Arguments:
-
-        - `layout`:
-            - Type: dict
-            - What: The layout of the pane.
-            - Required: False
-            - See: `cave_utils.api_utils.general.layout`
+        * **`props`**: `[dict]` → The props that will be rendered as global outputs.
+            * **See**: `cave_utils.api_utils.general.props`
+        * **`values`**: `[dict]` = `None` →
+            * The values to be assigned to the respective props. Each value is associated with its corresponding prop based on the key name used in `props`.
+            * **See**: `cave_utils.api_utils.general.values`
+        * **`layout`**: `[dict]` =`{"type": "grid", "numColumns": "auto", "numRows": "auto"}` →
+            * The layout of the global outputs when the "Overview" chart is selected.
+            * **See**: `cave_utils.api_utils.general.layout`
         """
+
         return {"kwargs": kwargs, "accepted_values": {}}
 
     def __extend_spec__(self, **kwargs):
@@ -65,4 +55,4 @@ class globalOutputs(ApiValidator):
                 prepend_path=["layout"],
                 prop_id_list=list(props_data.keys()),
                 **kwargs,
-            )
+            )