konnect.curl.abc module

Abstract protocols which may be implemented by users

curl provides simple implementations of these protocols which may be used directly or subclassed by users.

class ConfigHandle(*args, **kwargs)

Bases: Protocol

The interface provided by objects passed to RequestProtocol.configure_handle()

setopt(option: int, value: object, /) → None

Set an option on a Curl handle

See https://curl.se/libcurl/c/curl_easy_setopt.html for a list of options and what they do.

unsetopt(option: int, /) → None

Set options that have a default value back to that default

pause(state: int, /) → None

Set the paused state of a Curl handle

This is provided for request implementations that need to await upload data, they may store the handle or method for later use. In a future release it will be deprecated in favour of a method that returns an asynchronously writable object.

class GetInfoHandle(*args, **kwargs)

Bases: Protocol

The interface provided by objects passed to RequestProtocol.completed()

getinfo(option: int, /) → object

Return information about a Curl handle

Note that string values are returned as unicode strings.

See https://curl.se/libcurl/c/curl_easy_getinfo.html for a list of options and what they return.

getinfo_raw(option: int, /) → object

Like GetInfoHandle.getinfo() but string values are returned as byte strings

class RequestProtocol(*args, **kwargs)

Bases: Protocol[konnect.curl.abc.U_co, konnect.curl.abc.R_co]

Request classes that are passed to Multi.process() must implement this protocol

configure_handle(handle: konnect.curl.abc.ConfigHandle, /) → None

Configure a Curl handle for the request by calling ConfigHandle methods

See https://curl.se/libcurl/c/curl_easy_setopt.html for a list of options and what they do.

has_update() → bool

Return whether calling RequestProtocol.get_update() will return a value or raise LookupError

get_update() → konnect.curl.abc.U_co

Return a waiting update or raise LookupError if there is none

Multi.process() will only call this method when RequestProtocol.has_update() indicates an update is available. The returned value will be returned by Multi.process().

Note that values returned by this method are interim updates, and Multi.process() will be called again with the current request. It is up to the implementer how many times updates will be returned and what objects to return as updates: it may be different objects for different stages of a transfer; or there may never be interim updates.

completed(handle: konnect.curl.abc.GetInfoHandle, /) → konnect.curl.abc.R_co

Indicate that Curl has completed processing the handle and return a final response

Like RequestProtocol.get_update this method’s return value will be returned by Multi.process(). Unlike RequestProtocol.get_update this method will be called exactly once for a successful transfer.

The GetInfoHandle passed as a positional argument may be used to get post-completion information about a transfer, see https://curl.se/libcurl/c/curl_easy_getinfo.html for a list of options and what they return.