Skip to main content

Files

Wave provides four functions to manage files from your app:

  • ui.file_upload() allows uploading files from the browser to the Wave server.
  • q.site.upload() uploads files from your app to the Wave server.
  • q.site.download() downloads a file from the Wave server to your app.
  • q.site.unload() deletes a file from the Wave server.

Accept file uploads​

Use a file upload component (ui.file_upload()) to accept file uploads from the browser. Files get uploaded from the browser and get stored on the Wave server. Use q.site.download() to download files from the Wave server to your app.

from h2o_wave import Q, main, app, ui

@app('/uploads')
async def serve(q: Q):
    paths = q.args.datasets
    if not paths:
        q.page['example'] = ui.form_card(box='1 1 4 10', items=[
            ui.text_xl('Upload datasets'),
            ui.file_upload(name='datasets', label='Upload', multiple=True),
        ])
    else:
        for path in paths:
            local_path = await q.site.download(path, '.')
            # Do something with the file located at local_path
            # ...
    await q.page.save()
tip

After a file is uploaded from the browser, it is stored forever on the Wave server. If you don't need the file any longer, use q.site.unload() to delete it from the Wave server.

Provide file downloads​

Use q.site.upload() to upload files from your app to the Wave server. Use the returned paths to display download links in the browser and a download attribute to initiate the download process right after the click.

from h2o_wave import Q, main, app, ui

@app('/downloads')
async def serve(q: Q):
    download_path, = await q.site.upload(['results.csv'])
    q.page['download'] = ui.form_card(box='1 1 2 2', items = [
        ui.link(label='Download Results', path=download_path, download=True),
    ])
    await q.page.save()

See download link for more info.

tip

q.site.upload() accepts a list of file paths, so you can upload multiple files at a time.

Use q.site.upload_dir() to upload whole directories and preserve their structure. Useful when you want to host Javascript files having relative paths to other scripts for example. The function returns a list of uploaded paths and since it only takes a single directory at a time, the list is always going to have size of 1.

tip

q.site.upload_dir() is necessary only in very specific edgecases. For most of the time we recommend serving files directly.

danger

If running Wave on Windows, you might encounter a 500 internal error during q.site.upload call due to lack of permissions since Wave server needs to write to your file system. The simple solution is to start the Wave server (or wave run your_app.py for Wave > 0.20.0) within a terminal with Admin rights (open terminal as Admin).

Serving images​

Use q.site.upload() to upload images from your app to the Wave server. Use the returned paths in ui.image() or `ui.image_card().

image, = await q.site.upload(['path/to/my/image.png'])
q.page['example'] = ui.form_card(box='1 1 4 4', items=[
    ui.image(title='Image title', image=image, type='png'),
])

Serving image streams​

Use image streams to display images that can be updated in near real time, say for use cases such as real time object detection in videos or webcam streams. This feature lets you display an initial image on a web page, then follow up with updated images (or frames).

Use q.site.uplink() to stream a frame. This function returns the path to an image that can be passed to ui.image() or ui.image_card(), or any UI or HTML element that accepts an image source.

Use q.site.unlink() to signal the end of a stream.

@app('/demo')
async def serve(q: Q):
    # Create stream by sending initial image
    path = await q.site.uplink('my_stream', 'image/jpeg', my_image)

    # Display image on page
    q.page['qux'] = ui.form_card(box='1 1 5 5', items=[ui.image('Image Stream', path=path)])
    await q.page.save()

    # Update image
    for i in range(100):
        await q.site.uplink('my_stream', 'image/jpeg', my_image)

    # Stop stream
    await q.site.unlink('my_stream')

See examples/file_stream.py for a complete example.

Rendering documents​

Use q.site.upload() to upload document from your app to the Wave server (or see the following section for other ways for serving files). Use the returned paths in ui.frame() component.

q.app.document_path, = await q.site.upload(['path/to/my/document.pdf'])
q.page['example'] = ui.form_card(box='1 1 7 7', items=[
    ui.frame(path=document_path)
])

Serving files directly from the Wave server​

As an alternative to using the above upload() or download() mechanisms, you can make the Wave server (waved) directly serve the contents of one or more existing directories. If the Wave server and your app both have access to the directories on the file system, your app can simply create or copy files to the directories to make them accessible from web browsers.

Serve the contents of directory /home/zaphod/data at http://localhost:10101/datasets/

waved -public-dir /datasets/@/home/zaphod/data

Serve the contents of directory /home/zaphod/data at http://localhost:10101/datasets/, and /home/zaphod/models at http://localhost:10101/public/models

waved -public-dir /datasets/@/home/zaphod/data -public-dir /public/models/@/home/zaphod/models

Serve the contents of directory /home/zaphod/data at http://localhost:10101/datasets/, but only to authenticated users.

waved -private-dir /datasets/@/home/zaphod/data

Serve the contents of directory /home/zaphod/data at http://localhost:10101/datasets/, and /home/zaphod/models at http://localhost:10101/public/models, but only to authenticated users.

waved -private-dir /datasets/@/home/zaphod/data -private-dir /public/models/@/home/zaphod/models

Note that any number of -public-dir and -private-dir arguments are allowed.