Release v0.2.6

dkedar7 · Sep 4, 2023 · 184794c · 184794c
2 parents dc7f222 + 2d1db75
commit 184794c
Show file tree

Hide file tree

Showing 13 changed files with 784 additions and 278 deletions.
diff --git a/.github/codecov.yaml b/.github/codecov.yaml
@@ -0,0 +1,6 @@
+coverage:
+  status:
+    project:
+      default:
+        target: 90%    # the required coverage value
+    patch: off
diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml
@@ -68,7 +68,7 @@ jobs:
 
       - uses: codecov/codecov-action@v1
         with:
-          fail_ci_if_error: true
+          fail_ci_if_error: false
           files: coverage.xml
 
       - name: Build wheels and source tarball

diff --git a/docs/Examples/04_land_cover_map_with_geemap.ipynb b/docs/Examples/04_land_cover_map_with_geemap.ipynb
@@ -0,0 +1,129 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1cb94cfb",
+   "metadata": {},
+   "source": [
+    "[![Open in colab](https://colab.research.google.com/assets/colab-badge.svg)](https://githubtocolab.com/dkedar7/fast_dash/blob/docs/docs/Examples/04_land_cover_map_with_geemap.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ce363e40",
+   "metadata": {},
+   "source": [
+    "This notebook is optimized to run in Google Colab.\n",
+    "\n",
+    "We'll use the amazing Geemap library for this demo.\n",
+    "Learn more about Geemap at https://geemap.org/."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "15601ea1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install fast-dash geemap jupyter_dash"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "2f402652",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ee\n",
+    "import geemap.foliumap as geemap\n",
+    "\n",
+    "from fast_dash import fastdash, html, Fastify"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0e6bceca",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Authenticate Google Earth Engine\n",
+    "ee.Authenticate()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "9153b0d3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Define years over which we'll compare land cover\n",
+    "years = ['2001', '2004', '2006', '2008', '2011', '2013', '2016', '2019']\n",
+    "\n",
+    "# Using Fastify, Fast Dash allows making any Dash component suitable with Fast Dash\n",
+    "iframe_component = Fastify(component=html.Iframe(height=\"100%\"), \n",
+    "                           component_property=\"srcdoc\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "99030b06",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Build and deploy!\n",
+    "# If running locally, feel free to drop the mode and port arguments.\n",
+    "\n",
+    "@fastdash(theme=\"Zephyr\", mode=\"inline\", port=5000)\n",
+    "def compare_land_cover(year_of_left_layer: str = years, \n",
+    "                       year_of_right_layer: str = years) -> iframe_component:\n",
+    "    \"Compare how land cover in the US changed over the years\"\n",
+    "\n",
+    "    # Geemap code. Ref: https://huggingface.co/spaces/giswqs/geemap/blob/main/app.py\n",
+    "    Map = geemap.Map(center=(40, -100), zoom=4, height=600)\n",
+    "\n",
+    "    nlcd_left = ee.Image(\n",
+    "        f\"USGS/NLCD_RELEASES/2019_REL/NLCD/{year_of_left_layer}\"\n",
+    "    ).select(\"landcover\")\n",
+    "    nlcd_right = ee.Image(\n",
+    "        f\"USGS/NLCD_RELEASES/2019_REL/NLCD/{year_of_right_layer}\"\n",
+    "    ).select(\"landcover\")\n",
+    "\n",
+    "    left_layer = geemap.ee_tile_layer(nlcd_left, {}, f\"NLCD {year_of_left_layer}\")\n",
+    "    right_layer = geemap.ee_tile_layer(nlcd_right, {}, f\"NLCD {year_of_right_layer}\")\n",
+    "\n",
+    "    Map.split_map(left_layer, right_layer)\n",
+    "\n",
+    "    # Convert to HTML\n",
+    "    land_cover_map = Map.to_html()\n",
+    "\n",
+    "    return land_cover_map"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.16"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/User guide/build.md b/docs/User guide/build.md
diff --git a/docs/User guide/components.md b/docs/User guide/components.md
@@ -4,7 +4,7 @@ Fast components are the UI components that represent the input and outputs eleme
 
 Fast Dash borrows the concept of `component_property` from Dash. `component_property` is the answer to the question - __"Which property of a component should be assigned the value returned by the callback function?"__
 
-For example, if the first argument of a Fast Dash callback function is a `str` and we want to represent this input using a component that allows users to enter text. Say we decide to use the `dbc.Input()` Dash component. By reading the documentation of the component [here](https://dash-bootstrap-components.opensource.faculty.ai/docs/components/input/), you'll realize that we must update the `value` property of `dbc.Input()` for it work as expected. And therefore, when defining a Fast component for this input we'd use `component_property="value"`.
+For example, if the first argument of a Fast Dash callback function is a `str`, we must represent this input using a component that allows users to enter text. Say we decide to use the `dbc.Input()` Dash component. On referring to the documentation of the component [here](https://dash-bootstrap-components.opensource.faculty.ai/docs/components/input/), you'll realize that we must update the `value` property of `dbc.Input()` for it to work as expected. And therefore, when defining a Fast component for this input we would use `component_property="value"`.
 
 We use this design and the fact that Fast Dash allows using Fast components as type hints, in addition of standard Python data types, to write a simple app that takes text entered by users as the first input.
 
@@ -34,16 +34,47 @@ def your_function(input_text: text_input_component, ...):
     from fast_dash import Text, Slider, Upload, UploadImage, Image, Graph
     ```
 
-??? note "Dash components vs Fast components"
+!!! note "Dash components vs Fast components"
 
-    If you have used Dash, you will know that we have to specify a `component_property` to Dash's `Input` and `Output` methods when defining our callback functions (during runtime). In other words, you can develop Dash UI before writing your callback functions.
+    Dash components are interactive UI components that you can use to create web applications with Dash. Dash ships with supercharged core components (`dash.dcc`), and standard HTML components (`dash.html`) suitable for almost any task and data type.
 
-    On the contrary, Fast Dash **infers** components (when not specified) by studying the underlying callback function, particularly its type hints and default values. For that reason, it becomes essential for us to specify the `component_property` before we define our callback function.
+    Fast components are Dash components with some additional attributes to make them suitable for use by Fast Dash.
+
+    If you have used Dash, you will know that it requires us to specify a `component_property` argument to Dash's `Input` and `Output` methods when defining our callback functions (during runtime). In other words, we can develop Dash UI before writing our callback functions.
+
+    On the contrary, Fast Dash **infers** components (when not specified) by studying the underlying callback function, particularly its type hints and default values.
+
+## Can Dash components be used as Fast Components?
+
+**Yes!**
+
+However, Dash components have to be converted to Fast components before Fast Dash uses them. In most cases, Fast Dash performs that conversion automatically. But in the other cases, we can easily use the `Fastify` utility function to do that conversion ourselves.
+
+Here's a list of all Dash components that Fast Dash natively converts to Fast components without worrying the user.
 
-## How are they different from Dash components
 
 ## How to transform Dash components into Fast components
 
-## The special acknowledgement (ack) components
+If the Dash components you want to use isn't in the list of components you want to use with Fast Dash or if you want to update a different `component_property` of the component, then the `Fastify` function comes to your rescue.
+
+Use this syntax to do the conversion:
 
-## Some examples
+```py
+...
+from fastdash import Fastify
+
+fast_component = Fastify(component=dash_component, component_property=...)
+```
+
+For example, Fast Dash doesn't natively support automatic conversion of [Dash bio components](https://dash.plotly.com/dash-bio/molecule2dviewer) to Fast components. But, `Fastify` can convert any Dash component to a Fast component. Say, we wanted to use `dash.bio.Molecule2dViewer` to view a molecule:
+
+```py
+from fast_dash import fastdash, Fastify
+from dashbio import Molecule2dViewer
+
+molecule_fast_component = Fastify(component=Molecule2dViewer(), 
+                                    component_property="modelData")
+
+def view_molecule(...) -> molecule_fast_component:
+    ...
+```
diff --git a/docs/User guide/deployment.md b/docs/User guide/deployment.md
@@ -1,46 +1,49 @@
 # Deployment
 
-Fast Dash apps can be deployed as regular Dash apps. A universal and hence the preferred method to deploy is to containers the applications and then deploy to a public cloud endpoint.
+Fast Dash apps are deployed as any other Flask app. A universal and hence the recommended way to deploy is to containerize the application and then deploy it to an endpoint.
 
 Here're the general steps involved with the deployment process:
 
-1. Add a `Dockerfile` in the same directory that contains the main Fast Dash app module.
-2. Create `wsgi.py` Python script in the same path.
+1. Extract the Flask server from the `FastDash` app object (`server = app.server`).
+2. Add a `Dockerfile` in the same directory that contains the main Fast Dash app module.
 3. Build and run Docker container.
 
-The recommended directory structure is this:
+The recommended directory structure is:
 
 ```
 root\
 - app.py
 - requirements.txt
-- ....py  # (Other scripts that your Fast Dash app needs)
+- Dockerfile
+- ....py (Other scripts that your Fast Dash app needs)
+- ... (Other dependencies)
 ```
 
-With these steps in mind, let's see how we can deploy our simple text-to-text Fast Dash app to the most used cloud services.
+With these steps in mind, let's see how we can deploy our simple text-to-text Fast Dash app to Google Cloud Run. We can use the same process to deploy to any service that deploys web applications as Docker containers, like Hugging Face spaces.
 
 ## 1. Google Cloud Run
 
-### Step 1. Get started with Google Cloud
+### Step 0. Get started with Google Cloud
 
 Get started with Google Cloud [here](https://cloud.google.com/). If you already have an account, proceed to the console and select Cloud Run from the list of services.
 
-Although not mandatory, it's highly recommended to get access to the [`gcloud` command line utility](https://cloud.google.com/sdk/docs/install). The `gcloud` CLI reduces the deployment down to just a single line of code.
+Although not mandatory, it's highly recommended to get access to the [`gcloud` command line utility](https://cloud.google.com/sdk/docs/install). The `gcloud` CLI reduces the lines of code need to deploy apps down to just one!
 
-### Step 2. Add `wsgi.py`
+### Step 1. Extract Flask server object
 
-Add `wsgi.py` Python script to the current directory. Modify it and add the following lines:
+Note that `@fastdash` decorators are not recommended for production deployment. So if you've been using the decorator to develop the app locally, use the `FastDash` class instead for production deployments. Then, simply define the server object with `app.server`.
 
-```python
-from app import app
-server = app.app.server
+```py
+...
+app = FastDash(callback_function, ...)
+server = app.server
 ```
 
-`server` is the Flask object that gets deployed. We need to isolate it from the rest of the app code so that we can instruct `gunicorn` in the next step to deploy it inside our Docker container.
+`server` is the Flask object that gets deployed. We need to isolate it so we can instruct `gunicorn` in the next step to deploy it inside our Docker container.
 
 ### Step 3. Create `Dockerfile`
 
-Create a new file in the current path and modify it to reflect the following:
+Create a Dockerfile in the current path and modify it to reflect the following:
 
 ```
 FROM python:3.9-slim
@@ -56,22 +59,10 @@ RUN pip3 install --no-cache-dir -r requirements.txt
 CMD exec gunicorn wsgi:server --bind :$PORT
 ```
 
-### Step 4. Modify `requirements.txt`
+### Step 4. Update `requirements.txt`
 
 Add `gunicorn` to the list of dependencies in `requirements.txt`.
 
-
-At this stage, the root path of your app should have this structure:
-
-```
-root\
-- app.py
-- requirements.txt
-- wsgi.py
-- Dockerfile
-- ....py  # (Other scripts that your Fast Dash app needs)
-```
-
 ### Step 5. Deploy! 🚀
 
 If the `gcloud` CLI was correctly installed in step 1, simply run this command from the root of your project directory:
@@ -80,13 +71,6 @@ If the `gcloud` CLI was correctly installed in step 1, simply run this command f
 gcloud run deploy
 ```
 
-You will be asked to enter a few different settings for your app. Read Google Cloud Run's documentation here to understand what each of them mean.
-
-Generally, choosing the following settings is acceptable:
-
-1. Source code location: Enter the directory with `Dockerfile`. If you are already in the project `root`, then this directory is preselected. Simply hit `Enter`.
-2. Service name: Type the app name of hit `Enter` to select default.
-3. Please specify a region: Choose the number corresponding to your nearest region.
-4. Allow unauthenticated invocations to: Select `y` if you understand and are okay with the repercussions.
+You will be asked to choose a few different settings for your deployment. Read Google Cloud Run's documentation here to understand what each of them mean.
 
-That's it! Google Cloud will build your app inside a Docker container and display the URL here once it's ready. The entire operation can take upto 5 minutes for simple applications. The build time highly depends on the complexity of your app and the number of dependencies.
+That's it! Google Cloud will build your app inside a Docker container and display the URL once it's ready. The entire operation can take upto five minutes for simple applications. The build time highly depends on the complexity of your app and the number of dependencies.
diff --git a/docs/history.md b/docs/history.md
@@ -1,15 +1,11 @@
 # History
 
-# Release 0.2.5
-
 ## 0.2.5 (2023-08-13)
 
 ### Improvements
 
 - Fix: `update_live` is automatically set to `True` if the callback function doesn't require any inputs.
 
-# Release 0.2.4
-
 ## 0.2.4 (2023-08-12)
 
 ### Improvements
@@ -18,8 +14,6 @@
 - `outputs` argument overrides callback function output hints.
 - Improve pytest coverage.
 
-# Release 0.2.3
-
 ## 0.2.3 (2023-08-01)
 
 ### Features
@@ -28,8 +22,6 @@
 - Added a mosaic layout example to README.
 - `dash` can be imported from `fast_dash` like this: `from fast_dash import dash`.
 
-# Release 0.2.2
-
 ## 0.2.2 (2023-07-26)
 
 ### Features