The future syntax of du.callback and UploadStatus objects

[fohrloop]

Currently, dash-uploader callbacks can be added with the syntax which resembles dash callbacks:

@du.callback(
    output=Output('callback-output', 'children'),
    id='dash-uploader',
)
def get_a_list(filenames):
    return html.Ul([html.Li(filenames)])

As the current version of dash-uploader (0.6.0) really supports only one-file uploads, the filenames will always be a list of one string, where the string is the absolute filepath of the uploaded file on the server.

Now, the work on the flow-dev branch aims to make it possible to upload multiple files. Then, a plan for the callback syntax should be made. The changes may be backward incompatible as the version is still in 0.x.x .

Possible syntax

The possible new syntax should not be designed from the technical point of view, but instead made to be as simple and easy to use from the user's point of view as possible. There are two different events that might be interesting for the user

• A file was uploaded
• All files in "upload job" were uploaded

callback implementation details

How the dash callbacks really work is that:

• A property in JS/React is put under monitoring. Currently it is the this.props.isCompleted of the Upload_ReactComponent defined in the src\lib\components\Upload_ReactComponent.react.js.
• Whenever, in the JS/React side, the props is changed with this.props.setProps (dash-specific special prop that is passed to every component of a Dash app), a HTTP request is used to trigger a change in the attribute/property of a dash python component.
• Now, the isCompleted can be changed for example when the Javascript component finishes uploading. In reality, a JS component only knows when it sent the last chunk. Therefore, some logic must be made which assures that the file really has been uploaded and received and the chunks have been merged into a file succesfully. This is because callback logic might assume that there really is a file that can be accessed immediately with the python code in the dash app.
• As there can be events for "one file completed" and "all files completed", I suggest that instead of this.props.isCompleted there will be this.props.uploadedFiles and this.props.allUploadsCompleted or similar.

In the python side, the callback for the user could look like this:

@du.callback(
    output=Output('callback-output', 'children'),
    id='dash-uploader',
)
def get_a_list(filenames, finished):
    return html.Ul([html.Li(x) for x in filenames])

This would:

• Fire in case of filenames is changed; that is, whenever there is a new file that has finished uploading
• Not fire when finished changes (all files uploaded), as uploading files a, b and c would already trigger with filenames being ["C:\path\a", "C:\path\b", "C:\path\c"], and user would just need to check if finished is True or False to know if this was the last file.

dash_uploader.UploadStatus objects ?

I'm considering, if it would be wiser to start using UploadStatus objects in the callbacks instead. This would make it easier to make adjustments in the dash-uploader API later on, if needed. For example, if it would be needed to add n_files_total (total number of files to be uploaded) and n_files_uploaded (number of files uploaded so far), and perhaps last_uploaded (last uploaded file). Then, the callback structure would need to be updated to be:

@du.callback(
    output=Output('callback-output', 'children'),
    id='dash-uploader',
)
def get_a_list(filenames, finished, n_files_total, n_files_uploaded, last_uploaded):
    return html.Ul([html.Li(x) for x in filenames])

and the list might get longer. This would potentially cause some breaking changes when users would update dash-uploader. A very long list of arguments makes the API ugly and cumbersome, and would be aesthetically unpleasing if a user just wants the filenames and does not care about the other parameters.

Another possibility would be syntax like:

@du.callback(
    output=Output('callback-output', 'children'),
    id='dash-uploader',
)
def get_a_list(filenames, *args, **kwargs):
    return html.Ul([html.Li(x) for x in filenames])

Or just **kwargs. This would ensure that there will be no backwards incompatible changes. But, then users would always need to refer to the documentation to access kwargs['some_parameter'], and the access syntax is uglier than simple status.some_parameter.

The UploadStatus object would then allow syntax like:

@du.callback(
    output=Output('callback-output', 'children'),
    id='dash-uploader',
)
def get_a_list(status):
    print(status.n_files_uploaded, status.n_files_total)
    return html.Ul([html.Li(x) for x in status.filenames])

If user uses python Type Annotations, then the syntax could be:

@du.callback(
    output=Output('callback-output', 'children'),
    id='dash-uploader',
)
def get_a_list(status: du.UploadStatus):
    print(status.n_files_uploaded, status.n_files_total)
    return html.Ul([html.Li(x) for x in status.filenames])

This might also make it possible that the IDE would suggest/tell the available attributes of the status object.

[fohrloop]

I created a diagram about how the internals of dash-uploader work, and put it here (also at docs/how-dash-uploader-works.svg).

It seems that the fileSuccess event is only fired in the React side when the post() method of the HttpRequestHandler returns; i.e. when the file has been written to disk (created from the chunks). Therefore there should be no race condition. This means that this.props.setProps can be called (changing props that are listened by du.callbacks) at the fileSuccess. The prop that triggers changes in the server side should be set last.