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