Functions

check_version (major, minor, micro)

cookie_parse (header, origin)

cookies_from_request (msg)

cookies_from_response (msg)

cookies_to_cookie_header (cookies)

cookies_to_request (cookies, msg)

cookies_to_response (cookies, msg)

date_time_new_from_http_string (date_string)

date_time_to_string (date, format)

form_decode (encoded_form)

form_decode_multipart (multipart, file_control_name)

form_encode_datalist (form_data_set)

form_encode_hash (form_data_set)

get_major_version ()

get_micro_version ()

get_minor_version ()

header_contains (header, token)

header_free_param_list (param_list)

header_g_string_append_param (string, name, value)

header_g_string_append_param_quoted (string, name, value)

header_parse_list (header)

header_parse_param_list (header)

header_parse_param_list_strict (header)

header_parse_quality_list (header)

header_parse_semi_param_list (header)

header_parse_semi_param_list_strict (header)

headers_parse (str, len, dest)

headers_parse_request (str, len, req_headers)

headers_parse_response (str, len, headers)

headers_parse_status_line (status_line)

message_headers_iter_init (hdrs)

session_error_quark ()

status_get_phrase (status_code)

tld_domain_is_public_suffix (domain)

tld_error_quark ()

tld_get_base_domain (hostname)

uri_decode_data_uri (uri)

uri_equal (uri1, uri2)

websocket_client_prepare_handshake (msg, origin, protocols, supported_extensions)

websocket_client_verify_handshake (msg, supported_extensions)

websocket_error_quark ()

websocket_server_check_handshake (msg, origin, protocols, supported_extensions)

websocket_server_process_handshake (msg, expected_origin, protocols, supported_extensions)

Details

Soup.check_version(major, minor, micro)
Parameters:

  • major (int) – the major version to check

  • minor (int) – the minor version to check

  • micro (int) – the micro version to check

Returns:

True if the version of the libsoup currently loaded is the same as or newer than the passed-in version.

Return type:

bool

Like [funcCHECK_VERSION], but the check for Soup.check_version is at runtime instead of compile time.

This is useful for compiling against older versions of libsoup, but using features from newer versions.

Soup.cookie_parse(header, origin)
Parameters:

  • header (str) – a cookie string (eg, the value of a Set-Cookie header)

  • origin (GLib.Uri or None) – origin of the cookie

Returns:

a new Soup.Cookie, or None if it could not be parsed, or contained an illegal “domain” attribute for a cookie originating from origin.

Return type:

Soup.Cookie or None

Parses header and returns a Soup.Cookie.

If header contains multiple cookies, only the first one will be parsed.

If header does not have “path” or “domain” attributes, they will be defaulted from origin. If origin is None, path will default to “/”, but domain will be left as None. Note that this is not a valid state for a Soup.Cookie, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie.

As of version 3.4.0 the default value of a cookie’s same-site-policy is Soup.SameSitePolicy.LAX.

Soup.cookies_from_request(msg)
Parameters:

msg (Soup.Message) – a Soup.Message containing a “Cookie” request header

Returns:

a GLib.SList of ``SoupCookie``s, which can be freed with [method`Cookie`.free].

Return type:

[Soup.Cookie]

Parses msg's Cookie request header and returns a [struct`GLib`.SList] of ``SoupCookie``s.

As the “Cookie” header, unlike “Set-Cookie”, only contains cookie names and values, none of the other Soup.Cookie fields will be filled in. (Thus, you can’t generally pass a cookie returned from this method directly to [func`cookies_to_response`].)

Soup.cookies_from_response(msg)
Parameters:

msg (Soup.Message) – a Soup.Message containing a “Set-Cookie” response header

Returns:

a GLib.SList of ``SoupCookie``s, which can be freed with [method`Cookie`.free].

Return type:

[Soup.Cookie]

Parses msg's Set-Cookie response headers and returns a [struct`GLib`.SList] of ``SoupCookie``s.

Cookies that do not specify “path” or “domain” attributes will have their values defaulted from msg.

Parameters:

cookies ([Soup.Cookie]) – a GLib.SList of Soup.Cookie

Returns:

the serialization of cookies

Return type:

str

Serializes a [struct`GLib`.SList] of Soup.Cookie into a string suitable for setting as the value of the “Cookie” header.

Soup.cookies_to_request(cookies, msg)
Parameters:

Adds the name and value of each cookie in cookies to msg's “Cookie” request.

If msg already has a “Cookie” request header, these cookies will be appended to the cookies already present. Be careful that you do not append the same cookies twice, eg, when requeuing a message.

Soup.cookies_to_response(cookies, msg)
Parameters:

Appends a “Set-Cookie” response header to msg for each cookie in cookies.

This is in addition to any other “Set-Cookie” headers msg may already have.

Soup.date_time_new_from_http_string(date_string)
Parameters:

date_string (str) – The date as a string

Returns:

a new GLib.DateTime, or None if date_string could not be parsed.

Return type:

GLib.DateTime or None

Parses date_string and tries to extract a date from it.

This recognizes all of the “HTTP-date” formats from RFC 2616, RFC 2822 dates, and reasonable approximations thereof. (Eg, it is lenient about whitespace, leading “0”s, etc.)

Soup.date_time_to_string(date, format)
Parameters:
Returns:

date as a string or None

Return type:

str

Converts date to a string in the format described by format.

Soup.form_decode(encoded_form)
Parameters:

encoded_form (str) – data of type “application/x-www-form-urlencoded”

Returns:

a hash table containing the name/value pairs from encoded_form, which you can free with [func`GLib`.HashTable.destroy].

Return type:

{str: str}

Decodes form.

which is an urlencoded dataset as defined in the HTML 4.01 spec.

Soup.form_decode_multipart(multipart, file_control_name)
Parameters:
Returns:

a hash table containing the name/value pairs (other than file_control_name) from msg, which you can free with [func`GLib`.HashTable.destroy]. On error, it will return None.

filename:

return location for the name of the uploaded file

content_type:

return location for the MIME type of the uploaded file

file:

return location for the uploaded file data

Return type:

({str: str} or None, filename: str, content_type: str, file: GLib.Bytes)

Decodes the “multipart/form-data” request in multipart.

this is a convenience method for the case when you have a single file upload control in a form. (Or when you don’t have any file upload controls, but are still using “multipart/form-data” anyway.) Pass the name of the file upload control in file_control_name, and [func`form_decode_multipart`] will extract the uploaded file data into filename, content_type, and file. All of the other form control data will be returned (as strings, as with [func`form_decode`] in the returned [struct`GLib`.HashTable].

You may pass None for filename, content_type and/or file if you do not care about those fields. [func`form_decode_multipart`] may also return None in those fields if the client did not provide that information. You must free the returned filename and content-type with [func`GLib`.free], and the returned file data with [method`Glib`.Bytes.unref].

If you have a form with more than one file upload control, you will need to decode it manually, using [ctor`Multipart`.new_from_message] and [method`Multipart`.get_part].

Soup.form_encode_datalist(form_data_set)
Parameters:

form_data_set (GLib.Data) – a datalist containing name/value pairs

Returns:

the encoded form

Return type:

str

Encodes form_data_set into a value of type “application/x-www-form-urlencoded”.

Encodes as defined in the HTML 4.01 spec. Unlike [func`form_encode_hash`], this preserves the ordering of the form elements, which may be required in some situations.

See also: [ctor`Message`.new_from_encoded_form].

Soup.form_encode_hash(form_data_set)
Parameters:

form_data_set ({str: str}) – a hash table containing name/value pairs (as strings)

Returns:

the encoded form

Return type:

str

Encodes form_data_set into a value of type “application/x-www-form-urlencoded”.

Encodes as defined in the HTML 4.01 spec.

Note that the HTML spec states that “The control names/values are listed in the order they appear in the document.” Since this method takes a hash table, it cannot enforce that; if you care about the ordering of the form fields, use [func`form_encode_datalist`].

See also: [ctor`Message`.new_from_encoded_form].

Soup.get_major_version()
Returns:

the major version number of the libsoup library

Return type:

int

Returns the major version number of the libsoup library.

e.g. in libsoup version 2.42.0 this is 2.

This function is in the library, so it represents the libsoup library your code is running against. Contrast with the Soup.MAJOR_VERSION macro, which represents the major version of the libsoup headers you have included when compiling your code.

Soup.get_micro_version()
Returns:

the micro version number of the libsoup library

Return type:

int

Returns the micro version number of the libsoup library.

e.g. in libsoup version 2.42.0 this is 0.

This function is in the library, so it represents the libsoup library your code is running against. Contrast with the Soup.MICRO_VERSION macro, which represents the micro version of the libsoup headers you have included when compiling your code.

Soup.get_minor_version()
Returns:

the minor version number of the libsoup library

Return type:

int

Returns the minor version number of the libsoup library.

e.g. in libsoup version 2.42.0 this is 42.

This function is in the library, so it represents the libsoup library your code is running against. Contrast with the Soup.MINOR_VERSION macro, which represents the minor version of the libsoup headers you have included when compiling your code.

Soup.header_contains(header, token)
Parameters:

  • header (str) – An HTTP header suitable for parsing with [func`header_parse_list`]

  • token (str) – a token

Returns:

whether or not header contains token

Return type:

bool

Parses header to see if it contains the token token (matched case-insensitively).

Note that this can’t be used with lists that have qvalues.

Soup.header_free_param_list(param_list)
Parameters:

param_list ({str: str}) – a GLib.HashTable returned from [func`header_parse_param_list`] or [func`header_parse_semi_param_list`]

Frees param_list.

Soup.header_g_string_append_param(string, name, value)
Parameters:

Appends something like name=value to string, taking care to quote value if needed, and if so, to escape any quotes or backslashes in value.

Alternatively, if value is a non-ASCII UTF-8 string, it will be appended using RFC5987 syntax. Although in theory this is supposed to work anywhere in HTTP that uses this style of parameter, in reality, it can only be used portably with the Content-Disposition “filename” parameter.

If value is None, this will just append name to string.

Soup.header_g_string_append_param_quoted(string, name, value)
Parameters:

  • string (GLib.String) – a GLib.String being used to construct an HTTP header value

  • name (str) – a parameter name

  • value (str) – a parameter value

Appends something like name="value" to string, taking care to escape any quotes or backslashes in value.

If value is (non-ASCII) UTF-8, this will instead use RFC 5987 encoding, just like [func`header_g_string_append_param`].

Soup.header_parse_list(header)
Parameters:

header (str) – a header value

Returns:

a GLib.SList of list elements, as allocated strings

Return type:

[str]

Parses a header whose content is described by RFC2616 as #something.

“something” does not itself contain commas, except as part of quoted-strings.

Soup.header_parse_param_list(header)
Parameters:

header (str) – a header value

Returns:

a GLib.HashTable of list elements, which can be freed with [func`header_free_param_list`].

Return type:

{str: str}

Parses a header which is a comma-delimited list of something like: token [ "=" ( token | quoted-string ) ].

Tokens that don’t have an associated value will still be added to the resulting hash table, but with a None value.

This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

Soup.header_parse_param_list_strict(header)
Parameters:

header (str) – a header value

Returns:

a GLib.HashTable of list elements, which can be freed with [func`header_free_param_list`] or None if there are duplicate elements.

Return type:

{str: str} or None

A strict version of [func`header_parse_param_list`] that bails out if there are duplicate parameters.

Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use [func`header_parse_param_list`] instead.

Soup.header_parse_quality_list(header)
Parameters:

header (str) – a header value

Returns:

a GLib.SList of acceptable values (as allocated strings), highest-qvalue first.

unacceptable:

on return, will contain a list of unacceptable values

Return type:

([str], unacceptable: [str])

Parses a header whose content is a list of items with optional “qvalue”s (eg, Accept, Accept-Charset, Accept-Encoding, Accept-Language, TE).

If unacceptable is not None, then on return, it will contain the items with qvalue 0. Either way, those items will be removed from the main list.

Soup.header_parse_semi_param_list(header)
Parameters:

header (str) – a header value

Returns:

a GLib.HashTable of list elements, which can be freed with [func`header_free_param_list`].

Return type:

{str: str}

Parses a header which is a semicolon-delimited list of something like: token [ "=" ( token | quoted-string ) ].

Tokens that don’t have an associated value will still be added to the resulting hash table, but with a None value.

This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

Soup.header_parse_semi_param_list_strict(header)
Parameters:

header (str) – a header value

Returns:

a GLib.HashTable of list elements, which can be freed with [func`header_free_param_list`] or None if there are duplicate elements.

Return type:

{str: str} or None

A strict version of [func`header_parse_semi_param_list`] that bails out if there are duplicate parameters.

Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use [func`header_parse_semi_param_list`] instead.

Soup.headers_parse(str, len, dest)
Parameters:
Returns:

success or failure

Return type:

bool

Parses the headers of an HTTP request or response in str and stores the results in dest.

Beware that dest may be modified even on failure.

This is a low-level method; normally you would use [func`headers_parse_request`] or [func`headers_parse_response`].

Soup.headers_parse_request(str, len, req_headers)
Parameters:
Returns:

Soup.Status.OK if the headers could be parsed, or an HTTP error to be returned to the client if they could not be.

req_method:

if non-None, will be filled in with the request method

req_path:

if non-None, will be filled in with the request path

ver:

if non-None, will be filled in with the HTTP version

Return type:

(int, req_method: str, req_path: str, ver: Soup.HTTPVersion)

Parses the headers of an HTTP request in str and stores the results in req_method, req_path, ver, and req_headers.

Beware that req_headers may be modified even on failure.

Soup.headers_parse_response(str, len, headers)
Parameters:
Returns:

success or failure.

ver:

if non-None, will be filled in with the HTTP version

status_code:

if non-None, will be filled in with the status code

reason_phrase:

if non-None, will be filled in with the reason phrase

Return type:

(bool, ver: Soup.HTTPVersion, status_code: int, reason_phrase: str)

Parses the headers of an HTTP response in str and stores the results in ver, status_code, reason_phrase, and headers.

Beware that headers may be modified even on failure.

Soup.headers_parse_status_line(status_line)
Parameters:

status_line (str) – an HTTP Status-Line

Returns:

True if status_line was parsed successfully.

ver:

if non-None, will be filled in with the HTTP version

status_code:

if non-None, will be filled in with the status code

reason_phrase:

if non-None, will be filled in with the reason phrase

Return type:

(bool, ver: Soup.HTTPVersion, status_code: int, reason_phrase: str)

Parses the HTTP Status-Line string in status_line into ver, status_code, and reason_phrase.

status_line must be terminated by either “\0” or “\r\n”.

Soup.message_headers_iter_init(hdrs)
Parameters:

hdrs (Soup.MessageHeaders) – a Soup.MessageHeaders

Returns:

a pointer to a Soup.MessageHeadersIter structure

Return type:

iter: Soup.MessageHeadersIter

Initializes iter for iterating hdrs.

Soup.session_error_quark()
Returns:

Error quark for Soup.Session.

Return type:

int

Registers error quark for Soup.Session if needed.

Soup.status_get_phrase(status_code)
Parameters:

status_code (int) – an HTTP status code

Returns:

the (terse, English) description of status_code

Return type:

str

Looks up the stock HTTP description of status_code.

*There is no reason for you to ever use this function.* If you wanted the textual description for the [property`Message`:status-code] of a given [class`Message`], you should just look at the message’s [property`Message`:reason-phrase]. However, you should only do that for use in debugging messages; HTTP reason phrases are not localized, and are not generally very descriptive anyway, and so they should never be presented to the user directly. Instead, you should create you own error messages based on the status code, and on what you were trying to do.

Soup.tld_domain_is_public_suffix(domain)
Parameters:

domain (str) – a domain name

Returns:

True if it is a public domain, False otherwise.

Return type:

bool

Looks whether the domain passed as argument is a public domain suffix (.org, .com, .co.uk, etc) or not.

Prior to libsoup 2.46, this function required that domain be in UTF-8 if it was an IDN. From 2.46 on, the name can be in either UTF-8 or ASCII format.

Soup.tld_error_quark()
Returns:

Error quark for Soup TLD functions.

Return type:

int

Registers error quark for Soup.tld_get_base_domain() if needed.

Soup.tld_get_base_domain(hostname)
Parameters:

hostname (str) – a hostname

Raises:

GLib.Error

Returns:

a pointer to the start of the base domain in hostname. If an error occurs, None will be returned and error set.

Return type:

str

Finds the base domain for a given hostname

The base domain is composed by the top level domain (such as .org, .com, .co.uk, etc) plus the second level domain, for example for myhost.mydomain.com it will return mydomain.com.

Note that None will be returned for private URLs (those not ending with any well known TLD) because choosing a base domain for them would be totally arbitrary.

Prior to libsoup 2.46, this function required that hostname be in UTF-8 if it was an IDN. From 2.46 on, the name can be in either UTF-8 or ASCII format (and the return value will be in the same format).

Soup.uri_decode_data_uri(uri)
Parameters:

uri (str) – a data URI, in string form

Returns:

a GLib.Bytes with the contents of uri, or None if uri is not a valid data URI

content_type:

location to store content type

Return type:

(GLib.Bytes, content_type: str or None)

Decodes the given data URI and returns its contents and content_type.

Soup.uri_equal(uri1, uri2)
Parameters:
Returns:

True if equal otherwise False

Return type:

bool

Tests whether or not uri1 and uri2 are equal in all parts.

Soup.websocket_client_prepare_handshake(msg, origin, protocols, supported_extensions)
Parameters:

Adds the necessary headers to msg to request a WebSocket handshake including supported WebSocket extensions.

The message body and non-WebSocket-related headers are not modified.

This is a low-level function; if you use [method`Session`.websocket_connect_async] to create a WebSocket connection, it will call this for you.

Soup.websocket_client_verify_handshake(msg, supported_extensions)
Parameters:
Raises:

GLib.Error

Returns:

True if msg contains a completed valid WebSocket handshake, False and an error if not.

accepted_extensions:

a GLib.List of Soup.WebsocketExtension objects

Return type:

(bool, accepted_extensions: [Soup.WebsocketExtension])

Looks at the response status code and headers in msg and determines if they contain a valid WebSocket handshake response (given the handshake request in msg's request headers).

If supported_extensions is non-None, extensions included in the response “Sec-WebSocket-Extensions” are verified too. Accepted extensions are returned in accepted_extensions parameter if non-None.

This is a low-level function; if you use [method`Session`.websocket_connect_async] to create a WebSocket connection, it will call this for you.

Soup.websocket_error_quark()
Returns:

Error quark for SoupWebsocket.

Return type:

int

Registers error quark for SoupWebsocket if needed.

Soup.websocket_server_check_handshake(msg, origin, protocols, supported_extensions)
Parameters:
Raises:

GLib.Error

Returns:

True if msg contained a valid WebSocket handshake, False and an error if not.

Return type:

bool

Examines the method and request headers in msg and determines whether msg contains a valid handshake request.

If origin is non-None, then only requests containing a matching “Origin” header will be accepted. If protocols is non-None, then only requests containing a compatible “Sec-WebSocket-Protocols” header will be accepted. If supported_extensions is non-None, then only requests containing valid supported extensions in “Sec-WebSocket-Extensions” header will be accepted.

Normally [func`websocket_server_process_handshake`] will take care of this for you, and if you use [method`Server`.add_websocket_handler] to handle accepting WebSocket connections, it will call that for you. However, this function may be useful if you need to perform more complicated validation; eg, accepting multiple different Origins, or handling different protocols depending on the path.

Soup.websocket_server_process_handshake(msg, expected_origin, protocols, supported_extensions)
Parameters:
Returns:

True if msg contained a valid WebSocket handshake request and was updated to contain a handshake response. False if not.

accepted_extensions:

a GLib.List of Soup.WebsocketExtension objects

Return type:

(bool, accepted_extensions: [Soup.WebsocketExtension])

Examines the method and request headers in msg and (assuming msg contains a valid handshake request), fills in the handshake response.

If expected_origin is non-None, then only requests containing a matching “Origin” header will be accepted. If protocols is non-None, then only requests containing a compatible “Sec-WebSocket-Protocols” header will be accepted. If supported_extensions is non-None, then only requests containing valid supported extensions in “Sec-WebSocket-Extensions” header will be accepted. The accepted extensions will be returned in accepted_extensions parameter if non-None.

This is a low-level function; if you use [method`Server`.add_websocket_handler] to handle accepting WebSocket connections, it will call this for you.