cave-utils 2.0.1__tar.gz → 2.0.2__tar.gz

{cave_utils-2.0.1 → cave_utils-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cave_utils
-Version: 2.0.1
+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
+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
-    - Outputs will be stored in `logs/validation/{session_name}.log`
 
 4. Use the following command to run your cave_app:
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils"`

{cave_utils-2.0.1 → 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
+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
-    - Outputs will be stored in `logs/validation/{session_name}.log`
 
 4. Use the following command to run your cave_app:
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils"`

{cave_utils-2.0.1 → cave_utils-2.0.2}/cave_utils/api/appBar.py

@@ -78,7 +78,7 @@ class appBar_data_star(ApiValidator):
                 * `"lowerRight"`: Lower section of the right-side bar
         * **`variant`**: `[str]` = `None` → The variant of the button.
             * **Accepted Values**:
-                * When **`type`** == `"pane"` | `"page"`:
+                * When **`type`** == `"pane"`:
                     * `"modal"`: A [modal pane][]
                     * `"wall"`: A [wall pane][]
                 * Otherwise:

{cave_utils-2.0.1 → cave_utils-2.0.2}/cave_utils/api/groupedOutputs.py

@@ -60,9 +60,10 @@ class groupedOutputs_data_star(ApiValidator):
         * **`stats`**: `[dict]` → A dictionary of stats that are available for the data.
             * **See**: `cave_utils.api.groupedOutputs.groupedOutputs_data_star_stats`
         **`valueLists`**: `[dict]` → A dictionary of lists that make up the stats for the data.
+            * **See**: `cave_utils.api.groupedOutputs.groupedOutputs_data_star_valueLists`
+            * **Note**: Each key must also be a key in `groupedOutputs.data.*.stats`.
         **`groupLists`**: `[dict]` → A dictionary of lists that make up the groupings for the data.
         """
-        # TODO: Flesh out valueLists and groupLists
         return {"kwargs": kwargs, "accepted_values": {}}
 
     def __extend_spec__(self, **kwargs):
@@ -74,45 +75,37 @@ class groupedOutputs_data_star(ApiValidator):
             validator=groupedOutputs_data_star_stats,
             **kwargs,
         )
-        list_lengths = []
-        pass_list_lengths = True
         # Ensure Valid Value Lists
         valueLists_data = self.data.get("valueLists", {})
-        for key, value in valueLists_data.items():
-            if not self.__check_type__(
-                value=value, check_type=(list,), prepend_path=["valueLists", key]
-            ):
-                pass_list_lengths = False
-                continue
-            list_lengths.append(len(value))
-            self.__check_type_list__(
-                data=value, types=(int, float), prepend_path=["valueLists", key]
-            )
+        groupedOutputs_data_star_valueLists(
+            data=valueLists_data,
+            log=self.log,
+            prepend_path=["valueLists"],
+            acceptable_data_keys=list(stats_data.keys()),
+            **kwargs,
+        )
         # Ensure Valid Group Lists
-        available_groups = kwargs.get("available_groups", {})
         groupLists_data = self.data.get("groupLists", {})
-        self.__check_subset_valid__(
-            subset=list(groupLists_data.keys()),
-            valid_values=list(available_groups.keys()),
+        groupedOutputs_data_star_groupLists(
+            data=groupLists_data,
+            log=self.log,
             prepend_path=["groupLists"],
+            **kwargs,
         )
-        for key, value in groupLists_data.items():
-            if not self.__check_type__(
-                value=value, check_type=(list,), prepend_path=["groupLists", key]
-            ):
-                pass_list_lengths = False
-                continue
-            list_lengths.append(len(value))
-            valid_values = available_groups.get(key, [])
-            if not self.__check_type_list__(
-                data=valid_values, types=(str,), prepend_path=["groupLists", key]
+
+        # Ensure that all lists are the same length
+        try:
+            if (
+                len(
+                    set(
+                        [len(v) for v in valueLists_data.values()]
+                        + [len(v) for v in groupLists_data.values()]
+                    )
+                )
+                != 1
             ):
-                continue
-            self.__check_subset_valid__(
-                subset=value, valid_values=valid_values, prepend_path=["groupLists", key]
-            )
-        # Ensure all lists are the same length
-        if not pass_list_lengths or len(set(list_lengths)) != 1:
+                raise Exception
+        except:
             self.__error__(
                 msg="All values in groupedOutputs.data.*.groupLists and groupedOutputs.data.*.valueLists must be lists of the same length.",
             )
@@ -180,14 +173,58 @@ class groupedOutputs_data_star_valueLists(ApiValidator):
     @staticmethod
     def spec(**kwargs):
         """
-        Accepts any key value pairs as a dictionary structure for the data.
-        Each value must be a list of integers or floats.
+        Arguments:
+
+        - **`yourCustomKeyHere`**: `[list]` →
+            - * **Note**: Each custom key passed must also be a key in `groupedOutputs.data.*.stats`.
+            - * **Note**: Each value must be a list of integers or floats.
         """
         return {"kwargs": {}, "accepted_values": {}}
 
     def __extend_spec__(self, **kwargs):
+        if not self.__check_subset_valid__(
+            subset=list(self.data.keys()),
+            valid_values=kwargs.get("acceptable_data_keys", []),
+            prepend_path=[],
+        ):
+            return
         for key, value in self.data.items():
-            self.__check_type_list__(data=value, types=(int, float), prepend_path=[key])
+            if self.__check_type__(value=value, check_type=(list,), prepend_path=[key]):
+                self.__check_type_list__(data=value, types=(int, float), prepend_path=[key])
+
+
+@type_enforced.Enforcer
+class groupedOutputs_data_star_groupLists(ApiValidator):
+    """
+    The group lists are located under the path **`groupedOutputs.data.*.groupLists`**.
+    """
+
+    @staticmethod
+    def spec(**kwargs):
+        """
+        Arguments:
+
+        - **`yourCustomKeyHere`**: `[list]` →
+            - * **Note**: Each value must be a list of strings
+            - * **Note**: Each item in the passed value must also be found in `groupedOutputs.groupings.{yourCustomKeyHere}.data.id`.
+        """
+        return {"kwargs": {}, "accepted_values": {}}
+
+    def __extend_spec__(self, **kwargs):
+        available_groups = kwargs.get("available_groups", {})
+        if self.__check_subset_valid__(
+            subset=list(self.data.keys()),
+            valid_values=list(available_groups.keys()),
+            prepend_path=[],
+        ):
+            for key, value in self.data.items():
+                if self.__check_type__(value=value, check_type=(list,), prepend_path=[key]):
+                    self.__check_type_list__(data=value, types=(str,), prepend_path=[key])
+                    self.__check_subset_valid__(
+                        subset=value,
+                        valid_values=available_groups.get(key, []),
+                        prepend_path=[key],
+                    )
 
 
 @type_enforced.Enforcer

{cave_utils-2.0.1 → cave_utils-2.0.2}/cave_utils/api/maps.py

@@ -365,6 +365,7 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
             * **Notes**:
                 * If `None`, the data layer will not be colored.
                 * Does not apply to shape layers
+                * Only props of type `"num"`, `"toggle"`, and `"selector"` can be colored.
             * **Example**:
                 ```py
                 "colorByOptions": {
@@ -386,6 +387,7 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
             * **Notes**:
                 * If `None`, the data layer will not be sized.
                 * Does not apply to shape layers
+                * Only props of type `"num"` can be sized.
             * **Example**:
                 ```py
                 "sizeByOptions": {
@@ -447,7 +449,7 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
         colorBy_availableProps = {
             k: v
             for k, v in available_props.items()
-            if v.get("type") in ["num", "toggle", "selector"]
+            if v.get("type") in ["num", "toggle", "selector", "text"]
         }
         sizeBy_availableProps = {
             k: v for k, v in available_props.items() if v.get("type") in ["num"]
@@ -591,8 +593,13 @@ class colorByOptions(ApiValidator):
                 ):
                     return
                 self.__check_rgba_string_valid__(rgba_string=value, prepend_path=[key])
+        elif prop_type == "text":
+            for key, value in self.data.items():
+                self.__check_rgba_string_valid__(rgba_string=value, prepend_path=[key])
         else:
-            self.__error__(msg=f"Invalid prop type ({prop_type}) for colorByOptions")
+            self.__error__(
+                msg=f"Invalid prop type ({prop_type}) for colorByOptions. Allowed props are `num`, `toggle`, `selector`, and `text`"
+            )
 
 
 @type_enforced.Enforcer

{cave_utils-2.0.1 → cave_utils-2.0.2}/cave_utils/api_utils/general.py

@@ -40,6 +40,7 @@ class props(ApiValidator):
         unitPlacement: [str, None] = None,
         locale: [str, None] = None,
         fallbackValue: [str, None] = None,
+        allowNone: [bool, None] = None,
         **kwargs,
     ):
         """
@@ -88,11 +89,14 @@ class props(ApiValidator):
                     * `"picture"`: Show a PNG or JPG image
                     * `"video"`: Display a YouTube, Vimeo, or Dailymotion video clip
         * **`enabled`**: `[bool]` = `True` → Whether or not the prop will be enabled.
+            * **Note**: This attribute is applicable to all props except `"head"` props.
         * **`apiCommand`**: `[str]` = `None` → The name of the API command to trigger.
             * **Note**: If `None`, no `apiCommand` is triggered.
+            * **Note**: This attribute is applicable to all props except `"head"` props.
         * **`apiCommandKeys`**: `[list]` = `None` →
             * The root API keys to pass to your `execute_command` function if an `apiCommand` is provided.
             * **Note**: If `None`, all API keys are passed to your `execute_command`.
+            * **Note**: This attribute is applicable to all props except `"head"` props.
         * **`icon`**: `[str]` = `None` → The icon to use for the prop.
             * **Notes**:
                 * It must be a valid icon name from the [react-icons][] bundle, preceded by the abbreviated name of the icon library source.
@@ -146,8 +150,10 @@ class props(ApiValidator):
                 * This attribute is applicable exclusively to `"num"` props.
         * **`fallbackValue`**: [str] = `None` → A value to show when the value is missing or invalid.
             * **Notes**:
+                * This is only for display purposes as related to number formatting. It does not affect the actual value or any computations.
+                    * For example, if the value passed is `None`, the fallback value will be displayed instead.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.fallbackValue`.
-                * This attribute only applies to `"num"` props.
+                * This attribute is applicable exclusively to `"num"` props.
         * **`unit`**: `[str]` = `None` → The unit to use for the prop.
             * **Notes**:
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.unit`.
@@ -229,6 +235,17 @@ class props(ApiValidator):
                 * Takes precedence over other formatting, except when used in a node cluster and the `cave_utils.api.maps.group` attribute is `True`. In this case, the max value within the node cluster is displayed.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.legendMaxLabel`.
                 * This attribute is applicable exclusively to `"num"` props.
+        * **`allowNone`**: `[bool]` = `False` →
+            * Whether or not to allow `None` as a valid value for the prop. This is primarily used to help when validating `values` and `valueLists`.
+            * **Notes**:
+                * If `True`, `None` will be a valid value for the prop.
+                    * `None` values will be treated differently in the front end
+                        * For map display purposes: `None` values will be shown as a different color or ignored.
+                            * See `nullColor` in: `/cave_utils/cave_utils/api/maps.html#colorByOptions`
+                        * For prop purposes: `None` values will be left blank.
+                * If `False`, `None` will not be a valid value for the prop.
+                * This attribute is applicable to all props except `"head"` props.
+
 
         [metric prefix]: https://en.wikipedia.org/wiki/Metric_prefix
         [Scientific notation]: https://en.wikipedia.org/wiki/Scientific_notation
@@ -236,9 +253,9 @@ class props(ApiValidator):
         """
         passed_values = {k: v for k, v in locals().items() if (v is not None) and k != "kwargs"}
         required_fields = ["name", "type"]
-        optional_fields = ["help", "variant", "enabled"]
+        optional_fields = ["help", "variant"]
         if type != "head":
-            optional_fields += ["apiCommand", "apiCommandKeys"]
+            optional_fields += ["enabled", "apiCommand", "apiCommandKeys", "allowNone"]
         if type == "head":
             if variant == "icon":
                 required_fields += ["icon"]
@@ -458,8 +475,12 @@ class values(ApiValidator):
                 )
                 continue
             prop_type = prop_spec.get("type", None)
+            if prop_type == "head":
+                self.__error__(
+                    msg=f"`{prop_key}` with the prop type of `{prop_type}` can not have an associated value."
+                )
+                continue
             acceptable_types = {
-                "head": (str,),
                 "num": (int, float),
                 "toggle": (bool,),
                 "button": (str,),
@@ -467,9 +488,16 @@ class values(ApiValidator):
                 "selector": (list,),
                 "date": (str,),
                 "media": (str,),
-            }.get(prop_type, None)
+            }.get(prop_type, tuple())
+            # Add None to acceptable types if allowed
+            if prop_spec.get("allowNone", False):
+                acceptable_types += (type(None),)
+            # Validate types and continue if invalid
             if not self.__check_type__(prop_value, acceptable_types, prepend_path=[prop_key]):
                 continue
+            # Continue if the value is None
+            if prop_value is None:
+                continue
             if prop_type == "num":
                 min_value = prop_spec.get("minValue", float("-inf"))
                 max_value = prop_spec.get("maxValue", float("inf"))
@@ -480,10 +508,6 @@ class values(ApiValidator):
             elif prop_type == "selector":
                 options = list(prop_spec.get("options", {}).keys())
                 self.__check_subset_valid__(prop_value, options, prepend_path=[prop_key])
-            elif prop_type == "head":
-                self.__error__(
-                    msg=f"`{prop_key}` with the prop type of `{prop_type}` can not have an associated value."
-                )
             elif prop_type == "date":
                 pass
                 # TODO: Validate date string
@@ -498,7 +522,7 @@ class valueLists(ApiValidator):
         """
         Accepts all arbitrary values depending on what you have in your props as part of the API spec.
 
-        The valueLists you pass will be validated against the props in your API spec.
+        The valueLists you pass will be validated against the `props` from your API spec.
         """
         return {
             "kwargs": {},
@@ -520,8 +544,12 @@ class valueLists(ApiValidator):
                 )
                 continue
             prop_type = prop_spec.get("type", None)
+            if prop_type == "head":
+                self.__error__(
+                    msg=f"`{prop_key}` with the prop type of `{prop_type}` can not have an associated value."
+                )
+                continue
             acceptable_types = {
-                "head": (str,),
                 "num": (int, float),
                 "toggle": (bool,),
                 "button": (str,),
@@ -529,11 +557,16 @@ class valueLists(ApiValidator):
                 "selector": (list,),
                 "date": (str,),
                 "media": (str,),
-            }.get(prop_type, None)
+            }.get(prop_type, tuple())
+            # Add None to acceptable types if allowed
+            if prop_spec.get("allowNone", False):
+                acceptable_types += (type(None),)
             if not self.__check_type_list__(
                 data=prop_value_list, types=acceptable_types, prepend_path=[prop_key]
             ):
                 continue
+            if prop_spec.get("allowNone", False):
+                prop_value_list = [v for v in prop_value_list if v is not None]
             if prop_type == "num":
                 # Validate minimum is met
                 min_value = prop_spec.get("minValue")

{cave_utils-2.0.1 → cave_utils-2.0.2}/cave_utils/api_utils/validator_utils.py

@@ -93,40 +93,42 @@ class ApiValidator:
         """
         Validate an rgba string and if an issue is present, log an error
         """
+        msg = "Invalid RGBA string. Must be in the format 'rgba(0, 0, 0, 0)' where each value is an integer between 0 and 255."
         try:
             if "rgba(" != rgba_string[:5]:
-                self.__error__(path=prepend_path, msg="Invalid RGBA string")
+                self.__error__(path=prepend_path, msg=msg)
                 return
             if ")" != rgba_string[-1]:
-                self.__error__(path=prepend_path, msg="Invalid RGBA string")
+                self.__error__(path=prepend_path, msg=msg)
                 return
             rgba_list = rgba_string[5:-1].replace(" ", "").split(",")
             for rgba in rgba_list:
                 if not rgba.isdigit():
-                    self.__error__(path=prepend_path, msg="Invalid RGBA string")
+                    self.__error__(path=prepend_path, msg=msg)
                     return
                 if int(rgba) < 0 or int(rgba) > 255:
-                    self.__error__(path=prepend_path, msg="Invalid RGBA string")
+                    self.__error__(path=prepend_path, msg=msg)
                     return
         except:
-            self.__error__(path=prepend_path, msg="Invalid RGBA string")
+            self.__error__(path=prepend_path, msg=msg)
 
     def __check_pixel_string_valid__(self, pixel_string: str, prepend_path: list = list()):
         """
         Validate a pixel string and if an issue is present, log an error
         """
+        msg = "Invalid pixel string. Must be in the format '5px' where the value portion is a whole number."
         try:
             if "px" != pixel_string[-2:]:
-                self.__error__(path=prepend_path, msg="Invalid pixel string")
+                self.__error__(path=prepend_path, msg=msg)
                 return
-            if int(pixel_string[:-2]) <= 0:
-                self.__error__(path=prepend_path, msg="Invalid pixel string")
+            if int(pixel_string[:-2]) < 0:
+                self.__error__(path=prepend_path, msg=msg)
         except:
-            self.__error__(path=prepend_path, msg="Invalid pixel string")
+            self.__error__(path=prepend_path, msg=msg)
 
     def __check_url_valid__(self, url: str, prepend_path: list = list()):
         """
-        Validate a url and if an issue is present, log an error
+        Validate a url and if an issue is present, log an error.
         """
         # Use Django regex for URL validation
         # See https://stackoverflow.com/a/7160778/12014156

{cave_utils-2.0.1 → cave_utils-2.0.2}/cave_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cave-utils
-Version: 2.0.1
+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
+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
-    - Outputs will be stored in `logs/validation/{session_name}.log`
 
 4. Use the following command to run your cave_app:
     `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils"`

{cave_utils-2.0.1 → cave_utils-2.0.2}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cave_utils"
-version = "2.0.1"
+version = "2.0.2"
 description = "Python wrapper for api use in the cave_app"
 authors = [
     {name="Connor Makowski", email="conmak@mit.edu"}

{cave_utils-2.0.1 → cave_utils-2.0.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = cave_utils
-version = 2.0.1
+version = 2.0.2
 description_file = README.md
 
 [options]