solara-ui 1.31.0__py2.py3-none-any.whl

solara/components/file_browser.py

@@ -0,0 +1,182 @@
+import os
+from os.path import isfile, join
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Union, cast
+
+import humanize
+import ipyvuetify as vy
+import traitlets
+
+import solara
+from solara.components import Div
+
+
+def list_dir(path, filter: Callable[[Path], bool] = lambda x: True, directory_first: bool = False) -> List[dict]:
+    def mk_item(n):
+        full_path = join(path, n)
+        is_file = isfile(full_path)
+        return {"name": n, "is_file": is_file, "size": humanize.naturalsize(os.stat(full_path).st_size) if is_file else None}
+
+    files = [mk_item(k) for k in os.listdir(path) if not k.startswith(".") if filter(Path(path) / k)]
+    sorted_files = sorted(files, key=lambda item: (item["is_file"] == directory_first, item["name"].lower()))
+
+    return sorted_files
+
+
+class FileListWidget(vy.VuetifyTemplate):
+    template_file = (__file__, "file_list_widget.vue")
+
+    files = traitlets.List(cast(List[Dict], [])).tag(sync=True)
+    clicked = traitlets.Dict(allow_none=True, default_value=None).tag(sync=True)
+    double_clicked = traitlets.Dict(allow_none=True, default_value=None).tag(sync=True)
+    scroll_pos = traitlets.Int(allow_none=True).tag(sync=True)
+
+    def test_click(self, path: Union[Path, str], double_click=False):
+        """Simulate a click or double click at the Python side"""
+        matches = [k for k in self.files if k["name"] == str(path)]
+        if len(matches) == 0:
+            names = [k["name"] for k in self.files]
+            raise NameError(f"Could not find {path}, possible filenames: {names}")
+        item = matches[0]
+        if double_click:
+            self.double_clicked = item
+        else:
+            self.clicked = item
+
+    def __contains__(self, name):
+        """Test if filename/directory name is in the current directory."""
+        return name in [k["name"] for k in self.files]
+
+
+@solara.component
+def FileBrowser(
+    directory: Union[None, str, Path, solara.Reactive[Path]] = None,
+    on_directory_change: Callable[[Path], None] = None,
+    on_path_select: Callable[[Optional[Path]], None] = None,
+    on_file_open: Callable[[Path], None] = None,
+    filter: Callable[[Path], bool] = lambda x: True,
+    directory_first: bool = False,
+    on_file_name: Callable[[str], None] = None,
+    start_directory=None,
+    can_select=False,
+):
+    """File/directory browser at the server side.
+
+    There are two modes possible
+
+     * `can_select=False`
+       * `on_file_open`: Triggered when **single** clicking a file or directory.
+       * `on_path_select`: Never triggered
+       * `on_directory_change`: Triggered when clicking a directory
+     * `can_select=True`
+       * `on_file_open`: Triggered when **double** clicking a file or directory.
+       * `on_path_select`: Triggered when clicking a file or directory
+       * `on_directory_change`: Triggered when double clicking a directory
+
+    ## Arguments
+
+     * `directory`: The directory to start in. If `None` the current working directory is used.
+     * `on_directory_change`: Depends on mode, see above.
+     * `on_path_select`: Depends on mode, see above.
+     * `on_file_open`: Depends on mode, see above.
+     * `filter`: A function that takes a `Path` and returns `True` if the file/directory should be shown.
+     * `directory_first`: If `True` directories are shown before files. Default: `False`.
+     * `on_file_name`: (deprecated) Use on_file_open instead.
+     * `start_directory`: (deprecated) Use directory instead.
+    """
+    if start_directory is not None:
+        directory = start_directory  # pragma: no cover
+    if directory is None:
+        directory = os.getcwd()  # pragma: no cover
+    if isinstance(directory, str):
+        directory = Path(directory)
+    current_dir = solara.use_reactive(directory)
+    selected, set_selected = solara.use_state(None)
+    double_clicked, set_double_clicked = solara.use_state(None)
+    warning, set_warning = solara.use_state(cast(Optional[str], None))
+    scroll_pos_stack, set_scroll_pos_stack = solara.use_state(cast(List[int], []))
+    scroll_pos, set_scroll_pos = solara.use_state(0)
+    selected, set_selected = solara.use_state(None)
+
+    def change_dir(new_dir: str):
+        if os.access(new_dir, os.R_OK):
+            current_dir.value = Path(new_dir)
+            if on_directory_change:
+                on_directory_change(Path(new_dir))
+            set_warning(None)
+            return True
+        else:
+            set_warning(f"[no read access to {new_dir}]")
+
+    def on_item(item, double_click):
+        if item is None:
+            if can_select and on_path_select:
+                on_path_select(None)
+            return
+        if item["name"] == "..":
+            current_dir_str = str(current_dir.value)
+            new_dir = current_dir_str[: current_dir_str.rfind(os.path.sep)]
+            action_change_directory = (can_select and double_click) or (not can_select and not double_click)
+            if action_change_directory and change_dir(new_dir):
+                if scroll_pos_stack:
+                    last_pos = scroll_pos_stack[-1]
+                    set_scroll_pos_stack(scroll_pos_stack[:-1])
+                    set_scroll_pos(last_pos)
+                set_selected(None)
+                set_double_clicked(None)
+                if on_path_select and can_select:
+                    on_path_select(None)
+            if can_select and not double_click:
+                if on_path_select:
+                    on_path_select(Path(new_dir))
+            return
+
+        path = os.path.join(current_dir.value, item["name"])
+        is_file = item["is_file"]
+        if (can_select and double_click) or (not can_select and not double_click):
+            if is_file:
+                if on_file_open:
+                    on_file_open(Path(path))
+                if on_file_name is not None:
+                    on_file_name(path)
+            else:
+                if change_dir(path):
+                    set_scroll_pos_stack(scroll_pos_stack + [scroll_pos])
+                    set_scroll_pos(0)
+                set_selected(None)
+            set_double_clicked(None)
+            if on_path_select and can_select:
+                on_path_select(None)
+        elif can_select and not double_click:
+            if on_path_select:
+                on_path_select(Path(path))
+        else:  # not can_select and double_click is ignored
+            raise RuntimeError("Combination should not happen")  # pragma: no cover
+
+    def on_click(item):
+        set_selected(item)
+        on_item(item, False)
+
+    def on_double_click(item):
+        set_double_clicked(item)
+        if can_select:
+            on_item(item, True)
+        # otherwise we can ignore it, single click will handle it
+
+    files = [{"name": "..", "is_file": False}] + list_dir(current_dir.value, filter=filter, directory_first=directory_first)
+    with Div(class_="solara-file-browser") as main:
+        Div(children=[str(current_dir.value)])
+        FileListWidget.element(
+            files=files,
+            selected=selected,
+            clicked=selected,
+            on_clicked=on_click,
+            double_clicked=double_clicked,
+            on_double_clicked=on_double_click,
+            scroll_pos=scroll_pos,
+            on_scroll_pos=set_scroll_pos,
+        ).key("FileList")
+        if warning:
+            Div(style_="font-weight: bold; color: red", children=[warning])
+
+    return main

solara/components/file_download.py

@@ -0,0 +1,199 @@
+from pathlib import Path
+from typing import BinaryIO, Callable, List, Optional, Union, cast
+
+import ipyvuetify as vy
+import ipywidgets as widgets
+import traitlets
+
+import solara
+
+
+class FileDownloadWidget(vy.VuetifyTemplate):
+    template_file = (__file__, "download.vue")
+    children = traitlets.List(cast(List[solara.Element], [])).tag(sync=True, **widgets.widget_serialization)
+    filename = traitlets.Unicode().tag(sync=True)
+    bytes = traitlets.Bytes(None, allow_none=True).tag(sync=True)
+    mime_type = traitlets.Unicode("application/octet-stream").tag(sync=True)
+    request_download = traitlets.Bool(False).tag(sync=True)
+
+
+@solara.component
+def FileDownload(
+    data: Union[str, bytes, BinaryIO, Callable[[], Union[str, bytes, BinaryIO]]],
+    filename: Optional[str] = None,
+    label: Optional[str] = None,
+    icon_name: Optional[str] = "mdi-cloud-download-outline",
+    close_file: bool = True,
+    mime_type: str = "application/octet-stream",
+    string_encoding: str = "utf-8",
+    children=[],
+):
+    """Download a file or data.
+
+    ## Simple usage
+
+    By default, if no children are provided, a button is created with the label "Download: {filename}".
+
+    ```solara
+    import solara
+
+    data = "This is the content of the file"
+
+    @solara.component
+    def Page():
+        solara.FileDownload(data, filename="solara-download.txt", label="Download file")
+    ```
+
+    ## Advanced usage
+
+    If children are provided, they are displayed instead of the button. The children can be any solara component,
+    including a button, markdown text, or an image.
+
+    ```solara
+    import solara
+
+    data = "This is the content of the file"
+
+    @solara.component
+    def Page():
+        with solara.FileDownload(data, "solara-download-2.txt"):
+            solara.Markdown("Any text, or even an image")
+            solara.Image("https://solara.dev/static/public/beach.jpeg", width="200px")
+    ```
+
+    ## Custom button
+
+    If children are provided, they are displayed instead of the button. The children can be any solara component,
+    including a button, markdown text, or an image.
+
+    ```solara
+    import solara
+
+    data = "This is the content of the file"
+
+    @solara.component
+    def Page():
+        with solara.FileDownload(data, "solara-download-2.txt"):
+            solara.Button("Custom download button", icon_name="mdi-cloud-download-outline", color="primary")
+    ```
+
+    ## Usage with file
+
+    A file object can be used as data. The file will be closed after downloading by default.
+
+    ```solara
+    import solara
+    import pandas as pd
+
+    df = pd.DataFrame({"id": [1, 2, 3], "name": ["John", "Mary", "Bob"]})
+
+    @solara.component
+    def Page():
+        file_object = df.to_csv(index=False)
+        solara.FileDownload(file_object, "users.csv", mime_type="application/vnd.ms-excel")
+    ```
+
+    If a file like object is used, we try to base the filename on the file object.
+    ```solara
+    import solara
+    import solara.website.pages
+    import os
+
+    filename = os.path.dirname(solara.website.__file__) + "/public/beach.jpeg"
+
+    @solara.component
+    def Page():
+        # only open the file once by using use_memo
+        file_object = solara.use_memo(lambda: open(filename, "rb"), [])
+        # no filename is provided, but we can extract it from the file object
+        solara.FileDownload(file_object, mime_type="image/jpeg", close_file=False)
+    ```
+
+    ## Lazy reading
+
+    Not only is the data lazily uploaded to the browser, but also the data is only read when the download is requested.
+    This happens for files by default, but can also be used by passing in a callback function.
+
+    ```solara
+    import solara
+    import time
+
+    @solara.component
+    def Page():
+        def get_data():
+            # I run in a thread, so I can do some heavy processing
+            time.sleep(3)
+            # I only get called when the download is requested
+            return "This is the content of the file"
+        solara.FileDownload(get_data, "solara-lazy-download.txt")
+    ```
+
+    ## Arguments
+
+     * `data`: The data to download. Can be a string, bytes, or a file like object, or a function that returns one of these.
+     * `filename`: The name of the file the user will see as default when downloading (default name is "solara-download.dat").
+        If a file object is provided, the filename will be extracted from the file object if possible.
+     * `label`: The label of the button. If not provided, the label will be "Download: {filename}".
+     - `icon_name`: The name of the icon to display on the button ([Overview of available icons](https://pictogrammers.github.io/@mdi/font/4.9.95/)).
+     * `close_file`: If a file object is provided, close the file after downloading (default True).
+     * `mime_type`: The mime type of the file. If not provided, the mime type will be "application/octet-stream",
+           For instance setting it to "application/vnd.ms-excel" will allow the user OS to directly open the
+           file into Excel.
+     * `string_encoding`: The encoding to use when converting a string to bytes (default "utf-8").
+
+    ## Note on file size
+
+    Note that the data will be kept in memory when downloading.
+    If the file is large (>10 MB), and when using [Solara server](/documentation/advanced/understanding/solara-server), we recommend using the
+    [static files directory](/documentation/advanced/reference/static-files) instead.
+
+    """
+    request_download, set_request_download = solara.use_state(False)
+
+    # if the data changes, we 'reset'
+    def reset():
+        nonlocal request_download
+        request_download = False
+        set_request_download(False)
+
+    solara.use_memo(reset, [data])
+
+    # we only upload to the frontend if clicked
+    def get_data() -> Optional[bytes]:
+        if request_download:
+            if callable(data):
+                data_non_lazy = data()
+            else:
+                data_non_lazy = data
+            if hasattr(data_non_lazy, "read"):
+                if hasattr(data_non_lazy, "seek"):
+                    if hasattr(data_non_lazy, "tell") and data_non_lazy.tell() != 0:
+                        data_non_lazy.seek(0)
+                content = data_non_lazy.read()  # type: ignore
+                if close_file:
+                    data_non_lazy.close()  # type: ignore
+                return content
+            elif isinstance(data_non_lazy, str):
+                return data_non_lazy.encode(string_encoding)
+            else:
+                return cast(bytes, data_non_lazy)
+        return None
+
+    bytes_result: solara.Result[Optional[bytes]] = solara.use_thread(get_data, dependencies=[request_download, data])
+    if filename is None and hasattr(data, "name"):
+        try:
+            filename = Path(data.name).name  # type: ignore
+        except Exception:
+            pass
+    filename = filename or "solara-download.dat"
+    label = label or ("Download: " + filename)
+    FileDownloadWidget.element(
+        filename=filename,
+        bytes=bytes_result.value if bytes_result.state == solara.ResultState.FINISHED else None,
+        request_download=request_download,
+        on_request_download=set_request_download,
+        children=children or [solara.Button(label, loading=bytes_result.state == solara.ResultState.RUNNING, icon_name=icon_name)],
+        mime_type=mime_type,
+    )
+    if bytes_result.state == solara.ResultState.ERROR and bytes_result.error:
+        raise bytes_result.error

solara/components/file_drop.py

@@ -0,0 +1,139 @@
+import threading
+import typing
+from typing import Any, Callable, List, Optional, Union, cast
+
+import traitlets
+from ipyvue import Template
+from ipyvuetify.extra import FileInput
+from ipywidgets import widget_serialization
+from typing_extensions import TypedDict
+
+import solara
+import solara.hooks as hooks
+
+
+class FileInfo(TypedDict):
+    name: str
+    size: int
+    file_obj: typing.BinaryIO
+    data: Optional[bytes]
+
+
+class FileDropZone(FileInput):
+    # override to narrow traitlet of FileInput
+    template = traitlets.Instance(Template).tag(sync=True, **widget_serialization)
+    template_file = (__file__, "file_drop.vue")
+    items = traitlets.List(default_value=cast(List[Any], [])).tag(sync=True)
+    label = traitlets.Unicode().tag(sync=True)
+    multiple = traitlets.Bool(True).tag(sync=True)
+
+
+@solara.component
+def _FileDrop(
+    label="Drop file(s) here",
+    on_total_progress: Optional[Callable[[float], None]] = None,
+    on_file: Optional[Callable[[Union[FileInfo, List[FileInfo]]], None]] = None,
+    lazy: bool = True,
+    multiple: bool = False,
+):
+    """Generic implementation used by FileDrop and FileDropMultiple.
+
+    If multiple=True, multiple files can be uploaded.
+    """
+
+    file_info, set_file_info = solara.use_state(None)
+    wired_files, set_wired_files = solara.use_state(cast(Optional[typing.List[FileInfo]], None))
+
+    file_drop = FileDropZone.element(label=label, on_total_progress=on_total_progress, on_file_info=set_file_info, multiple=multiple)  # type: ignore
+
+    def wire_files():
+        if not file_info:
+            return
+
+        real = cast(FileDropZone, solara.get_widget(file_drop))
+
+        # workaround for @observe being cleared
+        real.version += 1
+        real.reset_stats()
+
+        set_wired_files(cast(typing.List[FileInfo], real.get_files()))
+
+    solara.use_side_effect(wire_files, [file_info])
+
+    def handle_file(cancel: threading.Event):
+        if not wired_files:
+            return
+        if on_file:
+            for i in range(len(wired_files)):
+                if not lazy:
+                    wired_files[i]["data"] = wired_files[i]["file_obj"].read()
+                else:
+                    wired_files[i]["data"] = None
+            if multiple:
+                on_file(wired_files)
+            else:
+                on_file(wired_files[0])
+
+    result: solara.Result = hooks.use_thread(handle_file, [wired_files])
+    if result.error:
+        raise result.error
+
+    return file_drop
+
+
+@solara.component
+def FileDrop(
+    label="Drop file here",
+    on_total_progress: Optional[Callable[[float], None]] = None,
+    on_file: Optional[Callable[[FileInfo], None]] = None,
+    lazy: bool = True,
+):
+    """Region a user can drop a file into for file uploading.
+
+    If lazy=True, no file content will be loaded into memory,
+    nor will any data be transferred by default.
+    If lazy=False, file content will be loaded into memory and passed to the `on_file` callback via the `FileInfo.data` attribute.
+
+
+    A file object is of the following argument type:
+    ```python
+    class FileInfo(typing.TypedDict):
+        name: str  # file name
+        size: int  # file size in bytes
+        file_obj: typing.BinaryIO
+        data: Optional[bytes]: bytes  # only present if lazy=False
+    ```
+
+
+    ## Arguments
+     * `on_total_progress`: Will be called with the progress in % of the file upload.
+     * `on_file`: Will be called with a `FileInfo` object, which contains the file `.name`, `.length` and a `.file_obj` object.
+     * `lazy`: Whether to load the file contents into memory or not. If `False`,
+        the file contents will be loaded into memory via the `.data` attribute of file object(s).
+
+    """
+
+    return _FileDrop(label=label, on_total_progress=on_total_progress, on_file=on_file, lazy=lazy, multiple=False)
+
+
+@solara.component
+def FileDropMultiple(
+    label="Drop files here",
+    on_total_progress: Optional[Callable[[float], None]] = None,
+    on_file: Optional[Callable[[List[FileInfo]], None]] = None,
+    lazy: bool = True,
+):
+    """Region a user can drop multiple files into for file uploading.
+
+    Almost identical to `FileDrop` except that multiple files can be dropped and `on_file` is called
+    with a list of `FileInfo` objects.
+
+    ## Arguments
+     * `on_total_progress`: Will be called with the progress in % of the file(s) upload.
+     * `on_file`: Will be called with a `List[FileInfo]`.
+        Each `FileInfo` contains the file `.name`, `.length`, `.file_obj` object, and `.data` attributes.
+     * `lazy`: Whether to load the file contents into memory or not.
+
+    """
+
+    return _FileDrop(label=label, on_total_progress=on_total_progress, on_file=on_file, lazy=lazy, multiple=True)

solara/components/file_drop.vue

@@ -0,0 +1,83 @@
+<template>
+  <div ref="dropzone" class="solara-file-drop" effectAllowed="move">
+    <template v-if="file_info && file_info.length > 0">
+      <template v-if="multiple">
+        <div v-for="file in file_info">
+          {{ file.name }}
+        </div>
+      </template>
+      <template v-else>
+        {{ file_info[0].name }}
+      </template>
+    </template>
+    <template v-else>
+      {{ label }}
+    </template>
+  </div>
+</template>
+
+<script>
+module.exports = {
+  mounted() {
+    this.chunk_size = 2 * 1024 * 1024;
+    this.$refs.dropzone.addEventListener('dragover', event => {
+      event.preventDefault();
+    });
+
+    this.$refs.dropzone.addEventListener('drop', async event => {
+      event.preventDefault();
+      const items = await Promise.all([...event.dataTransfer.items]);
+      const files = items.map(i => i.webkitGetAsEntry())
+      const fileHolders = files.filter(f => f.isFile)
+      const nativeFilesPromises = fileHolders.map(fileHolder => new Promise((rs, rj) => fileHolder.file(rs, rj)))
+      const nativeFiles = await Promise.all(nativeFilesPromises)
+
+      this.native_file_info = nativeFiles
+      this.file_info = this.native_file_info.map(
+        ({name, size}) => ({
+          name,
+          isFile: true,
+          size,
+        }));
+    });
+  },
+  methods: {
+    jupyter_clear() {
+      this.native_file_info = [];
+      this.file_info = [];
+    },
+    jupyter_read(chunk) {
+      const {id, file_index, offset, length} = chunk;
+      let to_do = length;
+      let sub_offset = offset;
+
+      (async () => {
+        while (to_do > 0) {
+          console.log(this.chunk_size, to_do);
+          const sub_length = Math.min(to_do, this.chunk_size);
+
+          const file = this.native_file_info[file_index];
+          const blob = file.slice(sub_offset, sub_offset + sub_length);
+          const buff = await blob.arrayBuffer();
+
+          const msg = {id, file_index, offset: sub_offset, length: sub_length}
+          this.upload(msg, [buff]);
+
+          to_do -= sub_length
+          sub_offset += sub_length
+        }
+      })();
+    }
+  }
+}
+</script>
+
+<style id="solara-file-drop">
+.solara-file-drop {
+  height: 100px;
+  border: 1px dashed gray;
+  margin: 8px 0;
+  padding: 8px;
+  overflow: auto;
+}
+</style>

solara/components/file_list_widget.vue

@@ -0,0 +1,78 @@
+<template>
+  <v-sheet class="solara-file-list" ref="scrollpane"
+      @click="clicked = null"
+  >
+    <v-list
+      @click="clicked = null"
+    >
+      <v-list-item
+          v-for="{name, is_file, size} in files"
+          :key="name + '|' + is_file"
+          @click.stop="clicked = { name, is_file }"
+          @dblclick="double_clicked = { name, is_file }"
+          :class="(clicked && clicked.name == name) ? 'solara-file-list-selected': ''"
+      >
+        <v-list-item-icon>
+          <v-icon>{{ name === '..' ? 'mdi-keyboard-backspace' : is_file ? 'mdi-file-document' : 'mdi-folder' }}</v-icon>
+        </v-list-item-icon>
+
+        <v-list-item-content>
+          <v-list-item-title :class="'solara-file-list-' + (is_file ? 'file' : 'dir')">
+            {{ name }}<span v-if="size"> - {{ size }}</span>
+          </v-list-item-title>
+        </v-list-item-content>
+      </v-list-item>
+    </v-list>
+  </v-sheet>
+</template>
+
+<script>
+module.exports = {
+  mounted() {
+    const element = this.$refs.scrollpane.$el
+    element.scrollTop = this.scroll_pos
+
+    this._scrollListener = _.debounce((e) => {
+      this.scroll_pos = Math.round(element.scrollTop)
+    }, 50)
+    element.addEventListener('scroll', this._scrollListener)
+  },
+  watch: {
+    scroll_pos(v) {
+      this.$nextTick(() => this.$refs.scrollpane.$el.scrollTop = v);
+    }
+  }
+}
+</script>
+
+<style id="solara-file-list">
+.solara-file-list {
+  height: 400px;
+  overflow: auto;
+}
+
+.solara-file-list-dir {
+  font-weight: bold;
+}
+
+.solara-file-list-selected {
+  background-color: #3333;
+
+}
+
+.solara-file-list .v-list-item__icon,
+.solara-file-list .v-list-item__list {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+.v-application--is-ltr .solara-file-list .v-list-item__icon {
+  margin-right: 8px;
+}
+
+.solara-file-list .v-list-item {
+  height: 28px;
+  min-height: 0;
+  padding-left: 0;
+}
+</style>