duck.html.components.core.lively_utils.file_request

File request: Lively WebSocket utilities module.

Module Contents

Classes

RequestedFileEntry

Requested file entry dataclass.

Functions

clean_requested_file

Clean up a requested file entry after it resolves, times out, or errors.

mark_file_upload_failed

Mark a pending file upload as failed.

mark_file_upload_started

Mark a pending file upload as started.

notify_file_upload_progress

Notify the server of a file upload’s current progress.

receive_ws_file

View for receiving an uploaded file from the client.

ws_request_file

Request a file from the client inside a Lively event handler.

Data

DEFAULT_FILE_TIMEOUT

DEFAULT_TOTAL_FILE_TIMEOUT

REQUESTED_FILES

STARTED_FILE_UPLOADS

API

duck.html.components.core.lively_utils.file_request.DEFAULT_FILE_TIMEOUT

30

duck.html.components.core.lively_utils.file_request.DEFAULT_TOTAL_FILE_TIMEOUT

None

exception duck.html.components.core.lively_utils.file_request.FileNotSelectedError[source]

Bases: duck.http.fileuploads.FileUploadError

Raised when no selected file on file input.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception duck.html.components.core.lively_utils.file_request.FileUploadNotFoundError[source]

Bases: duck.http.fileuploads.FileUploadError

Raised when a requested file upload cannot be found.

Initialization

Initialize self. See help(type(self)) for accurate signature.

duck.html.components.core.lively_utils.file_request.REQUESTED_FILES: Dict[str, duck.html.components.core.lively_utils.file_request.RequestedFileEntry]

None

class duck.html.components.core.lively_utils.file_request.RequestedFileEntry[source]

Requested file entry dataclass.

allowed_mimes: Optional[List[str]]

None

file_id: str

None

future: asyncio.Future

None

on_progress: Optional[Callable]

None

token_secret: str

None

duck.html.components.core.lively_utils.file_request.STARTED_FILE_UPLOADS: Dict[str, asyncio.Future]

None

duck.html.components.core.lively_utils.file_request.clean_requested_file(file_id: str)[source]

Clean up a requested file entry after it resolves, times out, or errors.

Parameters:

file_id – Unique identifier of the requested file.

duck.html.components.core.lively_utils.file_request.mark_file_upload_failed(file_id: str, reason: str = '', strict: bool = False) → bool[source]

Mark a pending file upload as failed.

Parameters:

  • file_id – Unique identifier of the file upload.

  • reason – Optional reason describing why the upload failed.

  • strict – Whether to raise FileUploadNotFoundError when the upload does not exist.

Returns:

True if the upload was successfully marked as failed, otherwise False when strict is False.

Raises:

  • FileUploadNotFoundError – If the upload does not exist and strict is True.

  • asyncio.InvalidStateError – If the upload has already been marked as failed or otherwise has a completed future.

duck.html.components.core.lively_utils.file_request.mark_file_upload_started(file_id: str, strict: bool = False) → bool[source]

Mark a pending file upload as started.

Parameters:

  • file_id – Unique identifier of the file upload.

  • strict – Whether to raise FileUploadNotFoundError when the upload does not exist.

Returns:

True if the upload was successfully marked as started, otherwise False when strict is False.

Raises:

  • FileUploadNotFoundError – If the upload does not exist and strict is True.

  • asyncio.InvalidStateError – If the upload has already been marked as started or otherwise has a completed future.

duck.html.components.core.lively_utils.file_request.notify_file_upload_progress(file_id: str, percent: float, strict: bool = False) → bool[source]

Notify the server of a file upload’s current progress.

Parameters:

  • file_id – Unique identifier of the file upload.

  • percent – Upload progress as a percentage (0-100).

  • strict – Whether to raise FileUploadNotFoundError when the upload does not exist.

Returns:

True if the progress was successfully notified, otherwise False when strict is False.

Raises:

FileUploadNotFoundError – If the upload does not exist and strict is True.

async duck.html.components.core.lively_utils.file_request.receive_ws_file(request) → duck.http.response.JsonResponse[source]

View for receiving an uploaded file from the client.

Saves the file using the configured upload handler and resolves the matching future so the waiting async_request_file call can continue.

Parameters:

request – Incoming Duck request carrying the multipart file upload.

Returns:

JSON response acknowledging receipt or describing the error.

async duck.html.components.core.lively_utils.file_request.ws_request_file(form_id: str, name: str, ws: duck.html.components.core.websocket.LivelyWebSocketView, *, allowed_mimes: Optional[List[str]] = None, on_progress: Optional[Callable[[int], None]] = None, timeout: float = DEFAULT_FILE_TIMEOUT, total_timeout=DEFAULT_TOTAL_FILE_TIMEOUT) → duck.http.fileuploads.BaseFileUpload[source]

Request a file from the client inside a Lively event handler.

Sends a command over the websocket telling the client to open a file picker and upload the selected file to the receiving view, then waits for that upload to complete.

Parameters:

  • form_id – The ID of the form to target.

  • name – Name of the file to request (usually the name of the file input).

  • ws – Active Lively websocket connection for the current client.

  • allowed_mimes – Optional list of mimetypes to expect from client.

  • on_progress – Optional callable to call on file upload progress. Defaults to None.

  • timeout – Seconds to wait before giving up on the upload.

  • total_timeout – Total seconds in overall for the whole file upload to finish.

Returns:

BaseFileUpload instance inheriting from io.BytesIO.

Raises:

  • TimeoutError – If the client does not upload a file in time.

  • ValueError – If on_progress is not None and not a callable.