Soup.URI¶

Fields¶

Name	Type	Access	Description
fragment	`str`	r/w	a fragment identifier within path, or `None`
host	`str`	r/w	the hostname or IP address, or `None`
password	`str`	r/w	a password, or `None`
path	`str`	r/w	the path on host
port	`int`	r/w	the port number on host
query	`str`	r/w	a query for path, or `None`
scheme	`str`	r/w	the URI scheme (eg, “http”)
user	`str`	r/w	a username, or `None`

Methods¶

class	`decode` (part)
class	`encode` (part, escape_extra)
class	`new` (uri_string)
class	`new_with_base` (base, uri_string)
class	`normalize` (part, unescape_extra)
	`copy` ()
	`copy_host` ()
	`equal` (uri2)
	`free` ()
	`get_fragment` ()
	`get_host` ()
	`get_password` ()
	`get_path` ()
	`get_port` ()
	`get_query` ()
	`get_scheme` ()
	`get_user` ()
	`host_equal` (v2)
	`host_hash` ()
	`set_fragment` (fragment)
	`set_host` (host)
	`set_password` (password)
	`set_path` (path)
	`set_port` (port)
	`set_query` (query)
	`set_query_from_form` (form)
	`set_scheme` (scheme)
	`set_user` (user)
	`to_string` (just_path_and_query)
	`uses_default_port` ()

Details¶

class Soup.URI¶

A Soup.URI represents a (parsed) URI. Soup.URI supports RFC 3986 (URI Generic Syntax), and can parse any valid URI. However, libsoup only uses “http” and “https” URIs internally; You can use SOUP_URI_VALID_FOR_HTTP() to test if a Soup.URI is a valid HTTP URI.

scheme will always be set in any URI. It is an interned string and is always all lowercase. (If you parse a URI with a non-lowercase scheme, it will be converted to lowercase.) The macros %SOUP_URI_SCHEME_HTTP and %SOUP_URI_SCHEME_HTTPS provide the interned values for “http” and “https” and can be compared against URI scheme values.

user and password are parsed as defined in the older URI specs (ie, separated by a colon; RFC 3986 only talks about a single “userinfo” field). Note that password is not included in the output of Soup.URI.to_string(). libsoup does not normally use these fields; authentication is handled via Soup.Session signals.

host contains the hostname, and port the port specified in the URI. If the URI doesn’t contain a hostname, host will be None, and if it doesn’t specify a port, port may be 0. However, for “http” and “https” URIs, host is guaranteed to be non-None (trying to parse an http URI with no host will return None), and port will always be non-0 (because libsoup knows the default value to use when it is not specified in the URI).

path is always non-None. For http/https URIs, path will never be an empty string either; if the input URI has no path, the parsed Soup.URI will have a path of “/”.

query and fragment are optional for all URI types. Soup.form_decode() may be useful for parsing query.

Note that path, query, and fragment may contain % -encoded characters. Soup.URI.new() calls Soup.URI.normalize() on them, but not Soup.URI.decode(). This is necessary to ensure that Soup.URI.to_string() will generate a URI that has exactly the same meaning as the original. (In theory, Soup.URI should leave user, password, and host partially-encoded as well, but this would be more annoying than useful.)

classmethod decode(part)¶

Parameters:	part (`str`) – a URI part
Returns:	the decoded URI part.
Return type:	`str`

Fully % -decodes part.

In the past, this would return None if part contained invalid percent-encoding, but now it just ignores the problem (as Soup.URI.new() already did).

classmethod encode(part, escape_extra)¶

Parameters:	part (`str`) – a URI part escape_extra (`str` or `None`) – additional reserved characters to escape (or `None`)
Returns:	the encoded URI part
Return type:	`str`

This % -encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.

classmethod new(uri_string)¶

Parameters:	uri_string (`str` or `None`) – a URI
Returns:	a `Soup.URI`, or `None` if the given string was found to be invalid.
Return type:	`Soup.URI` or `None`

Parses an absolute URI.

You can also pass None for uri_string if you want to get back an “empty” Soup.URI that you can fill in by hand. (You will need to call at least Soup.URI.set_scheme() and Soup.URI.set_path(), since those fields are required.)

classmethod new_with_base(base, uri_string)¶

Parameters:	base (`Soup.URI`) – a base URI uri_string (`str`) – the URI
Returns:	a parsed `Soup.URI`.
Return type:	`Soup.URI`

Parses uri_string relative to base.

classmethod normalize(part, unescape_extra)¶

Parameters:	part (`str`) – a URI part unescape_extra (`str` or `None`) – reserved characters to unescape (or `None`)
Returns:	the normalized URI part
Return type:	`str`

% -decodes any “unreserved” characters (or characters in unescape_extra) in part, and % -encodes any non-ASCII characters, spaces, and non-printing characters in part.

“Unreserved” characters are those that are not allowed to be used for punctuation according to the URI spec. For example, letters are unreserved, so Soup.URI.normalize() will turn http://example.com/foo/b%61r into http://example.com/foo/bar, which is guaranteed to mean the same thing. However, “/” is “reserved”, so http://example.com/foo%2Fbar would not be changed, because it might mean something different to the server.

In the past, this would return None if part contained invalid percent-encoding, but now it just ignores the problem (as Soup.URI.new() already did).

copy()¶

Returns:	a copy of self, which must be freed with `Soup.URI.free`()
Return type:	`Soup.URI`

Copies self

copy_host()¶

Returns:	the new `Soup.URI`
Return type:	`Soup.URI`

Makes a copy of self, considering only the protocol, host, and port

New in version 2.28.

equal(uri2)¶

Parameters:	uri2 (`Soup.URI`) – another `Soup.URI`
Returns:	`True` or `False`
Return type:	`bool`

Tests whether or not self and uri2 are equal in all parts

free()¶: Frees self.

get_fragment()¶

Returns:	self’s fragment.
Return type:	`str`

Gets self’s fragment.

New in version 2.32.

get_host()¶

Returns:	self’s host.
Return type:	`str`

Gets self’s host.

New in version 2.32.

get_password()¶

Returns:	self’s password.
Return type:	`str`

Gets self’s password.

New in version 2.32.

get_path()¶

Returns:	self’s path.
Return type:	`str`

Gets self’s path.

New in version 2.32.

get_port()¶

Returns:	self’s port.
Return type:	`int`

Gets self’s port.

New in version 2.32.

get_query()¶

Returns:	self’s query.
Return type:	`str`

Gets self’s query.

New in version 2.32.

get_scheme()¶

Returns:	self’s scheme.
Return type:	`str`

Gets self’s scheme.

New in version 2.32.

get_user()¶

Returns:	self’s user.
Return type:	`str`

Gets self’s user.

New in version 2.32.

host_equal(v2)¶

Parameters:	v2 (`Soup.URI`) – a `Soup.URI` with a non-`None` host member
Returns:	whether or not the URIs are equal in scheme, host, and port.
Return type:	`bool`

Compares self and v2, considering only the scheme, host, and port.

New in version 2.28.

host_hash()¶

Returns:	a hash
Return type:	`int`

Hashes self, considering only the scheme, host, and port.

New in version 2.28.

set_fragment(fragment)¶

Parameters:	fragment (`str` or `None`) – the fragment

Sets self’s fragment to fragment.

set_host(host)¶

Parameters:	host (`str` or `None`) – the hostname or IP address, or `None`

Sets self’s host to host.

If host is an IPv6 IP address, it should not include the brackets required by the URI syntax; they will be added automatically when converting self to a string.

http and https URIs should not have a None host.

set_password(password)¶

Parameters:	password (`str` or `None`) – the password, or `None`

Sets self’s password to password.

set_path(path)¶

Parameters:	path (`str`) – the non-`None` path

Sets self’s path to path.

set_port(port)¶

Parameters:	port (`int`) – the port, or 0

Sets self’s port to port. If port is 0, self will not have an explicitly-specified port.

set_query(query)¶

Parameters:	query (`str` or `None`) – the query

Sets self’s query to query.

set_query_from_form(form)¶

Parameters:	form ({`str`: `str`}) – a `GLib.HashTable` containing HTML form information

Sets self’s query to the result of encoding form according to the HTML form rules. See Soup.form_encode_hash() for more information.

set_scheme(scheme)¶

Parameters:	scheme (`str`) – the URI scheme

Sets self’s scheme to scheme. This will also set self’s port to the default port for scheme, if known.

set_user(user)¶

Parameters:	user (`str` or `None`) – the username, or `None`

Sets self’s user to user.

to_string(just_path_and_query)¶

Parameters:	just_path_and_query (`bool`) – if `True`, output just the path and query portions
Returns:	a string representing self, which the caller must free.
Return type:	`str`

Returns a string representing self.

If just_path_and_query is True, this concatenates the path and query together. That is, it constructs the string that would be needed in the Request-Line of an HTTP request for self.

Note that the output will never contain a password, even if self does.

uses_default_port()¶

Returns:	`True` or `False`
Return type:	`bool`

Tests if self uses the default port for its scheme. (Eg, 80 for http.) (This only works for http, https and ftp; libsoup does not know the default ports of other protocols.)