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