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().

  • CurlMimePart.data() also accepts objects exposing Python’s buffer protocol (for example bytearray and memoryview), not only bytes/ASCII str.

  • CurlMimePart.data_cb(datasize, read, seek=None, free=None, userdata=None) maps to libcurl curl_mime_data_cb() for streaming content from callbacks. read(userdata, max_bytes) uses the same return conventions as READFUNCTION. Optional seek(userdata, offset, origin) follows SEEKFUNCTION semantics and should return SEEKFUNC_OK, SEEKFUNC_FAIL or SEEKFUNC_CANTSEEK. Optional free(userdata) is called when libcurl releases the callback-backed part.

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 is a first-draft API. It currently documents MIME object construction and nesting. End-to-end request attachment via Curl options is documented separately as that integration is finalized.

Note

Ownership and handle constraints:

  • CurlMime objects passed to Curl.setopt(pycurl.MIMEPOST, mime) must be top-level/owning MIME trees (not already attached via subparts()).

  • CurlMimePart.subparts(child) requires both CurlMime objects to use the same Curl handle.

  • A CurlMime currently set as MIMEPOST cannot be attached as subparts().

  • Curl.duphandle() duplicates callback-backed MIME parts and shares the callback userdata pointer between handles, matching libcurl behavior.

CurlMime

class pycurl.CurlMime

Python wrapper for libcurl MIME API.

CurlMime objects have the following methods:

close()

Release the underlying curl_mime handle.

closed()

Return whether this CurlMime object is closed.

addpart()

Create and return a new MIME part.

add()

Add a part using a keyword-oriented builder API.

add_field()

Add a simple form field part.

add_file()

Add a file upload part.

add_multipart()

Add and attach a nested multipart CurlMime.

CurlMimePart

class pycurl.CurlMimePart

A MIME part belonging to a CurlMime object.

CurlMimePart objects have the following methods:

name(object, /)

Set the name of this MIME part.

data(object, /)

Set in-memory data for this MIME part.

data_cb()

Set callback-based data for this MIME part.

filedata(object, /)

Set on-disk file data for this MIME part.

filename(object, /)

Set the remote filename for this MIME part.

type(object, /)

Set content type for this MIME part.

encoder(object, /)

Set content transfer encoding for this MIME part.

headers(object, /)

Set custom headers for this MIME part.

subparts(object, /)

Attach a child CurlMime object as multipart data.