cave-utils 2.2.1__tar.gz → 2.3.0__tar.gz

{cave_utils-2.2.1/cave_utils.egg-info → cave_utils-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cave_utils
-Version: 2.2.1
+Version: 2.3.0
 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

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/api/groupedOutputs.py

@@ -123,9 +123,11 @@ class groupedOutputs_data_star_stats(ApiValidator):
         name: str,
         calculation: str,
         unit: [str, None] = None,
-        unitPlacement: str = "afterWithSpace",
+        unitPlacement: [str, None] = None,
         precision: [int, None] = None,
-        trailingZeros: bool = False,
+        trailingZeros: [bool, None] = None,
+        notation: [str, None] = None,
+        notationDisplay: [str, None] = None,
         **kwargs,
     ):
         """
@@ -156,11 +158,36 @@ class groupedOutputs_data_star_stats(ApiValidator):
             * **Notes**:
                 * This ensures that all precision digits are shown. For example: `1.5` → `1.500` when precision is `3`.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.trailingZeros`.
+        * **`notation`**: `[int]` = `"standard"` → The formatting style of a numeric value.
+        * **`notationDisplay`**: `[str]` = `"e+"` | `"short"` | `None` → Further customize the formatting within the selected `notation`.
+            * **Notes**:
+                * No `notationDisplay` option is provided for a `"standard"` notation
+                * The options `"short"` and `"long"` are only provided for the `"compact"` notation
+                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"`, `"engineering"` and `"precision"` notations
+                * If `None`, it defaults to `"short"` for `"compact"` notation, and to `"e+"` for `"scientific"`, `"engineering"` or `"precision"` notations; if the option is set to `"standard"`, its value remains `None`.
+
+        [metric prefix]: https://en.wikipedia.org/wiki/Metric_prefix
+        [Scientific notation]: https://en.wikipedia.org/wiki/Scientific_notation
+        [Engineering notation]: https://en.wikipedia.org/wiki/Engineering_notation
+        [Number.prototype.toPrecision]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision
         """
+        passed_values = {k: v for k, v in locals().items() if (v is not None) and k != "kwargs"}
+        if notationDisplay and not notation:
+            raise Exception(f"Missing required fields: notation")
+        notation = passed_values.get("notation", "standard")
+
         return {
             "kwargs": kwargs,
             "accepted_values": {
                 "unitPlacement": ["after", "afterWithSpace", "before", "beforeWithSpace"],
+                "notation": ["standard", "compact", "scientific", "engineering", "precision"],
+                "notationDisplay": {
+                    "compact": ["short", "long"],
+                    "scientific": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+                    "engineering": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+                    "precision": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+                    "standard": [],
+                }.get(notation, []),
             },
         }
 
@@ -268,6 +295,10 @@ class groupedOutputs_groupings_star(ApiValidator):
         * **`grouping`**: `[str]` = `None` →
             * A group that is created to put similar groupings together in the UI dropdowns when selecting groupings.
             * **Note**: If `None`, the grouping will be placed in the root of the UI dropdowns.
+
+        [metric prefix]: https://en.wikipedia.org/wiki/Metric_prefix
+        [Scientific notation]: https://en.wikipedia.org/wiki/Scientific_notation
+        [Engineering notation]: https://en.wikipedia.org/wiki/Engineering_notation
         """
         return {
             "kwargs": kwargs,
@@ -368,12 +399,12 @@ class groupedOutputs_groupings_star_levels_star(ApiValidator):
                 * If `None`, this will be considered to be the root of the hierarchy.
         * **`ordering`**: `[list]` →
             * The ordering of individual values for this level in charts and tables.
-            * **Note**: If none, the ordering will be alphabetical.
+            * **Note**: If `None`, the ordering will be alphabetical.
             * **Note**: If a partial ordering is provided, the provided values will be placed first in order.
             * **Note**: If a partial ordering is provided, the remaining values will be placed in alphabetical order.
             * **Note**: All items in this list must be defined in `groupedOutputs.groupings.*.levels.*.values.*`
-        * **`orderWithParent`**: `[bool]`=True →
-            * Weather or not to order this level based on the parent level.
+        * **`orderWithParent`**: `[bool]` = `True` →
+            * Wether or not to order this level based on the parent level.
             * If `True`, the ordering of this level will also be based on the parent level.
             * If `False`, the ordering will be based on the ordering of this level only.
         * **`coloring`**: `[dict]` →

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/api/maps.py

@@ -311,13 +311,13 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
                 * `"solid"`: Represents a single continuous line.
                 * `"dashed"`: A series of dashes or line segments
                 * `"dotted"`: A dotted line
-            * **Note**: This attribute is applicable exclusively to `arc` layers.
+            * **Note**: This attribute applies exclusively to `arc` layers.
         * **`allowGrouping`**: `[bool]` = `False` → Whether or not to allow grouping of the data layer.
-            * **Note**: This attribute is applicable exclusively to `node` layers.
+            * **Note**: This attribute applies exclusively to `node` layers.
         * **`group`**: `[bool]` = `False` → Whether or not to group the data layer.
             * **Notes**:
                 * If `False`, the data layer will not be grouped
-                * This attribute is applicable exclusively to `node` layers
+                * This attribute applies exclusively to `node` layers
         * **`groupCalcBySize`**: `[str]` = `"count"` | `"mode"` → The aggregation function to use on the prop specified in `sizeBy`.
             * **Accepted Values**:
                 * When **`sizeBy`** prop's **`type`** == `"num"`:
@@ -338,7 +338,7 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
                 * If `None`, the data layer will not be grouped
                 * The calculation is based on the values of the prop specified in `sizeBy`
                 * The default value for a `sizeBy` prop of type `"num"` is `"count"`. For other types, the default value is `"mode"`.
-                * This attribute is applicable exclusively to `node` layers
+                * This attribute applies exclusively to `node` layers
         * **`groupCalcByColor`**: `[str]` = `"count"` | `"mode"` → The aggregation function to use on the prop specified in `colorBy`.
             * **Accepted Values**:
                 * When **`colorBy`** prop's **`type`** == `"num"`:
@@ -359,15 +359,15 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
                 * If `None`, the data layer will not be grouped
                 * The calculation is based on the prop specified in `colorBy`
                 * The default value for a `colorBy` prop of type `"num"` is `"count"`. For other types, the default value is `"mode"`.
-                * This attribute is applicable exclusively to `node` layers
+                * This attribute applies exclusively to `node` layers
         * **`groupScaleWithZoom`**: `[bool]` = `False` → Whether or not to scale the group size with zoom.
             * **Notes**:
                 * If `False`, the group size will be constant as set by `groupScale`
-                * This attribute is applicable exclusively to `node` layers
+                * This attribute applies exclusively to `node` layers
         * **`groupScale`**: `[float | int]` = `None` → The zoom level at which to conduct grouping of the nodes.
             * **Notes**:
                 * If `None`, the group scale will be determined by the map zoom.
-                * This attribute is applicable exclusively to `node` layers
+                * This attribute applies exclusively to `node` layers
         * **`colorByOptions`**: `[dict]` = `None` → The options for coloring the data layer.
             * **Notes**:
                 * If `None`, the data layer will not be colored.
@@ -411,7 +411,7 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
             * **Notes**:
                 * Arc layer icons are determined by `lineBy`.
                 * Shape layer icons are always the default icon.
-                * This attribute is applicable exclusively to `node` layers
+                * This attribute applies exclusively to `node` layers
         """
         return {
             "kwargs": kwargs,
@@ -459,7 +459,8 @@ class maps_data_star_legendGroups_star_data_star(ApiValidator):
             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"]
+            k: v for k, v in available_props.items()
+            if v.get("type") in ["num", "toggle", "selector"]
         }
 
         passed_colorByOptions = self.data.get("colorByOptions", {})
@@ -687,5 +688,23 @@ class sizeByOptions(ApiValidator):
                     if not isinstance(obj_val, (int, float)):
                         self.__error__(msg=f"Invalid `{obj_key}` ({obj_val}) must be a number")
                         continue
+        elif prop_type == "toggle":
+            for key, value in self.data.items():
+                if not self.__check_subset_valid__(
+                    subset=[key],
+                    valid_values=["true", "false", "nullSize"],
+                    prepend_path=[],
+                ):
+                    return
+                self.__check_pixel_string_valid__(pixel_string=value, prepend_path=[key])
+        elif prop_type == "selector":
+            for key, value in self.data.items():
+                if not self.__check_subset_valid__(
+                    subset=[key],
+                    valid_values=list(prop_data.get("options").keys()) + ["nullSize"],
+                    prepend_path=[],
+                ):
+                    return
+                self.__check_pixel_string_valid__(pixel_string=value, prepend_path=[key])
         else:
             self.__error__(msg=f"Invalid prop type ({prop_type}) for sizeByOptions")

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/api/pages.py

@@ -2,9 +2,11 @@
 Configure your application's pages.
 """
 
-from cave_utils.api_utils.validator_utils import ApiValidator, CustomKeyValidator
 import type_enforced
 
+from itertools import chain
+from cave_utils.api_utils.validator_utils import ApiValidator, CustomKeyValidator
+
 
 @type_enforced.Enforcer
 class pages(ApiValidator):
@@ -84,6 +86,10 @@ class pages_data_star_pageLayout(ApiValidator):
         showToolbar: bool = True,
         maximized: bool = False,
         defaultToZero: bool = False,
+        distributionType: [str, None] = None,
+        distributionYAxis: [str, None] = None,
+        distributionVariant: [str, None] = None,
+        showNA: bool = False,
         **kwargs,
     ):
         """
@@ -112,6 +118,7 @@ class pages_data_star_pageLayout(ApiValidator):
                     * `"table"`: A table showing the aggregated values.
                     * `"treemap"`: A [treemap chart][]
                     * `"waterfall"`: A [waterfall chart][]
+                    * `"distribution"`: A [distribution chart][]
                 * When **`type`** == `"globalOutput"`:
                     * `"bar"`: A [bar chart][]
                     * `"line"`: A [line chart][]
@@ -138,6 +145,28 @@ class pages_data_star_pageLayout(ApiValidator):
         * **`maximized`**: `[bool]` = `False` → Whether or not the layout should be maximized.
             * **Note**: If more than one chart belonging to the same page layout is set to `True`, the first one found in the list will take precedence.
         * **`defaultToZero`**: `[bool]` = `False` → Whether or not the chart should default missing values to zero.
+        * **`distributionType`**: `[str]` = `None` → The type of distribution function displayed in distribution charts.
+            * Accepted Values:
+                * `"pdf"`: Uses the probability density function.
+                * `"cdf"`: Uses the cumulative density function.
+            * **Notes**:
+                * If left unspecified (i.e., `None`), it will default to `"pdf"`.
+                * This attribute is applicable exclusively to the `"distribution"` variant.
+        * **`distributionYAxis`**: `[str]` = `None` → The y-axis metric in distribution charts.
+            * Accepted Values:
+                * `"counts"`: Displays the y-axis as raw counts of occurrences.
+                * `"density"`: Displays the y-axis as proportions of total counts.
+            * **Notes**:
+                * If left unspecified (i.e., `None`), it will default to `"counts"`.
+                * This attribute is applicable exclusively to the `"distribution"` variant.
+        * **`distributionVariant`**: `[str]` = `None` → The chart type displayed in distribution charts.
+            * Accepted Values:
+                * `"bar"`: A bar chart.
+                * `"line"`: A line chart.
+            * **Notes**:
+                * If left unspecified (i.e., `None`), it will default to `"bar"`.
+                * This attribute is applicable exclusively to the `"distribution"` variant.
+        * **`showNA`**: `[bool]` = `False` → Whether to display missing or filtered values in both the chart tooltip and the axis.
 
         [area chart]: https://en.wikipedia.org/wiki/Area_chart
         [bar chart]: https://en.wikipedia.org/wiki/Bar_chart
@@ -154,6 +183,7 @@ class pages_data_star_pageLayout(ApiValidator):
         [table chart]: #
         [treemap chart]: https://en.wikipedia.org/wiki/Treemapping
         [waterfall chart]: https://en.wikipedia.org/wiki/Waterfall_chart
+        [distribution chart]: https://en.wikipedia.org/wiki/Probability_distribution
         """
         if type == "globalOutput":
             variant_options = ["bar", "line", "table", "overview"]
@@ -168,12 +198,14 @@ class pages_data_star_pageLayout(ApiValidator):
                 "heatmap",
                 "line",
                 "scatter",
+                "distribution",
                 "stacked_area",
                 "stacked_waterfall",
                 "sunburst",
                 "table",
                 "treemap",
                 "waterfall",
+                "distribution",
             ]
         else:
             variant_options = []
@@ -183,6 +215,9 @@ class pages_data_star_pageLayout(ApiValidator):
                 "type": ["groupedOutput", "globalOutput", "map"],
                 "variant": variant_options,
                 "statAggregation": ["sum", "mean", "min", "max"],
+                "distributionType": ["pdf", "cdf"] if variant == "distribution" else [],
+                "distributionYAxis": ["counts", "density"] if variant == "distribution" else [],
+                "distributionVariant": ["bar", "line"] if variant == "distribution" else [],
             },
         }
 
@@ -219,45 +254,56 @@ class pages_data_star_pageLayout(ApiValidator):
         # Validate groupedOutput
         else:
             # Validate groupedOutputDataId
-            groupedOutputDataId = self.data.get("groupedOutputDataId")
+            groupedOutputDataId_raw = self.data.get("groupedOutputDataId")
+            groupedOutputDataId = (
+                [groupedOutputDataId_raw]
+                if isinstance(groupedOutputDataId_raw, str)
+                else groupedOutputDataId_raw
+            )
             if groupedOutputDataId is not None:
                 self.__check_type__(
                     groupedOutputDataId, (str, list), prepend_path=["groupedOutputDataId"]
                 )
-                # TODO: Review subset validation
                 # Ensure that the groupedOutputDataId is valid
                 self.__check_subset_valid__(
-                    subset=[groupedOutputDataId],
+                    subset=groupedOutputDataId,
                     valid_values=list(kwargs.get("groupedOutputs_validGroupIds", {}).keys()),
                     prepend_path=["groupedOutputDataId"],
                 )
             # Validate statId
-            statId = self.data.get("statId")
-            if statId is not None:
-                self.__check_type__(statId, (str, list), prepend_path=["statId"])
-                statIds = statId if isinstance(statId, list) else [statId]
-                # TODO: Review subset validation
-                for sid in statIds:
+            statId_raw = self.data.get("statId")
+            if statId_raw is not None:
+                self.__check_type__(statId_raw, (str, list), prepend_path=["statId"])
+                statId = statId_raw if isinstance(statId_raw, list) else [statId_raw]
+                if len(groupedOutputDataId) != len(statId):
+                    self.__error__(
+                        msg="`groupingId` and `statId` must be the same length.",
+                    )
+                    return
+                for idx, sid in enumerate(statId):
                     # Ensure that the statId is valid
                     self.__check_subset_valid__(
                         subset=[sid],
                         valid_values=list(
                             kwargs.get("groupedOutputs_validStatIds", {}).get(
-                                groupedOutputDataId, []
+                                groupedOutputDataId[idx], []
                             )
                         ),
-                        prepend_path=["statId"],
+                        prepend_path=["statId", idx],
                     )
             # Validate groupingId
             groupingId = self.data.get("groupingId")
             if groupingId is not None:
                 self.__check_type__(groupingId, list, prepend_path=["groupingId"])
+                all_valid_group_ids = chain.from_iterable([
+                    kwargs.get("groupedOutputs_validGroupIds", {}).get(groupingId_item, [])
+                    for groupingId_item in groupedOutputDataId
+                ])
+                valid_values = list(set(all_valid_group_ids))
                 # Ensure that the groupingId is valid
                 self.__check_subset_valid__(
                     subset=groupingId,
-                    valid_values=list(
-                        kwargs.get("groupedOutputs_validGroupIds", {}).get(groupedOutputDataId, [])
-                    ),
+                    valid_values=valid_values,
                     prepend_path=["groupingId"],
                 )
             # Validate groupingLevel

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/api/settings.py

@@ -88,13 +88,13 @@ class settings_defaults(ApiValidator):
         locale: str = "en-US",
         precision: int = 2,
         trailingZeros: bool = False,
-        notation: [str, None] = "standard",
+        notation: [str, None] = None,
         notationDisplay: [str, None] = None,
         fallbackValue: [str, None] = "N/A",
         unit: [str, None] = None,
-        unitPlacement: str = "afterWithSpace",
+        unitPlacement: [str, None] = None,
         legendPrecision: [str, None] = None,
-        legendNotation: [str, None] = "standard",
+        legendNotation: [str, None] = None,
         legendNotationDisplay: [str, None] = None,
         legendMinLabel: [str, None] = None,
         legendMaxLabel: [str, None] = None,
@@ -106,50 +106,73 @@ class settings_defaults(ApiValidator):
         * **`showToolbar`**: `[bool]` = `True` → If `True`, chart toolbars will be displayed by default.
         * **`locale`**: `[str]` = `"en-US"` →
             * Format numeric values based on language and regional conventions.
-            * **Note**: This attribute only applies to `"num"` props.
+            * **Note**: This attribute only applies to `"num"` props or `stats`.
             * **See**: [Locale identifier][].
         * **`precision`**: `[int]` = `2` → The number of decimal places to display.
             * **Notes**:
                 * Set the precision to `0` to attach an integer constraint.
-                * This attribute only applies to `"num"` props.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`trailingZeros`**: `[bool]` = `False` → If `True`, trailing zeros will be displayed.
             * **Notes**:
                 * This ensures that all precision digits are shown. For example: `1.5` → `1.500` when precision is `3`.
-                * This attribute only applies to `"num"` props.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`notation`**: `[int]` = `"standard"` → The formatting style of a numeric value.
+            * **Accepted Values**:
+                    * `"standard"`: Plain number formatting
+                    * `"compact"`: Resembles the [metric prefix][] system
+                    * `"scientific"`: [Scientific notation][]
+                    * `"engineering"`: [Engineering notation][]
+                    * `"precision"`: Emulates the [Number.prototype.toPrecision][] method
+            * **Notes**:
+                * If left unspecified (i.e. `None`), the prop's or stat's `notation` will be used or in case the latter is undefined, `settings.notation` will be used.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`notationDisplay`**: `[str]` = `"e+"` | `"short"` | `None` → Further customize the formatting within the selected `notation`.
+            * **Accepted Values**:
+                * When **`notation`** == `"compact"`:
+                    * `"short"`: Add symbols `K`, `M`, `B`, and `T` (in `"en-US"`) to denote thousands, millions, billions, and trillions, respectively.
+                    * `"long"`: Present numeric values with the informal suffix words `thousand`, `million`, `billion`, and `trillion` (in `"en-US"`).
+                * When **`notation`** == `"scientific"`, `"engineering"` or `"precision"`:
+                    * `"e"`: Exponent symbol in lowercase as per the chosen `locale` identifier
+                    * `"e+"`: Similar to `"e"`, but with a plus sign for positive exponents.
+                    * `"E"`: Exponent symbol in uppercase as per the chosen `locale` identifier
+                    * `"E+"`: Similar to `"E"`, but with a plus sign for positive exponents.
+                    * `"x10^"`: Formal scientific notation representation
+                    * `"x10^+"`: Similar to `"x10^"`, with a plus sign for positive exponents.
+                * When **`notation`** == `"standard"`:
+                    * No `notationDisplay` option is allowed for a `"standard"` notation
             * **Notes**:
                 * No `notationDisplay` option is provided for a `"standard"` notation
                 * The options `"short"` and `"long"` are only provided for the `"compact"` notation
-                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"` and `"engineering"` notations
-                * If `None`, it defaults to `"short"` for `"compact"` notation, and to `"e+"` for `"scientific"` or `"engineering"` notations; if the option is set to `"standard"`, its value remains `None`.
-                * This attribute only applies to `"num"` props.
+                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"`, `"engineering"` and `"precision"` notations
+                * If `None`, it defaults to `"short"` for `"compact"` notation, and to `"e+"` for `"scientific"`, `"engineering"`, or `"precision"` notations. For the `"standard"` option, the value remains `None`.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`fallbackValue`**: [str] = `"N/A"` → A value to show when a numeric value is missing or invalid.
-            * **Note**: This attribute only applies to `"num"` props.
+            * **Note**: This attribute only applies to `"num"` props or `stats`.
         * **`unit`**: `[str]` = `None` → The unit to use for a prop or stat.
-            * **Note**: This attribute only applies to `"num"` props.
+            * **Note**: This attribute only applies to `"num"` props or `stats`.
         * **`unitPlacement`**: `[str]` = `"afterWithSpace"` → The position of the `unit` symbol relative to a value.
             * **Accepted Values**:
                 * `"after"`: The `unit` appears after the value.
                 * `"afterWithSpace"`: The `unit` appears after the value, separated by a space.
                 * `"before"`: The `unit` appears before the value.
                 * `"beforeWithSpace"`: The unit is placed before the value, with a space in between.
-            * **Note**: This attribute only applies to `"num"` props.
+            * **Note**: This attribute only applies to `"num"` props or `stats`.
         * **`legendPrecision`**: `[int]` = `None` →
             * The number of decimal places to display in the Map Legend.
             * **Notes**:
                 * Set the precision to `0` to attach an integer constraint.
-                * If left unspecified (i.e. `None`), the prop's `precision` will be used or in case the latter is undefined, `settings.precision` will be used.
-                * This attribute only applies to `"num"` props.
+                * If left unspecified (i.e. `None`), the prop's or stat's `precision` will be used or in case the latter is undefined, `settings.precision` will be used.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`legendNotation`**: `[int]` = `"standard"` → The formatting style of a numeric value.
             * **Accepted Values**:
                 * `"standard"`: Plain number formatting
                 * `"compact"`: Resembles the [metric prefix][] system
                 * `"scientific"`: [Scientific notation][]
                 * `"engineering"`: [Engineering notation][]
+                * `"precision"`: Emulates the [Number.prototype.toPrecision][] method
             * **Notes**:
-                * If left unspecified (i.e. `None`), the prop's `notation` will be used or in case the latter is undefined, `settings.notation` will be used.
-                * This attribute only applies to `"num"` props.
+                * If left unspecified (i.e. `None`), the prop's or stat's `notation` will be used or in case the latter is undefined, `settings.notation` will be used.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`legendNotationDisplay`**: `[str]` = `"e+"` | `"short"` | `None` → Further customize the formatting within the selected `legendNotation`.
             * **Accepted Values**:
                 * `"short"`: Add symbols `K`, `M`, `B`, and `T` (in `"en-US"`) to denote thousands, millions, billions, and trillions, respectively.
@@ -163,34 +186,53 @@ class settings_defaults(ApiValidator):
             * **Notes**:
                 * No `legendNotationDisplay` option is provided for a `"standard"` legend notation
                 * The options `"short"` and `"long"` are only provided for the `"compact"` legend notation
-                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"` and `"engineering"` legend notations
-                * If left unspecified (i.e. `None`), the prop's `notationDisplay` will be used or in case the latter is undefined, `settings.notationDisplay` will be used.
-                * This attribute only applies to `"num"` props.
+                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"`, `"engineering"` and `"precision"` legend notations
+                * If left unspecified (i.e. `None`), the prop's or stat's `notationDisplay` will be used or in case the latter is undefined, `settings.notationDisplay` will be used.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`legendMinLabel`**: `[str]` = `None` →
             * A custom and descriptive label in the Map Legend used to identify the lowest data point.
             * **Notes**:
                 * 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 min value within the node cluster is displayed.
-                * This attribute only applies to `"num"` props.
+                * This attribute only applies to `"num"` props or `stats`.
         * **`legendMaxLabel`**: `[str]` = `None` →
             * A custom and descriptive label in the Map Legend used to identify the highest data point.
             * **Notes**:
                 * 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.
-                * This attribute only applies to `"num"` props.
+                * This attribute only applies to `"num"` props or `stats`.
 
         [locale identifier]: https://en.wikipedia.org/wiki/IETF_language_tag
+        [metric prefix]: https://en.wikipedia.org/wiki/Metric_prefix
+        [Scientific notation]: https://en.wikipedia.org/wiki/Scientific_notation
+        [Engineering notation]: https://en.wikipedia.org/wiki/Engineering_notation
+        [Number.prototype.toPrecision]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision
         """
+        passed_values = {k: v for k, v in locals().items() if (v is not None) and k != "kwargs"}
+        required_fields = []
+        if notationDisplay:
+            required_fields += ["notation"]
+        if legendNotationDisplay:
+            required_fields += ["legendNotation"]
+        missing_required = pamda.difference(required_fields, list(passed_values.keys()))
+        if len(missing_required) > 0:
+            raise Exception(f"Missing required fields: {str(missing_required)}")
+
+        notationDisplay_options_dict = {
+            "compact": ["short", "long"],
+            "scientific": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+            "engineering": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+            "precision": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+            "standard": [],
+        }
+        notation = passed_values.get("notation", "standard")
+        legendNotation = passed_values.get("legendNotation", "standard")
         return {
             "kwargs": kwargs,
             "accepted_values": {
                 "unitPlacement": ["after", "afterWithSpace", "before", "beforeWithSpace"],
-                # TODO: Validate
-                # compact: allowed notation displays -> "short", "long"
-                # scientific|engineering: allowed notation displays -> "e", "e+", "E", "E+", "x10^", "x10^+"
-                # standard: allowed notation displays -> None
-                "notation": ["compact", "precision", "scientific"],
-                "notationDisplay": ["short", "long", "e", "e+", "E", "E+", "x10^", "x10^+"],
-                "legendNotation": ["compact", "precision", "scientific"],
-                "legendNotationDisplay": ["short", "long", "e", "e+", "E", "E+", "x10^", "x10^+"],
+                "notation": ["standard", "compact", "scientific", "engineering", "precision"],
+                "notationDisplay": notationDisplay_options_dict.get(notation, []),
+                "legendNotation": ["standard", "compact", "scientific", "engineering", "precision"],
+                "legendNotationDisplay": notationDisplay_options_dict.get(legendNotation, []),
             },
         }
 
@@ -283,13 +325,16 @@ class settings_time(ApiValidator):
     """
 
     @staticmethod
-    def spec(timeLength: int, timeUnits: str, **kwargs):
+    def spec(timeLength: int, timeUnits: str, looping: bool, speed: [float, int], **kwargs):
         """
         Arguments:
 
         * **`timeLength`**: `[int]` → The amount of time values to display.
         * **`timeUnits`**: `[str]` → The units of time to display.
             * **Example**: `"Decade"`.
+        * **`looping`**: `[bool]` → If `True`, the time animation will automatically restart from the beginning once it reaches the end.
+        * **`speed`**: `[float]` → The speed at which the animation advances to the next time step.
+            * **Note**: While `speed` is intended to be measured in frames per second (fps), performance may degrade as the size of the time-varying data increases, resulting in slower animation.
         """
         return {"kwargs": kwargs, "accepted_values": {}}
 
@@ -297,3 +342,10 @@ class settings_time(ApiValidator):
         timeLength = self.data.get("timeLength")
         if timeLength < 1:
             self.__error__(f"Time length must be greater than 0.", path=["timeLength"])
+        speed = self.data.get("speed")
+        accepted_speed_values = {0.5, 0.75, 1, 1.25, 1.5, 2}
+        if speed not in accepted_speed_values:
+            self.__error__(
+                f"speed must be one of the following values: {accepted_speed_values}.",
+                path=["speed"],
+            )

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/api_utils/general.py

@@ -17,9 +17,12 @@ class props(ApiValidator):
         variant: [str, None] = None,
         display: [bool, None] = None,
         enabled: [bool, None] = None,
+        container: [str, None] = None,
         apiCommand: [str, None] = None,
         apiCommandKeys: [list[str], None] = None,
         options: [dict, None] = None,
+        valueOptions: [list[int, float], None] = None,
+        label: [str, None] = None,
         placeholder: [str, None] = None,
         maxValue: [float, int, None] = None,
         minValue: [float, int, None] = None,
@@ -30,6 +33,7 @@ class props(ApiValidator):
         precision: [int, None] = None,
         notationDisplay: [str, None] = None,
         unit: [str, None] = None,
+        unitPlacement: [str, None] = None,
         views: [list[str], None] = None,
         legendNotation: [str, None] = None,
         legendPrecision: [int, None] = None,
@@ -38,7 +42,6 @@ class props(ApiValidator):
         legendMaxLabel: [str, None] = None,
         icon: [str, None] = None,
         trailingZeros: [bool, None] = None,
-        unitPlacement: [str, None] = None,
         locale: [str, None] = None,
         fallbackValue: [str, None] = None,
         draggable: [bool, None] = None,
@@ -59,6 +62,7 @@ class props(ApiValidator):
                 * `"selector"`: Select options from a set
                 * `"date"`: Select a date and/or time
                 * `"media"`: View various media formats
+                * `"coordinate"`: A coordinate input field
         * **`help`**: `[str]` = `None` → The help text to display.
         * **`display`**: `[bool]` = `None` → Whether or not the prop will be displayed.
         * **`variant`**: `[str]` = `None` → The variant of the prop.
@@ -76,9 +80,11 @@ class props(ApiValidator):
                     * `"slider"`: A range of values along a bar, from which users may select a single value
                     * `"icon"`: A fixed numerical value presented alongside a corresponding icon.
                     * `"iconCompact"`: Similar to `"icon"`, but designed in a compact format for appropriate rendering within a draggable pad.
+                    * `"incslider"`: A range of values along a bar, from which users may select a single value, with a predefined set of options.
                 * When **`type`** == `"selector"`:
                     * `"checkbox"`: Select one or more items from a set of checkboxes
-                    * `"combobox"`: A dropdown with a search bar that allows users to filter options when typing
+                    * `"combobox"`: A dropdown with a search bar allowing users to filter and select a single option by typing
+                    * `"comboboxMulti"`: A dropdown with a search bar, enabling users to filter and select multiple options. Selected items are displayed as tags within the input field.
                     * `"dropdown"`: Show multiple options that appear when the element is clicked
                     * `"nested"`: Select one or more options from a set of nested checkboxes
                     * `"radio"`: Select one option from a set of mutually exclusive options
@@ -95,38 +101,66 @@ class props(ApiValidator):
                 * When **`type`** == `"media"`:
                     * `"picture"`: Show a PNG or JPG image
                     * `"video"`: Display a YouTube, Vimeo, or Dailymotion video clip
+                * When **`type`** == `"coordinate"`:
+                    * `"latLngInput"`: A latitude and longitude input field
+                    * `"latLngMap"`: A clickable map to select a latitude and longitude
+                    * `"latLngPath"`: A clickable map to select a path of latitude and longitude points
+        * **`container`**: `[str]` = `"vertical"` | `"none"` →
+            * Specifies the type of prop container by selecting from predefined styles.
+            * **Accepted Values**:
+                * `"vertical"`: A vertical layout where the prop `name` appears at the top inside the container.
+                * `"horizontal"`: A horizontal layout where the prop `name` is on the left, followed by the actionable prop on the right.
+                * `"titled"`: Similar to the vertical container but without a background color, removing the embossed appearance of the prop.
+                * `"untitled"`: A slim container version without the prop `name` or `unit` label.
+                * `"none"`: Removes the prop container entirely, disabling the display of the prop `name`, `help` button and `unit` label. Only the actionable prop is displayed.
+            * **Notes**:
+                * This attribute applies to all props except the `"icon"` and `"iconCompact"` variants of the `"num"` prop.
+                * If left unspecified (i.e., `None`), the default is `"none"` for `"head"` props, and `"vertical"` for all others. As stated, the `"icon"` and `"iconCompact"` variants of the `"num"` prop are always set to `"none"`, regardless of this attribute.
+                * When the container is set to `"none"`, the `style` prop used at the `"item"` level of the `layout` becomes ineffective.
         * **`enabled`**: `[bool]` = `True` → Whether or not the prop will be enabled.
-            * **Note**: This attribute is applicable to all props except `"head"` props.
+            * **Note**: This attribute applies 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.
+            * **Note**: This attribute applies to all props except `"head"` props.
         * **`apiCommandKeys`**: `[list[str]]` = `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.
+            * **Note**: This attribute applies 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.
-                * This attribute is applicable exclusively to `"head"` props.
+                * This attribute applies exclusively to `"head"` props.
         * **`options`**: `[dict]` = `None` →
+            * The options to be displayed on the UI element mapped to their display properties.
             * **Notes**:
                 * Only options provided here are valid for the prop value
-                * This attribute is applicable exclusively to `"selector"` props
+                * This attribute applies to only `"selector"` props
+        * **`numVisibleTags`**: `[int]` = `None` →
+            * The maximum number of tags visible in a `"comboboxMulti"` variant of a `"selector"` prop when it is not focused.
+            * **Notes**:
+                * If `None`, all tags will be displayed
+                * This attribute applies exclusively to `"selector"` props using the `"comboboxMulti"` variant
+        * **`valueOptions`**: `[list[int|float]]` = `None` →
+            * **Notes**:
+                * Only valueOptions provided here can be selected for the prop value
+                * This attribute applies to `"num"` props with the `"incslider"` variant.
+        * **`label`**: `[str]` = `None` → The label to display above the input field when the prop is focused.
+            * **Note**: This attribute applies to `"num"`, `"text"`, and `"coordinate"` props.
         * **`placeholder`**: `[str]` = `None` → The placeholder text to display.
-            * **Note**: This attribute is applicable exclusively to `"text"` props.
+            * **Note**: This attribute applies exclusively to `"text"` props.
         * **`maxValue`**: `[float | int]` = `None` → The maximum value for the prop.
-            * **Note**: This attribute is applicable exclusively to `"num"` props.
+            * **Note**: This attribute applies exclusively to `"num"` props.
         * **`minValue`**: `[float | int]` = `None` → The minimum value for the prop.
-            * **Note**: This attribute is applicable exclusively to `"num"` props.
+            * **Note**: This attribute applies exclusively to `"num"` props.
         * **`maxRows`**: `[int]` = `None` →
             * The maximum number of rows to show for a `"textarea"` variant.
-            * **Note**: This attribute is applicable exclusively to `"text"` props.
+            * **Note**: This attribute applies exclusively to `"text"` props.
         * **`minRows`**: `[int]` = `None` →
             * The minimum number of rows to show for a `"textarea"` variant.
-            * **Note**: This attribute is applicable exclusively to `"text"` props.
+            * **Note**: This attribute applies exclusively to `"text"` props.
         * **`rows`**: `[int]` = `None` →
             * The fixed number of rows to show for a `"textarea"` variant.
-            * **Note**: This attribute is applicable exclusively to `"text"` props.
+            * **Note**: This attribute applies exclusively to `"text"` props.
         * **`views`**: `[list[str]]` →
             * The available time units for the represented date and/or time.
             * **Default Value**:
@@ -151,33 +185,33 @@ class props(ApiValidator):
                     * `"seconds"`: The seconds view
             * **Notes**:
                 * The views will be presented in the order specified in the `views` array.
-                * This attribute is applicable exclusively to `"date"` props.
+                * This attribute applies exclusively to `"date"` props.
         * **`locale`**: `[str]` = `None` →
             * Format numeric values based on language and regional conventions.
             * **Notes**:
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.locale`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
             * **See**: [Locale identifier][].
         * **`precision`**: `[int]` = `None` → The number of decimal places to display.
             * **Notes**:
                 * Set the precision to `0` to attach an integer constraint.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.precision`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`trailingZeros`**: `[bool]` = `None` → If `True`, trailing zeros will be displayed.
             * **Notes**:
                 * This ensures that all precision digits are shown. For example: `1.5` → `1.500` when precision is `3`.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.trailingZeros`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies 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 is applicable exclusively to `"num"` props.
+                * This attribute applies 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`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`unitPlacement`**: `[str]` = `None` → The position of the `unit` symbol relative to the value.
             * **Accepted Values**:
                 * `"after"`: The `unit` appears after the value.
@@ -186,22 +220,23 @@ class props(ApiValidator):
                 * `"beforeWithSpace"`: The unit is placed before the value, with a space in between.
             * **Notes**:
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.unitPlacement`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`notation`**: `[str]` = `"standard"` → The formatting style of a numeric value.
             * **Accepted Values**:
                 * `"standard"`: Plain number formatting
                 * `"compact"`: Resembles the [metric prefix][] system
                 * `"scientific"`: [Scientific notation][]
                 * `"engineering"`: [Engineering notation][]
+                * `"precision"`: Emulates the [Number.prototype.toPrecision][] method
             * **Notes**:
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.notation`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`notationDisplay`**: `[str]` = `"e+"` | `"short"` → Further customize the formatting within the selected `notation`.
             * **Accepted Values**:
                 * When **`notation`** == `"compact"`:
                     * `"short"`: Add symbols `K`, `M`, `B`, and `T` (in `"en-US"`) to denote thousands, millions, billions, and trillions, respectively.
                     * `"long"`: Present numeric values with the informal suffix words `thousand`, `million`, `billion`, and `trillion` (in `"en-US"`).
-                * When **`notation`** == `"scientific"` or `"engineering"`:
+                * When **`notation`** == `"scientific"`, `"engineering"` or `"precision"`:
                     * `"e"`: Exponent symbol in lowercase as per the chosen `locale` identifier
                     * `"e+"`: Similar to `"e"`, but with a plus sign for positive exponents.
                     * `"E"`: Exponent symbol in uppercase as per the chosen `locale` identifier
@@ -213,24 +248,25 @@ class props(ApiValidator):
             * **Notes**:
                 * No `notationDisplay` option is provided for a `"standard"` notation
                 * The options `"short"` and `"long"` are only provided for the `"compact"` notation
-                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"` and `"engineering"` notations
+                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"`, `"engineering"` and `"precision"` notations
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.notationDisplay`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`legendPrecision`**: `[int]` = `None` →
             * The number of decimal places to display in the Map Legend.
             * **Notes**:
                 * Set the precision to `0` to attach an integer constraint.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.legendPrecision`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`legendNotation`**: `[int]` = `"standard"` → The formatting style of a numeric value.
             * **Accepted Values**:
                 * `"standard"`: Plain number formatting
                 * `"compact"`: Resembles the [metric prefix][] system
                 * `"scientific"`: [Scientific notation][]
                 * `"engineering"`: [Engineering notation][]
+                * `"precision"`: Emulates the [Number.prototype.toPrecision][] method
             * **Notes**:
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.legendNotation`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`legendNotationDisplay`**: `[str]` = `"e+"` | `"short"` → Further customize the formatting within the selected `legendNotation`.
             * **Accepted Values**:
                 * `"short"`: Add symbols `K`, `M`, `B`, and `T` (in `"en-US"`) to denote thousands, millions, billions, and trillions, respectively.
@@ -244,26 +280,26 @@ class props(ApiValidator):
             * **Notes**:
                 * No `legendNotationDisplay` option is provided for a `"standard"` legend notation
                 * The options `"short"` and `"long"` are only provided for the `"compact"` legend notation
-                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"` and `"engineering"` legend notations
+                * The options `"e"`, `"e+"`, `"E"`, `"E+"`, `"x10^"`, and `"x10^+"` are provided for the `"scientific"`, `"engineering"` and `"precision"` notations
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.legendNotationDisplay`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`legendMinLabel`**: `[str]` = `None` →
             * A custom and descriptive label in the Map Legend used to identify the lowest data point.
             * **Notes**:
                 * 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 min value within the node cluster is displayed.
                 * If left unspecified (i.e., `None`), it will default to `settings.defaults.legendMinLabel`.
-                * This attribute is applicable exclusively to `"num"` props.
+                * This attribute applies exclusively to `"num"` props.
         * **`legendMaxLabel`**: `[str]` = `None` →
             * A custom and descriptive label in the Map Legend used to identify the highest data point.
             * **Notes**:
                 * 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.
+                * This attribute applies exclusively to `"num"` props.
         * **`draggable`**: `[bool]` = `None` →
             * If `True`, the prop will be rendered within the draggable global outputs pad.
             * **Notes**:
                 * The prop's `variant` is enforced to `iconCompact` to accommodate it within the draggable pad.
-                * This attribute is applicable exclusively to `"num"` props defined within `cave_utils.api.globalOutputs`.
+                * This attribute applies exclusively to `"num"` props defined within `cave_utils.api.globalOutputs`.
         * **`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**:
@@ -273,30 +309,40 @@ class props(ApiValidator):
                             * 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.
-
+                * This attribute applies to all props except `"head"` props.
 
+        [react-icons]: https://react-icons.github.io/react-icons/search
         [metric prefix]: https://en.wikipedia.org/wiki/Metric_prefix
         [Scientific notation]: https://en.wikipedia.org/wiki/Scientific_notation
         [Engineering notation]: https://en.wikipedia.org/wiki/Engineering_notation
+        [Number.prototype.toPrecision]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision
         """
         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", "display"]
-        if type != "head":
-            optional_fields += ["enabled", "apiCommand", "apiCommandKeys", "allowNone"]
+        optional_fields = ["help", "variant", "display", "container"]
         if type == "head":
             if variant == "icon" or variant == "iconRow":
                 required_fields += ["icon"]
+        else:
+            optional_fields += ["enabled", "apiCommand", "apiCommandKeys", "allowNone"]
+
         if type == "text":
-            optional_fields += ["minRows", "maxRows", "rows"]
-        if type == "num":
+            optional_fields += ["minRows", "maxRows", "rows", "label", "placeholder"]
+        elif type == "num":
             if variant == "slider":
                 required_fields += ["maxValue", "minValue"]
+            elif variant == "incslider":
+                required_fields += ["valueOptions"]
             else:
                 optional_fields += ["maxValue", "minValue"]
+                if variant is None or variant == "field":
+                    optional_fields += [ "label", "placeholder"]
             if variant == "icon" or variant == "iconCompact":
                 required_fields += ["icon"]
+            if notationDisplay:
+                required_fields += ["notation"]
+            if legendNotationDisplay:
+                required_fields += ["legendNotation"]
             optional_fields += [
                 "unit",
                 "notation",
@@ -311,14 +357,20 @@ class props(ApiValidator):
                 "unitPlacement",
                 "draggable",
             ]
-        if type == "selector":
+        elif type == "selector":
             required_fields += ["options"]
             optional_fields += ["placeholder"]
-        if type == "date":
+            if variant == "comboboxMulti":
+                optional_fields += ["numVisibleTags"]
+        elif type == "date":
             optional_fields += ["views"]
+        elif type == "coordinate":
+            optional_fields += ["label", "placeholder"]
+
         missing_required = pamda.difference(required_fields, list(passed_values.keys()))
         if len(missing_required) > 0:
             raise Exception(f"Missing required fields: {str(missing_required)}")
+
         for k, v in passed_values.items():
             if k not in required_fields + optional_fields:
                 kwargs[k] = v
@@ -326,6 +378,7 @@ class props(ApiValidator):
             "compact": ["short", "long"],
             "scientific": ["e", "e+", "E", "E+", "x10^", "x10^+"],
             "engineering": ["e", "e+", "E", "E+", "x10^", "x10^+"],
+            "precision": ["e", "e+", "E", "E+", "x10^", "x10^+"],
             "standard": [],
         }
         notation = passed_values.get("notation", "standard")
@@ -339,17 +392,18 @@ class props(ApiValidator):
         return {
             "kwargs": kwargs,
             "accepted_values": {
-                "type": ["head", "num", "toggle", "button", "text", "selector", "date", "media"],
+                "type": ["head", "num", "toggle", "button", "text", "selector", "date", "media", "coordinate"],
+                "container": ["vertical", "horizontal", "titled", "untitled", "none"],
                 "views": view_options_dict.get(variant, []),
                 "unitPlacement": ["after", "afterWithSpace", "before", "beforeWithSpace"],
-                "notation": ["compact", "precision", "scientific", "engineering"],
+                "notation": ["standard", "compact", "scientific", "engineering", "precision"],
                 "notationDisplay": notationDisplay_options_dict.get(notation, []),
-                "legendNotation": ["compact", "precision", "scientific", "engineering"],
+                "legendNotation": ["standard", "compact", "scientific", "engineering", "precision"],
                 "legendNotationDisplay": notationDisplay_options_dict.get(legendNotation, []),
                 "variant": {
                     "head": ["column", "row", "icon", "iconRow"],
                     "text": ["single", "textarea"],
-                    "num": ["field", "slider", "icon", "iconCompact"],
+                    "num": ["field", "slider", "icon", "iconCompact", "incslider"],
                     "selector": [
                         "dropdown",
                         "checkbox",
@@ -362,6 +416,7 @@ class props(ApiValidator):
                     ],
                     "date": ["date", "time", "datetime"],
                     "media": ["picture", "video"],
+                    "coordinate": ["latLngInput", "latLngMap", "latLngPath"],
                 }.get(type, []),
             },
         }
@@ -389,7 +444,7 @@ class props_options(ApiValidator):
         * **`path`**: `[list[str]]` = `None` → The path to an option.
             * **Notes**:
                 * If `None`, the option will not be selectable
-                * This attribute is applicable exclusively to `"nested"` props
+                * This attribute applies exclusively to `"nested"` props
         """
         variant = kwargs.get("variant")
         kwargs = {k: v for k, v in kwargs.items() if k != "variant"}
@@ -421,6 +476,7 @@ class layout(ApiValidator):
         itemId: [str, None] = None,
         column: [int, None] = None,
         row: [int, None] = None,
+        style: [dict, None] = None,
         **kwargs,
     ):
         """
@@ -433,25 +489,29 @@ class layout(ApiValidator):
         * **`numColumns`**: `[str | int]` = `"auto"` → The number of columns for the grid layout.
             * **Notes**:
                 * If `"auto"`, the number of columns will be calculated based on the number of items.
-                * This attribute is applicable exclusively to `"grid"` layouts.
+                * This attribute applies exclusively to `"grid"` layouts.
         * **`numRows`**: `[str | int]` = `"auto"` → The number of rows for the grid layout.
             * **Notes**:
                 * If `"auto"`, the number of rows will be calculated based on the number of items.
-                * This attribute is applicable exclusively to `"grid"` layouts.
+                * This attribute applies exclusively to `"grid"` layouts.
         * **`data`**: `[dict]` = `None` → The data for the layout.
-            * **Note**: This attribute is applicable exclusively to `"grid"` layouts.
+            * **Note**: This attribute applies exclusively to `"grid"` layouts.
         * **`itemId`**: `[str]` = `None` → The id of the prop placed in the layout
-            * **Note**: This attribute is applicable exclusively to `"item"` layouts.
+            * **Note**: This attribute applies exclusively to `"item"` layouts.
         * **`column`**: `[int]` = `None` → The column in which to place the prop in the current grid.
         * **`row`**: `[int]` = `None` → The row in which to place the prop in the current grid.
+        * **`style`**: `[dict | None]` = `None` → Provides an escape hatch for specifying CSS rules.
+            * **Note**: In `"item"` layouts, the `style` is applied to the root of the prop container, while in `"grid"` layouts, it targets the CSS Grid layout level.
         """
         passed_values = {k: v for k, v in locals().items() if (v is not None) and k != "kwargs"}
+        required_fields = ["type"]
+        optional_fields = ["style"]
         if type == "grid":
-            required_fields = ["type", "data"]
-            optional_fields = ["numColumns", "numRows", "column", "row"]
-        if type == "item":
-            required_fields = ["type", "itemId"]
-            optional_fields = ["column", "row"]
+            required_fields += ["data"]
+            optional_fields += ["numColumns", "numRows", "column", "row"]
+        elif type == "item":
+            required_fields += ["itemId"]
+            optional_fields += ["column", "row"]
         missing_required = pamda.difference(required_fields, list(passed_values.keys()))
         if len(missing_required) > 0:
             raise Exception(f"Missing required fields: {str(missing_required)}")
@@ -467,9 +527,7 @@ class layout(ApiValidator):
             accepted_values["numColumns"] = ["auto"]
         return {
             "kwargs": kwargs,
-            "accepted_values": {
-                "type": ["grid", "item"],
-            },
+            "accepted_values": accepted_values,
         }
 
     def __extend_spec__(self, **kwargs):
@@ -523,6 +581,7 @@ class values(ApiValidator):
                 "selector": (list,),
                 "date": (str,),
                 "media": (str,),
+                "coordinate": (list,),
             }.get(prop_type, tuple())
             # Add None to acceptable types if allowed
             if prop_spec.get("allowNone", False):
@@ -551,6 +610,9 @@ class values(ApiValidator):
                 )
             elif prop_type == "media":
                 self.__check_url_valid__(prop_value, prepend_path=[prop_key])
+            elif prop_type == "coordinate":
+                coord_variant = prop_spec.get("variant", "latLngInput")
+                self.__check_coord_path_valid__(prop_value, coord_variant, prepend_path=[prop_key])
 
 
 @type_enforced.Enforcer

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/api_utils/validator_utils.py

@@ -189,6 +189,17 @@ class ApiValidator:
         except:
             self.__error__(path=prepend_path, msg=msg)
 
+    # TODO: Implement a color value validator: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+    def __check_color_string_valid__(self, color_string: str, prepend_path: list[str] = list()):
+        """
+        Validate a color string and if an issue is present, log an error
+        """
+        msg = "Invalid color string. Must be in a valid color format. See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value"
+        try:
+            self.__check_rgba_string_valid__(rgba_string, prepend_path)
+        except:
+            self.__error__(path=prepend_path, msg=msg)
+
     def __check_pixel_string_valid__(self, pixel_string: str, prepend_path: list[str] = list()):
         """
         Validate a pixel string and if an issue is present, log an error
@@ -289,13 +300,21 @@ class ApiValidator:
         return True
 
     def __check_coord_path_valid__(
-        self, coord_path: list[list[int, float]], prepend_path: list[str] = list()
+        self,
+        coord_path: list[list[int, float]],
+        coord_variant: str,
+        prepend_path: list[str] = list(),
     ):
         """
         Validate a coordinate path and if an issue is present, log an error
         """
         try:
-            if len(coord_path) < 2:
+            if (
+                coord_variant == "latLngPath"
+                and len(coord_path) < 2
+                or coord_variant != "latLngPath"
+                and len(coord_path) > 1
+            ):
                 self.__error__(path=prepend_path, msg="Invalid coordinate path")
                 return
             for coord in coord_path:

{cave_utils-2.2.1 → cave_utils-2.3.0}/cave_utils/geo_utils.py

@@ -38,20 +38,14 @@ class GeoUtils:
             * A list of dictionaries with additional properties for each path.
             * Note: The dictionaries must have the same length as the input lists.
             * Note: The dictionaries are imputed into the output GeoJSON as properties.
-
-        Optional Arguments:
-
-        * **`show_progress`**: `[bool]` →
-            * If True, shows the progress of the calculations.
-            * Default: False
-        * **`filename`**: `[str, None]` →
+        * **`show_progress`**: `[bool]` = `False` →
+            * If `True`, shows the progress of the calculations.
+        * **`filename`**: `[str, None]` = `None` →
             * If provided, saves the output GeoJSON to the specified filename.
-            * Default: None
 
         Returns:
 
         * **`output`**: `[dict]` → A GeoJSON dictionary with the shortest paths given the input data.
-
         """
         if not hasattr(geoGraph, "get_shortest_path"):
             raise ValueError("`geoGraph` must be a geoGraph object from scgraph")

{cave_utils-2.2.1 → cave_utils-2.3.0/cave_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cave_utils
-Version: 2.2.1
+Version: 2.3.0
 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

{cave_utils-2.2.1 → cave_utils-2.3.0}/pyproject.toml

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

{cave_utils-2.2.1 → cave_utils-2.3.0}/setup.cfg

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