Multipart Forms

class microdot.multipart.FormDataIter(request)

Asynchronous iterator that parses a multipart/form-data body and returns form fields and files as they are parsed.

Parameters:

request – the request object to parse.

Example usage:

from microdot.multipart import FormDataIter

@app.post('/upload')
async def upload(request):
    async for name, value in FormDataIter(request):
        print(name, value)

The iterator returns no values when the request has a content type other than multipart/form-data. For a file field, the returned value is of type FileUpload, which supports the read() and save() methods. Values for regular fields are provided as strings.

The request body is read efficiently in chunks of size buffer_size. On iterations in which a file field is encountered, the file must be consumed before moving on to the next iteration, as the internal stream stored in FileUpload instances is invalidated at the end of the iteration.

buffer_size = 256

The size of the buffer used to read chunks of the request body. This size must be large enough to hold at least one complete header or boundary line, so it is not recommended to lower it, but it can be made higher to improve performance at the expense of RAM.

class microdot.multipart.FileUpload(filename, content_type, read)

Class that represents an uploaded file.

Parameters:

• filename – the name of the uploaded file.

• content_type – the content type of the uploaded file.

• read – a coroutine that reads from the uploaded file’s stream.

An uploaded file can be read from the stream using the read() method or saved to a file using the save() method.

Instances of this class do not normally need to be created directly.

max_memory_size = 1024

The size at which the file is copied to a temporary file.

async read(n=-1)

Read up to n bytes from the uploaded file’s stream.

Parameters:

n – the maximum number of bytes to read. If n is -1 or not given, the entire file is read.

async save(path_or_file)

Save the uploaded file to the given path or file object.

Parameters:

path_or_file – the path to save the file to, or a file object to which the file is to be written.

The file is read and written in chunks of size FormDataIter.buffer_size.

async copy(max_memory_size=None)

Copy the uploaded file to a temporary file, to allow the parsing of the multipart form to continue.

Parameters:

max_memory_size – the maximum size of the file to keep in memory. If not given, then the class attribute of the same name is used.

async close()

Close an open file.

This method must be called to free memory or temporary files created by the copy() method.

Note that when using the @with_form_data decorator this method is called automatically when the request ends.

microdot.multipart.with_form_data(f)

Decorator that parses a multipart/form-data body and updates the request object with the parsed form fields and files.

Example usage:

from microdot.multipart import with_form_data

@app.post('/upload')
@with_form_data
async def upload(request):
    print('form fields:', request.form)
    print('files:', request.files)

Note: this decorator calls the FileUpload.copy() method on all uploaded files, so that the request can be parsed in its entirety. The files are either copied to memory or a temporary file, depending on their size. The temporary files are automatically deleted when the request ends.