duck.http.fileuploads.handlers

Module containing classes for storing uploaded file data.

Package Contents

Classes

BaseFileUpload	Base class for storing file uploads data.
PersistentFileUpload	Class for persistent storage of file uploads on disk in a specified directory.
TemporaryFileUpload	Class for temporarily storing file upload data in memory.

API

class duck.http.fileuploads.handlers.BaseFileUpload(filename: str, initial_bytes: bytes = b'', **kw)

Bases: io.BytesIO

Base class for storing file uploads data.

Variables:

• initial_bytes – The initial byte content of the file.

• filename – The name of the file.

• name – Name of the form field for this File. (optional)

• content_type – The mimetype of the uploaded content. (optional)

• content_disposition – The file upload content disposition. (optional)

Initialization

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

__repr__()

async async_save()

Asynchronously save the data - defaults to wrapped save() using ensure_async.

getsize()

Returns the file IO object total bytes.

geturl(absolute=True)

Get the URL for accessing the uploaded file.

Returns:

The URL for accessing the uploaded file.

Return type:

str

guess_mimetype() → Optional[str]

Returns the guessed mimetype for the uploaded file.

Notes

• This method guesses the mimetype for the file upload using the provided bytes rather than the the filename, because it bypasses altered filenames thereby increasing security.

normalize_filename() → str

Normalize the filename by spaces or invalid characters.

Returns:

The normalized filename.

Return type:

str

abstractmethod save()

Save the uploaded data. This method should be implemented by subclasses.

Raises:

NotImplementedError – If the method is not implemented by subclasses.

save_to_file(filepath: str)

Save the uploaded data to a file.

Parameters:

filepath – The path where the file will be saved.

Returns:

The number of bytes written.

Return type:

int

verify(allowed_mimes: list[str] | None = None) → None

Verify the uploaded file’s declared MIME type against its detected type.

Parameters:

allowed_mimes – Optional MIME types permitted for the upload.

Raises:

• FileTypeNotAllowedError – If the detected MIME type is not allowed.

• FileVerificationError – If the declared MIME type does not match the detected MIME type.

… admonition:: Notes

The detected MIME type should be determined from the file’s content (for example, using magic bytes), not from its filename or extension.

exception duck.http.fileuploads.handlers.FileTypeNotAllowedError

Bases: duck.http.fileuploads.handlers.FileUploadError

Raised when a detected data mimetype doesn’t match any mime in allowed mimes list.

Initialization

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

exception duck.http.fileuploads.handlers.FileUploadError

Bases: Exception

Base exception class for file upload errors

Initialization

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

exception duck.http.fileuploads.handlers.FileVerificationError

Bases: duck.http.fileuploads.handlers.FileUploadError

Raised on verification failure for uploaded files.

Initialization

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

class duck.http.fileuploads.handlers.PersistentFileUpload(filename: str, initial_bytes: bytes = b'', directory: str = SETTINGS['FILE_UPLOAD_DIR'], overwrite_existing_file=True, **kw)

Bases: duck.http.fileuploads.handlers.BaseFileUpload

Class for persistent storage of file uploads on disk in a specified directory.

Variables:

• filename – The name of the file.

• initial_bytes – The initial byte content of the file.

• directory – The directory where the file will be saved.

• overwrite_existing_file – Whether to overwrite existing file in directory when saving

Initialization

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

save()

Save the uploaded data by writing it to the specified file path.

save_to_file()

Save the uploaded data to the specified file path.

Returns:

The number of bytes written.

Return type:

int

class duck.http.fileuploads.handlers.TemporaryFileUpload(filename: str, initial_bytes: bytes = b'', **kw)

Bases: duck.http.fileuploads.handlers.BaseFileUpload

Class for temporarily storing file upload data in memory.

Initialization

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

abstractmethod save()

Save the uploaded data. In this case, the method does nothing.