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.

See close() for the rules close() enforces when associated Curl handles are still in use.

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 idle 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.

close() refuses to detach a Curl handle that is currently inside perform() and raises pycurl.error in that case, even with detach_on_close=True. Idle attached handles are still detached automatically.

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.

closed

Whether this CurlShare object has been closed.

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. Failures reported by libcurl (CURLSHcode) are surfaced as pycurl.error.

share(*data) → None

Mark one or more data kinds as shared.

Equivalent to calling setopt(SH_SHARE, item) for each item. Each item must be one of: LOCK_DATA_COOKIE, LOCK_DATA_DNS, LOCK_DATA_SSL_SESSION, LOCK_DATA_CONNECT or LOCK_DATA_PSL.

At least one argument is required. Lists and tuples are not expanded — pass each constant individually. Items are applied sequentially under the CurlShare object lock; on failure, items already applied are not rolled back.

Example usage:

import pycurl
s = pycurl.CurlShare()
s.share(pycurl.LOCK_DATA_COOKIE, pycurl.LOCK_DATA_DNS)

Raises pycurl.error exception upon failure.

unshare(*data) → None

Mark one or more data kinds as no longer shared.

Equivalent to calling setopt(SH_UNSHARE, item) for each item. Each item must be one of: LOCK_DATA_COOKIE, LOCK_DATA_DNS, LOCK_DATA_SSL_SESSION, LOCK_DATA_CONNECT or LOCK_DATA_PSL.

At least one argument is required. Lists and tuples are not expanded — pass each constant individually. Items are applied sequentially under the CurlShare object lock; on failure, items already applied are not rolled back.

Example usage:

import pycurl
s = pycurl.CurlShare()
s.share(pycurl.LOCK_DATA_COOKIE, pycurl.LOCK_DATA_DNS)
s.unshare(pycurl.LOCK_DATA_COOKIE)

Raises pycurl.error exception upon failure.