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,
 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]` → Configure actions for your app bar(s).
 56            * **Note**: `appBar.data` is required and should have at least one item in it.
 57            * **See**: `cave_utils.api.appBar`
 58        * **`panes`**: `[dict]` = `{}` → Configure panes for your application.
 59            * **See**: `cave_utils.api.panes`
 60        * **`pages`**: `[dict]` = `{}` → Configure pages for your application.
 61            * **See**: `cave_utils.api.pages`
 62        * **`maps`**: `[dict]` = `{}` → Configure map views and settings for your application.
 63            * **See**: `cave_utils.api.maps`
 64        * **`mapFeatures`**: `[dict]` = `{}` →
 65            * Configure map features (interactive items on the map) for your application.
 66            * **See**: `cave_utils.api.mapFeatures`
 67        * **`groupedOutputs`**: `[dict]` = `{}` →
 68            * Configure data that can be sliced and diced for charts and tables based on arbitrary groups.
 69            * **See**: `cave_utils.api.groupedOutputs`
 70        * **`globalOutputs`**: `[dict]` = `{}` →
 71            * Configure data that is general to the entire application and can be compared across sessions.
 72            * **See**: `cave_utils.api.globalOutputs`
 73        * **`extraKwargs`**: `[dict]` = `{}` → Special arguments to be passed to the server.
 74            * **See**: `cave_utils.api.extraKwargs`
 75        """
 76        kwargs = {k: v for k, v in kwargs.items() if k != "associated"}
 77        return {
 78            "kwargs": kwargs,
 79            "accepted_values": {},
 80        }
 81
 82    def __extend_spec__(self, **kwargs):
 83        # Validate Kwargs
 84        if "extraKwargs" in self.data:
 85            extraKwargs(
 86                data=self.data.get("extraKwargs", {}),
 87                log=self.log,
 88                prepend_path=["kwargs"],
 89                **kwargs,
 90            )
 91        # Validate Settings
 92        settings(
 93            data=self.data.get("settings", {}),
 94            log=self.log,
 95            prepend_path=["settings"],
 96            root_data=self.data,
 97            **kwargs,
 98        )
 99        # Special logic to add timeLength to kwargs
100        # This is used to validate timeValues across the app
101        kwargs["timeLength"] = pamda.path(["settings", "time", "timeLength"], self.data)
102        # Validate panes
103        panes_data = self.data.get("panes")
104        pane_validPaneIds = []
105        if panes_data is not None:
106            panes(data=panes_data, log=self.log, prepend_path=["panes"], **kwargs)
107            pane_validPaneIds = list(panes_data.get("data", {}).keys())
108        # Validate mapFeatures
109        mapFeatures_data = self.data.get("mapFeatures", dict())
110        mapFeatures_feature_props = {}
111        if mapFeatures_data != {}:
112            mapFeatures(
113                data=mapFeatures_data,
114                log=self.log,
115                prepend_path=["mapFeatures"],
116                **kwargs,
117            )
118            for key, value in mapFeatures_data.get("data", {}).items():
119                mapFeatures_feature_props[key] = value.get("props", {})
120        # Validate maps
121        maps_data = self.data.get("maps", dict())
122        maps_validMapIds = []
123        if maps_data != {}:
124            maps(
125                data=maps_data,
126                log=self.log,
127                prepend_path=["maps"],
128                mapFeatures_feature_props=mapFeatures_feature_props,
129                **kwargs,
130            )
131            maps_validMapIds = list(maps_data.get("data", {}).keys())
132        # Validate globalOutputs
133        globalOutputs_data = self.data.get("globalOutputs", dict())
134        globalOuputs_validPropIds = []
135        if globalOutputs_data != {}:
136            globalOutputs(
137                data=globalOutputs_data,
138                log=self.log,
139                prepend_path=["globalOutputs"],
140                **kwargs,
141            )
142            globalOuputs_validPropIds = list(globalOutputs_data.get("values", {}).keys())
143        # Validate groupedOutputs
144        groupedOutputs_data = self.data.get("groupedOutputs", dict())
145        groupedOutputs_validLevelIds = {}
146        groupedOutputs_validStatIds = {}
147        groupedOutputs_validDatasetIds = {}
148        if groupedOutputs_data != {}:
149            groupedOutputs(
150                data=groupedOutputs_data,
151                log=self.log,
152                prepend_path=["groupedOutputs"],
153                **kwargs,
154            )
155            # Populate valid ids for each relevant groupedOutput to be used in pages.
156            try:
157                groupedOutputs_validLevelIds = {
158                    k: list(v.get("levels").keys())
159                    for k, v in groupedOutputs_data.get("groupings", {}).items()
160                }
161            except:
162                pass
163            try:
164                groupedOutputs_validStatIds = {
165                    k: list(v.get("stats", []))
166                    for k, v in groupedOutputs_data.get("data", {}).items()
167                }
168            except:
169                pass
170            try:
171                groupedOutputs_validDatasetIds = {
172                    k: list(v.get("groupLists").keys())
173                    for k, v in groupedOutputs_data.get("data", {}).items()
174                }
175            except:
176                pass
177        # Validate pages
178        pages_data = self.data.get("pages", dict())
179        page_validPageIds = []
180        if pages_data != {}:
181            pages(
182                data=pages_data,
183                log=self.log,
184                prepend_path=["pages"],
185                # Special Kwargs to validate globalOutputs, groupedOutputs and maps are valid:
186                globalOuputs_validPropIds=globalOuputs_validPropIds,
187                maps_validMapIds=maps_validMapIds,
188                groupedOutputs_validLevelIds=groupedOutputs_validLevelIds,
189                groupedOutputs_validStatIds=groupedOutputs_validStatIds,
190                groupedOutputs_validDatasetIds=groupedOutputs_validDatasetIds,
191                **kwargs,
192            )
193            page_validPageIds = list(pages_data.get("data", {}).keys())
194        # Validate appBar
195        appBar_data = self.data.get("appBar", dict())
196        if appBar_data != {}:
197            appBar(
198                data=appBar_data,
199                log=self.log,
200                prepend_path=["appBar"],
201                # Special kwargs to validate panes and pages are valid:
202                page_validPageIds=page_validPageIds,
203                pane_validPaneIds=pane_validPaneIds,
204                **kwargs,
205            )