CurlUrl Object

class pycurl.CurlUrl(url=None, flags=0) → New CurlUrl object

Create a CurlUrl Object wrapping a libcurl CURLU URL handle.

Without arguments the handle is empty. If url is given it is parsed with setpart(UPART_URL, url, flags), so flags may be any combination of the U_* constants.

The component properties (scheme, host, port, path, query, fragment, user, password, options and, on libcurl 7.65.0 or later, zoneid) read and write the URL parts. A getter returns None when the part is absent. Assigning None or using del removes it. For control over encoding and other flags use getpart() and setpart().

A CurlUrl can be passed to a Curl object through the CURLU option.

Corresponds to curl_url in libcurl. Requires libcurl 7.62.0 or later.

Example:

u = pycurl.CurlUrl("https://example.com/path?a=1")
u.host = "example.org"
curl.setopt(pycurl.CURLU, u)
Parameters:

  • url – an optional URL string to parse into the new handle.

  • flags (int) – U_* flags controlling how url is parsed.

A CurlUrl wraps a libcurl CURLU handle and exposes libcurl’s URL API. It requires libcurl 7.62.0 or later.

Component getters return None when the part is absent, which is how an absent part differs from an empty one. By default the properties read and write the raw value with no percent-encoding or decoding. Use getpart() and setpart() with the U_* flags for encoding control.

CurlUrl objects have the following methods:

getpart(part, flags=0) → str or None

Return one URL component, or None when it is absent.

part is one of the UPART_* constants. flags is a combination of the U_* constants, for example U_URLDECODE. Errors other than an absent part raise pycurl.error.

Corresponds to curl_url_get in libcurl.

setpart(part, value, flags=0) → None

Set one URL component.

part is one of the UPART_* constants. value is a string or bytes, or None to remove the part. flags is a combination of the U_* constants, for example U_URLENCODE or U_APPENDQUERY. On failure pycurl.error is raised.

Corresponds to curl_url_set in libcurl.

CurlUrl objects have the following attributes:

url

The full URL as a string, or None if it is incomplete. Corresponds to CURLUPART_URL.

scheme

The URL scheme, or None if the URL has no scheme. Corresponds to CURLUPART_SCHEME.

user

The user name from the URL userinfo, or None if not set. Corresponds to CURLUPART_USER.

password

The password from the URL userinfo, or None if not set. Corresponds to CURLUPART_PASSWORD.

options

The options from the URL userinfo, or None if not set. Corresponds to CURLUPART_OPTIONS.

host

The host name, or None if the URL has no host. An IPv6 address is returned in brackets, as it appears in the URL. Corresponds to CURLUPART_HOST.

port

The port as a string, or None if the URL has no port. Assigning an int is also accepted. Corresponds to CURLUPART_PORT.

path

The URL path, or None if not set. Corresponds to CURLUPART_PATH.

query

The query string, or None if the URL has no query. Corresponds to CURLUPART_QUERY.

fragment

The fragment, or None if the URL has no fragment. Corresponds to CURLUPART_FRAGMENT.

zoneid

The IPv6 zone id, or None if not set. Corresponds to CURLUPART_ZONEID. Requires libcurl 7.65.0 or later.

A CurlUrl can drive a transfer when passed to a Curl object through the CURLU option, which requires libcurl 7.63.0 or later:

u = pycurl.CurlUrl("https://example.com/")
curl.setopt(pycurl.CURLU, u)

libcurl reads the handle for each transfer, so a CurlUrl updated between transfers takes effect on the next one. The Curl object keeps the CurlUrl alive while the option is set. Corresponds to CURLOPT_CURLU in libcurl.

See libcurl-url for an overview of the libcurl URL API.