CurlMime Objects

PycURL exposes libcurl’s MIME tree API via CurlMime and CurlMimePart classes.

CurlMime offers both low-level wrappers and higher-level builder helpers:

  • Low-level: addpart() and CurlMimePart methods such as name(), data(), data_cb(), filedata() and subparts().

  • Builder helpers: add(), add_field(), add_file() and add_multipart().

Example:

import pycurl

curl = pycurl.Curl()
mime = pycurl.CurlMime(curl)

mime.add_field("field1", "value1")
mime.add_file("upload", "/tmp/example.txt", content_type="text/plain")

nested = mime.add_multipart(name="attachments", subtype="mixed")
nested.add_field("meta", "nested-value")

Note

This API is a first draft and may change.

Note

A CurlMime passed to Curl.setopt(pycurl.MIMEPOST, mime) must be a top-level owning tree, not one already attached with subparts().

CurlMime

class pycurl.CurlMime(curl) → New CurlMime object

Creates a new CurlMime tree bound to curl, corresponding to a curl_mime handle in libcurl. Pass it to Curl.setopt(pycurl.MIMEPOST, mime) to send it as the request body.

The CurlMime object can be used as a context manager. Exiting the context calls close().

Corresponds to curl_mime_init in libcurl.

Parameters:

curl (Curl) – the Curl object this tree belongs to. The handle must be open and not performing.

CurlMime objects have the following methods:

close() → None

Corresponds to curl_mime_free in libcurl. This method is automatically called by pycurl when a CurlMime object no longer has any references to it, but can also be called explicitly.

A CurlMime attached to another one with subparts() is released by its parent instead.

A subclass overriding __del__ must call super().__del__(), otherwise the free callbacks of its parts may not run.

close() may not be called while perform() is running on the Curl handle the mime belongs to. Doing so raises pycurl.error.

closed

Whether this CurlMime object has been closed.

addpart() → CurlMimePart

Create and return a new part at the end of this tree.

Corresponds to curl_mime_addpart in libcurl.

add(name=None, data=None, file=None, filename=None, content_type=None, headers=None, encoder=None) → CurlMimePart

Add a part and set the given fields on it, then return it.

At most one of data and file may be given. Each argument that is not None is applied with the CurlMimePart method of the same name, except file and content_type, which use filedata() and type().

Parameters:

  • name (str) – part name. A byte string is also accepted.

  • data – in-memory content, as bytes, an ASCII str, or any object supporting the buffer protocol.

  • file (str) – path to read the content from, instead of data.

  • filename (str) – remote filename to report for the part.

  • content_type (str) – value for the part’s Content-Type header.

  • headers – extra headers, as a list or tuple of strings.

  • encoder (str) – content transfer encoding, for example "base64".

add_field(name, value, content_type=None, encoder=None, headers=None) → CurlMimePart

Add a simple form field part and return it.

Equivalent to add(name=name, data=value, ...).

Parameters:

  • name (str) – field name.

  • value – field content, as bytes, an ASCII str, or any object supporting the buffer protocol.

  • content_type (str) – value for the part’s Content-Type header.

  • encoder (str) – content transfer encoding, for example "base64".

  • headers – extra headers, as a list or tuple of strings.

add_file(name, path, filename=None, content_type=None, headers=None, encoder=None) → CurlMimePart

Add a file upload part reading from path and return it.

Equivalent to add(name=name, file=path, ...).

Parameters:

  • name (str) – field name.

  • path (str) – path to the file to upload. It is opened to check that it is readable, and read again by libcurl during the transfer.

  • filename (str) – remote filename to report. When omitted libcurl derives it from path.

  • content_type (str) – value for the part’s Content-Type header.

  • headers – extra headers, as a list or tuple of strings.

  • encoder (str) – content transfer encoding, for example "base64".

add_multipart(name=None, subtype='mixed') → CurlMime

Add a nested multipart part and return the child CurlMime attached to it.

The child is owned by this tree, so it is released with the parent and cannot be attached anywhere else or set as MIMEPOST.

Parameters:

  • name (str) – part name.

  • subtype (str) – multipart subtype, giving a Content-Type of multipart/<subtype>. Pass None to leave the type unset.

CurlMimePart

class pycurl.CurlMimePart

A part belonging to a CurlMime tree.

Parts are created by CurlMime.addpart() and by the add*() builder methods. They are only usable while the tree that owns them is open.

CurlMimePart objects have the following methods:

name(name) → None

Set the name of this part.

Corresponds to curl_mime_name in libcurl.

Parameters:

name (str) – part name. A byte string is also accepted.

data(data) → None

Set in-memory data for this part.

The data is copied, so the object does not need to outlive the call.

Corresponds to curl_mime_data in libcurl.

Parameters:

data – the content, as bytes, an ASCII str, or any object supporting the buffer protocol.

data_cb(datasize, read, seek=None, free=None, userdata=None) → None

Set callback-based data for this part.

read uses the same return conventions as READFUNCTION. seek follows SEEKFUNCTION semantics and should return SEEKFUNC_OK, SEEKFUNC_FAIL or SEEKFUNC_CANTSEEK. free runs when libcurl releases the part’s content, which includes replacing it.

Curl.duphandle() shares userdata between the handles, so free runs once the last of them has been closed.

Corresponds to curl_mime_data_cb in libcurl.

Parameters:

  • datasize (int) – total size of the content, or -1 or None when it is not known in advance.

  • read (callable) – called as read(userdata, max_bytes).

  • seek (callable) – called as seek(userdata, offset, origin), or None.

  • free (callable) – called as free(userdata), or None.

  • userdata – any object, passed back to each of the three callbacks.

filedata(path) → None

Set on-disk file data for this part.

Corresponds to curl_mime_filedata in libcurl.

Parameters:

path (str) – path to the file to read the content from. A byte string is also accepted.

filename(name) → None

Set the remote filename for this part.

Corresponds to curl_mime_filename in libcurl.

Parameters:

name (str) – the filename. A byte string is also accepted.

type(content_type) → None

Set the content type for this part.

Corresponds to curl_mime_type in libcurl.

Parameters:

content_type (str) – the content type. A byte string is also accepted.

encoder(encoding) → None

Set the content transfer encoding for this part.

Corresponds to curl_mime_encoder in libcurl.

Parameters:

encoding (str) – the encoding, for example "base64". A byte string is also accepted.

headers(headers) → None

Set custom headers for this part.

Corresponds to curl_mime_headers in libcurl.

Parameters:

headers – the headers, as a list or tuple of strings, or None to clear them.

subparts(child) → None

Attach another CurlMime as the multipart content of this part.

Ownership of child transfers to this tree, so it is released with the parent. Setting this part’s content again, with data(), filedata(), data_cb() or another subparts(), releases the previously attached child and closes it.

Corresponds to curl_mime_subparts in libcurl.

Parameters:

child (CurlMime) – the tree to attach. It must be open, must use the same Curl handle, must not already be attached, and must not be set as MIMEPOST.