diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md index d41bbd15e..b253f87a7 100644 --- a/vizro-core/docs/pages/user-guides/data.md +++ b/vizro-core/docs/pages/user-guides/data.md @@ -5,15 +5,34 @@ Vizro supports two different types of data: * [Static data](static-data.md): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data. * [Dynamic data](dynamic-data.md): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running. +The following flowchart shows what you need to consider when choosing how to set up your data. +``` mermaid +graph TD + refresh["`Do you need your data to refresh while the dashboard is running?`"] + specification["`Do you need to specify your dashboard through a configuration language like YAML?`"] + dynamic([Use dynamic data referenced by name]) + static-direct([Use static data supplied directly]) + static-name([Use static data referenced by name]) + + refresh -- No --> specification + refresh -- Yes --> dynamic + specification -- No --> static-direct + specification -- Yes --> static-name + + click static-direct href "../static-data#supply-directly" + click static-name href "../static-data#reference-by-name" + click dynamic href "../dynamic-data" +``` + ??? note "Static vs. dynamic data comparison" - Do not worry if you do not yet understand everything in this table. It will become clearer after reading more about [static data](static-data.md) and [dynamic data](dynamic-data.md)! + This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](static-data.md) and [dynamic data](dynamic-data.md)! | | Static | Dynamic | |---------------------------------------------------------------|------------------|------------------------------------------| | Required Python type | pandas DataFrame | Function that returns a pandas DataFrame | | Can be supplied directly in `data_frame` argument of `figure` | Yes | No | - | Can be referred to by name after adding to Data Manager | Yes | Yes | + | Can be referenced by name after adding to Data Manager | Yes | Yes | | Can be refreshed while dashboard is running | No | Yes | | Production-ready | Yes | Yes | diff --git a/vizro-core/docs/pages/user-guides/dynamic-data.md b/vizro-core/docs/pages/user-guides/dynamic-data.md index cd2072cb8..51a4e70a6 100644 --- a/vizro-core/docs/pages/user-guides/dynamic-data.md +++ b/vizro-core/docs/pages/user-guides/dynamic-data.md @@ -2,7 +2,7 @@ A dynamic data source is a Python function that returns a pandas DataFrame. This function is executed when the dashboard is initially started and _can be executed again while the dashboard is running_. This makes it possible to refresh the data shown in your dashboard without restarting the dashboard itself. If you do not this functionality then you should use [static data](static-data.md) instead. -Unlike static data, dynamic data cannot be supplied directly into the `data_frame` argument of a `figure`. Instead, it must first be added to the Data Manager and then referred to by name. +Unlike static data, dynamic data cannot be supplied directly into the `data_frame` argument of a `figure`. Instead, it must first be added to the Data Manager and then referenced by name. !!! example "Dynamic data" === "app.py" @@ -33,20 +33,20 @@ Unlike static data, dynamic data cannot be supplied directly into the `data_fram ``` 1. To use `load_iris_data` as dynamic data it must first be added to the Data Manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded. - 2. Dynamic data is referred to by the name of the data source `"iris"`. + 2. Dynamic data is referenced by the name of the data source `"iris"`. === "Result" [![DataBasic]][DataBasic] [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png -Since dynamic data sources must always be added to the Data Manager and referred to by name, they may be used in YAML configuration [exactly the same way as for static data sources](static-data.md#reference-by-name). +Since dynamic data sources must always be added to the Data Manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](static-data.md#reference-by-name). ## Configure cache By default, every time the dashboard is refreshed a dynamic data function will be executed again. This means that your dashboard will always show the very latest data. In fact, if there are multiple graphs on the same page using the same dynamic data source then the loading function will be executed _multiple_ times, once for each graph on the page. Hence, if loading your data is a slow operation, your dashboard performance may suffer. -The Vizro Data Manager has a caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off. +The Vizro Data Manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off. In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options: diff --git a/vizro-core/docs/pages/user-guides/static-data.md b/vizro-core/docs/pages/user-guides/static-data.md index c04e2332d..4d12c43d3 100644 --- a/vizro-core/docs/pages/user-guides/static-data.md +++ b/vizro-core/docs/pages/user-guides/static-data.md @@ -44,7 +44,7 @@ The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`] If you would like to specify your dashboard configuration through YAML then you must first add your data to the Data Manager, importable as `vizro.managers.data_manager`. The value of the `data_frame` argument in the YAML configuration should then refer to the name of your data in the Data Manager. -!!! example "Static data referred to by name" +!!! example "Static data referenced by name" === "app.py" ```py import yaml diff --git a/vizro-core/examples/_dev/app.py b/vizro-core/examples/_dev/app.py index 0574d016e..86b60f2b5 100644 --- a/vizro-core/examples/_dev/app.py +++ b/vizro-core/examples/_dev/app.py @@ -41,3 +41,5 @@ # app.run(processes=2, threaded=False) # gunicorn -w 2 app:server -b localhost:8050 # should also work with --preload + +# docs: serverside diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index 51ac3e663..3a96e3e48 100644 --- a/vizro-core/mkdocs.yml +++ b/vizro-core/mkdocs.yml @@ -94,7 +94,11 @@ markdown_extensions: generic: true - footnotes - pymdownx.details - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - pymdownx.mark @@ -104,6 +108,7 @@ markdown_extensions: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg + plugins: - search - autorefs diff --git a/vizro-core/src/vizro/managers/_data_manager.py b/vizro-core/src/vizro/managers/_data_manager.py index 52140a0f1..1b4eea18f 100644 --- a/vizro-core/src/vizro/managers/_data_manager.py +++ b/vizro-core/src/vizro/managers/_data_manager.py @@ -166,7 +166,7 @@ def __setattr__(self, name, value): # Any attributes that are only relevant for _DynamicData should go here to raise a clear error message. if name in ["timeout"]: raise AttributeError( - f"Static data that is a pandas.DataFrame itself does not support {name}; you should instead use a" + f"Static data that is a pandas.DataFrame itself does not support {name}; you should instead use a " "dynamic data source that is a function that returns a pandas.DataFrame." ) super().__setattr__(name, value)