1"""
  2# API
  3
  4This module serves to document the `cave_app` API data structures.
  5
  6## API Reference
  7
  8Classes represent the actual API items and should have relevant API documentation for each item at the class level. In this current module, the `root` class represents the root of the API. The method `spec` details exactly what must be passed to root as well as other relevant documentation.
  9
 10Submodules (and their classes) are used to define the api at each level. You can use the links on the left to navigate into the API and get detailed documentation for each API item at each level.
 11
 12See the left hand side for all available submodules.
 13"""
 14
 15from cave_utils.api_utils.validator_utils import *
 16from cave_utils.api.extraKwargs import extraKwargs
 17from cave_utils.api.settings import settings
 18from cave_utils.api.appBar import appBar
 19from cave_utils.api.panes import panes
 20from cave_utils.api.pages import pages
 21from cave_utils.api.maps import maps
 22from cave_utils.api.globalOutputs import globalOutputs
 23from cave_utils.api.mapFeatures import mapFeatures
 24from cave_utils.api.groupedOutputs import groupedOutputs
 25import type_enforced
 26
 27
 28@type_enforced.Enforcer
 29class Root(ApiValidator):
 30    """
 31    The root of the CAVE API data structure.
 32
 33    This should include all of the data needed to build out your application.
 34    """
 35
 36    @staticmethod
 37    def spec(
 38        settings: dict,
 39        appBar: dict = dict(),
 40        panes: dict = dict(),
 41        pages: dict = dict(),
 42        maps: dict = dict(),
 43        mapFeatures: dict = dict(),
 44        groupedOutputs: dict = dict(),
 45        globalOutputs: dict = dict(),
 46        extraKwargs: dict = dict(),
 47        **kwargs,
 48    ):
 49        """
 50        Arguments:
 51
 52        * **`settings`**: `[dict]` → General settings for your application.
 53            * **Note**: `settings.iconUrl` is the only required field in `settings`
 54            * **See**: `cave_utils.api.settings`
 55        * **`appBar`**: `[dict]` = `None` → Configure actions for your app bar(s).
 56            * **Notes**:
 57                * If left unspecified, there will be no action elements on the app bar.
 58                * Otherwise, `appBar.data` is required and should have at least one item in it.
 59            * **See**: `cave_utils.api.appBar`
 60        * **`panes`**: `[dict]` = `{}` → Configure panes for your application.
 61            * **See**: `cave_utils.api.panes`
 62        * **`pages`**: `[dict]` = `{}` → Configure pages for your application.
 63            * **See**: `cave_utils.api.pages`
 64        * **`maps`**: `[dict]` = `{}` → Configure map views and settings for your application.
 65            * **See**: `cave_utils.api.maps`
 66        * **`mapFeatures`**: `[dict]` = `{}` →
 67            * Configure map features (interactive items on the map) for your application.
 68            * **See**: `cave_utils.api.mapFeatures`
 69        * **`groupedOutputs`**: `[dict]` = `{}` →
 70            * Configure data that can be sliced and diced for charts and tables based on arbitrary groups.
 71            * **See**: `cave_utils.api.groupedOutputs`
 72        * **`globalOutputs`**: `[dict]` = `{}` →
 73            * Configure data that is general to the entire application and can be compared across sessions.
 74            * **See**: `cave_utils.api.globalOutputs`
 75        * **`extraKwargs`**: `[dict]` = `{}` → Special arguments to be passed to the server.
 76            * **See**: `cave_utils.api.extraKwargs`
 77        """
 78        kwargs = {k: v for k, v in kwargs.items() if k != "associated"}
 79        return {
 80            "kwargs": kwargs,
 81            "accepted_values": {},
 82        }
 83
 84    def __extend_spec__(self, **kwargs):
 85        # Validate Kwargs
 86        if "extraKwargs" in self.data:
 87            extraKwargs(
 88                data=self.data.get("extraKwargs", {}),
 89                log=self.log,
 90                prepend_path=["kwargs"],
 91                **kwargs,
 92            )
 93        # Validate Settings
 94        settings(
 95            data=self.data.get("settings", {}),
 96            log=self.log,
 97            prepend_path=["settings"],
 98            root_data=self.data,
 99            **kwargs,
100        )
101        # Special logic to add timeLength to kwargs
102        # This is used to validate timeValues across the app
103        kwargs["timeLength"] = pamda.path(["settings", "time", "timeLength"], self.data)
104        # Validate panes
105        panes_data = self.data.get("panes")
106        pane_validPaneIds = []
107        if panes_data is not None:
108            panes(data=panes_data, log=self.log, prepend_path=["panes"], **kwargs)
109            pane_validPaneIds = list(panes_data.get("data", {}).keys())
110        # Validate mapFeatures
111        mapFeatures_data = self.data.get("mapFeatures", dict())
112        mapFeatures_feature_props = {}
113        if mapFeatures_data != {}:
114            mapFeatures(
115                data=mapFeatures_data,
116                log=self.log,
117                prepend_path=["mapFeatures"],
118                **kwargs,
119            )
120            for key, value in mapFeatures_data.get("data", {}).items():
121                mapFeatures_feature_props[key] = value.get("props", {})
122        # Validate maps
123        maps_data = self.data.get("maps", dict())
124        maps_validMapIds = []
125        if maps_data != {}:
126            maps(
127                data=maps_data,
128                log=self.log,
129                prepend_path=["maps"],
130                mapFeatures_feature_props=mapFeatures_feature_props,
131                **kwargs,
132            )
133            maps_validMapIds = list(maps_data.get("data", {}).keys())
134        # Validate globalOutputs
135        globalOutputs_data = self.data.get("globalOutputs", dict())
136        globalOuputs_validPropIds = []
137        if globalOutputs_data != {}:
138            globalOutputs(
139                data=globalOutputs_data,
140                log=self.log,
141                prepend_path=["globalOutputs"],
142                **kwargs,
143            )
144            globalOuputs_validPropIds = list(globalOutputs_data.get("values", {}).keys())
145        # Validate groupedOutputs
146        groupedOutputs_data = self.data.get("groupedOutputs", dict())
147        groupedOutputs_validLevelIds = {}
148        groupedOutputs_validStatIds = {}
149        groupedOutputs_validDatasetIds = {}
150        if groupedOutputs_data != {}:
151            groupedOutputs(
152                data=groupedOutputs_data,
153                log=self.log,
154                prepend_path=["groupedOutputs"],
155                **kwargs,
156            )
157            # Populate valid ids for each relevant groupedOutput to be used in pages.
158            try:
159                groupedOutputs_validLevelIds = {
160                    k: list(v.get("levels").keys())
161                    for k, v in groupedOutputs_data.get("groupings", {}).items()
162                }
163            except:
164                pass
165            try:
166                groupedOutputs_validStatIds = {
167                    k: list(v.get("stats", []))
168                    for k, v in groupedOutputs_data.get("data", {}).items()
169                }
170            except:
171                pass
172            try:
173                groupedOutputs_validDatasetIds = {
174                    k: list(v.get("groupLists").keys())
175                    for k, v in groupedOutputs_data.get("data", {}).items()
176                }
177            except:
178                pass
179        # Validate pages
180        pages_data = self.data.get("pages", dict())
181        page_validPageIds = []
182        if pages_data != {}:
183            pages(
184                data=pages_data,
185                log=self.log,
186                prepend_path=["pages"],
187                # Special Kwargs to validate globalOutputs, groupedOutputs and maps are valid:
188                globalOuputs_validPropIds=globalOuputs_validPropIds,
189                maps_validMapIds=maps_validMapIds,
190                groupedOutputs_validLevelIds=groupedOutputs_validLevelIds,
191                groupedOutputs_validStatIds=groupedOutputs_validStatIds,
192                groupedOutputs_validDatasetIds=groupedOutputs_validDatasetIds,
193                **kwargs,
194            )
195            page_validPageIds = list(pages_data.get("data", {}).keys())
196        # Validate appBar
197        appBar_data = self.data.get("appBar", dict())
198        if appBar_data != {}:
199            appBar(
200                data=appBar_data,
201                log=self.log,
202                prepend_path=["appBar"],
203                # Special kwargs to validate panes and pages are valid:
204                page_validPageIds=page_validPageIds,
205                pane_validPaneIds=pane_validPaneIds,
206                **kwargs,
207            )