0.2.0 - add typehints for components

Add a module `components.typehints` for providing annotations of the component properties.

Author: cainmagi

Changelog.md

@@ -13,6 +13,7 @@
 3. Add the cross-origin support when serving the data to clients (e.g. the browser).
 4. Add the external URL proxy support for fetching the cross-origin resources.
 5. Add a service `ServiceDownloader` which allows the MITM served by the local device.
+6. Add a module `components.typehints` for providing annotations of the component properties.
 
 #### :wrench: Fix
 

dash_file_cache/__init__.py

@@ -33,7 +33,7 @@
 # Import frequently-used classes.
 from .caches import CachePlain, CacheQueue, CacheFile
 from .services import ServiceData, ServiceDownloader
-from .components import PlainDownloader, Downloader
+from .components import PlainDownloader, Downloader, DownloaderURL, DownloaderStatus
 
 __all__ = (
     "__version__",
@@ -49,6 +49,8 @@
     "ServiceDownloader",
     "PlainDownloader",
     "Downloader",
+    "DownloaderURL",
+    "DownloaderStatus",
 )
 
 _js_dist = []

dash_file_cache/caches/typehints.py

@@ -14,7 +14,7 @@
 
 Description
 -----------
-Extra typehints used by this project.
+Extra typehints used by the definition of caches.
 """
 
 import os

dash_file_cache/components/__init__.py

@@ -31,8 +31,17 @@
 from ._imports_ import PlainDownloader, Downloader
 from ._imports_ import __all__ as __import_all__
 
+from . import typehints
+from .typehints import DownloaderURL, DownloaderStatus
 
-__all__ = ("PlainDownloader", "Downloader")
+
+__all__ = (
+    "typehints",
+    "PlainDownloader",
+    "Downloader",
+    "DownloaderURL",
+    "DownloaderStatus",
+)
 
 if not hasattr(_dash, "__plotly_dash") and not hasattr(_dash, "development"):
     print(

dash_file_cache/components/typehints.py

@@ -0,0 +1,62 @@
+"""
+Typehints
+=========
+@ Dash File Cache: components
+
+Author
+------
+Yuchen Jin (cainmagi)
+cainmagi@gmail.com
+
+License
+-------
+MIT License
+
+Description
+-----------
+Extra typehints used for annotating the component properties.
+"""
+
+from typing_extensions import Literal, TypedDict
+
+
+__all__ = ("DownloaderURL", "DownloaderStatus")
+
+
+class DownloaderURL(TypedDict):
+    """The component property `Downloader(url=...)`.
+
+    The URL used to access the data to be downloaded.
+
+    Each time when this value is set, a download event will be triggered. After
+    triggering the download event, this value will be reset by a blank string.
+    """
+
+    url: str
+    """The URL used to access the data to be downloaded."""
+
+    file_name_fallback: str
+    """A maunally configured file name. If this file name is configured, it will
+    be used when the file name cannot be parsed in the headers. This configuration
+    is useful when the URL is from a cross-origin site."""
+
+
+class DownloaderStatus(TypedDict):
+    """The component property `Downloader(status=...)`.
+
+    The status code when a downloading event is finalized.
+
+    If multiple downloading events are triggered by the same downloader, the later
+    event will overwrite the status from the former events.
+    """
+
+    type: Literal[
+        "success", "error-connect", "error-config", "error-io", "error-unknown"
+    ]
+    """The status code of the event. If the event is successful, this value should.
+    be "success" once the downloading event is finalized.
+    """
+
+    http_code: int
+    """The HTTP code from the response. If the event is successful, this value should
+    be in the range of 200-299.."""

examples/download_file.py

@@ -42,7 +42,7 @@
     sys.path.append(os.path.dirname(os.path.dirname(__file__)))
 
 from dash_file_cache import CacheFile
-from dash_file_cache import Downloader
+from dash_file_cache import Downloader, DownloaderStatus
 from dash_file_cache import ServiceData, ServiceDownloader
 
 
@@ -72,6 +72,7 @@ def layout(self) -> html.Div:
                 html.Div((html.P(("Progress:", html.Span(id="prog"))))),
                 html.Div((html.P("Cache type:"), html.P(id="type"))),
                 html.Div((html.P("Cache address:"), html.P(id="addr"))),
+                html.Div((html.P("Downloader status:"), html.P(id="dlstats"))),
                 Downloader(id="download", mitm="/dfc-downloader"),
             ),
         )
@@ -119,6 +120,16 @@ def trigger_downloading_event(addr):
                 return dash.no_update
             return addr
 
+        @app.callback(
+            Output("dlstats", "children"),
+            Input("download", "status"),
+            prevent_initial_call=True,
+        )
+        def trigger_downloading_status(status: Optional[DownloaderStatus]):
+            if not status:
+                return ""
+            return str(status)
+
 
 class WrappedApp:
     """A wrapped app. This wrapped app is accessed by the tests."""