CurlShare Object

class pycurl.CurlShare(detach_on_close=True) → New CurlShare object

Creates a new CurlShare Object which corresponds to a CURLSH handle in libcurl. CurlShare objects is what you pass as an argument to the SHARE option on Curl objects.

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

When a CurlShare is closed, its behavior depends on the value of detach_on_close.

Example:

with pycurl.CurlShare(detach_on_close=True) as s:
    curl.setopt(pycurl.SHARE, s)
    # perform operations
# the CurlShare is closed and the Curl object has been detached
Parameters:

detach_on_close (bool) –

Controls how associated Curl objects are handled when the CurlShare is closed.

If True (default), all live Curl objects associated with the share are automatically detached when close() is called or when exiting the context manager. Detaching clears the SHARE option on each Curl object, but does not close them. The caller remains responsible for managing the lifetime of the Curl objects.

If False, calling close() (or exiting the context manager) while there are still Curl objects associated with the share raises an exception. In this mode, the caller must explicitly remove or close all associated Curl objects before closing the CurlShare.

Warning

Detaching Curl objects from a CurlShare is not thread-safe with respect to those Curl objects.

The caller is responsible for ensuring proper synchronization when using CurlShare and Curl objects across multiple threads.

CurlShare objects have the following methods:

close() → None

Close shared handle.

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

The behavior of close() depends on the detach_on_close setting of the CurlShare:

  • If detach_on_close is True (default), all associated Curl objects are first detached from the share before the share handle is closed. Detaching clears the SHARE option on each Curl object but does not close them.

  • If detach_on_close is False, calling close() while there are still associated Curl objects raises pycurl.error and the share handle is not closed.

Warning

Automatic detachment performed when detach_on_close is True is not thread-safe with respect to the associated Curl objects. The caller must ensure that no other thread is operating on those Curl objects while close() is executing.

setopt(option, value) → None

Set curl share option.

Corresponds to curl_share_setopt in libcurl, where option is specified with the CURLSHOPT_* constants in libcurl, except that the CURLSHOPT_ prefix has been changed to SH_. Currently, value must be one of: LOCK_DATA_COOKIE, LOCK_DATA_DNS, LOCK_DATA_SSL_SESSION or LOCK_DATA_CONNECT.

Example usage:

import pycurl
curl = pycurl.Curl()
s = pycurl.CurlShare()
s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_COOKIE)
s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_DNS)
curl.setopt(pycurl.URL, 'https://curl.haxx.se')
curl.setopt(pycurl.SHARE, s)
curl.perform()
curl.close()

Raises pycurl.error exception upon failure.