Uri

class Uri(**kwargs)

A Uri object can be used to parse and split a URI string into its constituent parts. Two Uri objects can be joined to make a new Uri using the algorithm described in RFC3986.

Constructors

class Uri

Creates a new Uri object with the given URI parts. The path and query strings will be broken down into their elements. All strings should not be escaped except where indicated.

Added in version 1.6.

Parameters:

scheme – The scheme for the new URI.
userinfo – The user-info for the new URI.
host – The host name for the new URI.
port – The port number for the new URI or URI_NO_PORT.
path – The path for the new URI with ‘/’ separating path elements.
query – The query string for the new URI with ‘&’ separating query elements. Elements containing ‘&’ characters should encode them as “&percnt;26”.
fragment – The fragment name for the new URI.

Methods

class Uri

append_path(relative_path: str | None = None) → bool

Append a path onto the end of the path in the URI. The path is not normalized, call ``gst_uri_normalize``() to normalize the path.

Added in version 1.6.

Parameters:: relative_path – Relative path to append to the end of the current path.

append_path_segment(path_segment: str | None = None) → bool

Append a single path segment onto the end of the URI path.

Added in version 1.6.

Parameters:: path_segment – The path segment string to append to the URI path.

construct(protocol: str, location: str) → str

Constructs a URI for a given valid protocol and location.

Free-function: g_free

Deprecated since version Unknown: Use GstURI instead.

Parameters:

protocol – Protocol for URI
location – Location for URI

equal(second: Uri) → bool

Compares two Uri objects to see if they represent the same normalized URI.

Added in version 1.6.

Parameters:: second – Second Uri to compare.

from_string(uri: str) → Uri | None

Parses a URI string into a new Uri object. Will return NULL if the URI cannot be parsed.

Added in version 1.6.

Parameters:: uri – The URI string to parse.

from_string_escaped(uri: str) → Uri | None

Parses a URI string into a new Uri object. Will return NULL if the URI cannot be parsed. This is identical to from_string() except that the userinfo and fragment components of the URI will not be unescaped while parsing.

Use this when you need to extract a username and password from the userinfo such as https://user:password``example``.com since either may contain a URI-escaped ‘:’ character. from_string() will unescape the entire userinfo component, which will make it impossible to know which ‘:’ delineates the username and password.

The same applies to the fragment component of the URI, such as https://example.com/path#fragment which may contain a URI-escaped ‘#’.

Added in version 1.18.

Parameters:: uri – The URI string to parse.

from_string_with_base(uri: str) → Uri | None

Like from_string() but also joins with a base URI.

Added in version 1.6.

Parameters:: uri – The URI string to parse.

get_fragment() → str | None: Get the fragment name from the URI or None if it doesn’t exist. If uri is None then returns None.

Added in version 1.6.

get_host() → str | None: Get the host name from the URI or None if it doesn’t exist. If uri is None then returns None.

Added in version 1.6.

get_location(uri: str) → str | None

Extracts the location out of a given valid URI, ie. the protocol and “://” are stripped from the URI, which means that the location returned includes the hostname if one is specified. The returned string must be freed using free().

Free-function: g_free

Parameters:: uri – A URI string

get_media_fragment_table() → dict[str, str] | None

Get the media fragment table from the URI, as defined by “Media Fragments URI 1.0”. Hash table returned by this API is a list of “key-value” pairs, and the each pair is generated by splitting “URI fragment” per “&” sub-delims, then “key” and “value” are split by “=” sub-delims. The “key” returned by this API may be undefined keyword by standard. A value may be None to indicate that the key should appear in the fragment string in the URI, but does not have a value. Free the returned HashTable with ``g_hash_table_unref``() when it is no longer required. Modifying this hash table does not affect the fragment in the URI.

See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/

Added in version 1.12.

get_path() → str | None: Extract the path string from the URI object.

Added in version 1.6.

get_path_segments() → list[str]: Get a list of path segments from the URI.

Added in version 1.6.

get_path_string() → str | None: Extract the path string from the URI object as a percent encoded URI path.

Added in version 1.6.

get_port() → int: Get the port number from the URI or URI_NO_PORT if it doesn’t exist. If uri is None then returns URI_NO_PORT.

Added in version 1.6.

get_protocol(uri: str) → str | None

Extracts the protocol out of a given valid URI. The returned string must be freed using free().

Parameters:: uri – A URI string

get_query_keys() → list[str]: Get a list of the query keys from the URI.

Added in version 1.6.

get_query_string() → str | None: Get a percent encoded URI query string from the uri.

Added in version 1.6.

get_query_table() → dict[str, str] | None: Get the query table from the URI. Keys and values in the table are freed with g_free when they are deleted. A value may be None to indicate that the key should appear in the query string in the URI, but does not have a value. Free the returned HashTable with ``g_hash_table_unref``() when it is no longer required. Modifying this hash table will modify the query in the URI.

Added in version 1.6.

get_query_value(query_key: str) → str | None

Get the value associated with the query_key key. Will return None if the key has no value or if the key does not exist in the URI query table. Because None is returned for both missing keys and keys with no value, you should use query_has_key() to determine if a key is present in the URI query.

Added in version 1.6.

Parameters:: query_key – The key to lookup.

get_scheme() → str | None: Get the scheme name from the URI or None if it doesn’t exist. If uri is None then returns None.

get_userinfo() → str | None: Get the userinfo (usually in the form “username:password”) from the URI or None if it doesn’t exist. If uri is None then returns None.

Added in version 1.6.

has_protocol(uri: str, protocol: str) → bool

Checks if the protocol of a given valid URI matches protocol.

Parameters:

uri – a URI string
protocol – a protocol string (e.g. “http”)

is_normalized() → bool: Tests the uri to see if it is normalized. A None uri is considered to be normalized.

Added in version 1.6.

is_valid(uri: str) → bool

Tests if the given string is a valid URI identifier. URIs start with a valid scheme followed by “:” and maybe a string identifying the location.

Parameters:: uri – A URI string

is_writable() → bool

Check if it is safe to write to this Uri.

Check if the refcount of uri is exactly 1, meaning that no other reference exists to the Uri and that the Uri is therefore writable.

Modification of a Uri should only be done after verifying that it is writable.

Added in version 1.6.

join(ref_uri: Uri | None = None) → Uri | None

Join a reference URI onto a base URI using the method from RFC 3986. If either URI is None then the other URI will be returned with the ref count increased.

Added in version 1.6.

Parameters:: ref_uri – The reference URI to join onto the base URI.

join_strings(base_uri: str, ref_uri: str) → str | None

This is a convenience function to join two URI strings and return the result. The returned string should be free()’d after use.

Added in version 1.6.

Parameters:

base_uri – The percent-encoded base URI.
ref_uri – The percent-encoded reference URI to join to the base_uri.

make_writable() → Uri

Make the Uri writable.

Checks if uri is writable, and if so the original object is returned. If not, then a writable copy is made and returned. This gives away the reference to uri and returns a reference to the new Uri. If uri is None then None is returned.

Added in version 1.6.

Like new(), but joins the new URI onto a base URI.

Added in version 1.6.

Parameters:

scheme – The scheme for the new URI.
userinfo – The user-info for the new URI.
host – The host name for the new URI.
port – The port number for the new URI or URI_NO_PORT.
path – The path for the new URI with ‘/’ separating path elements.
query – The query string for the new URI with ‘&’ separating query elements. Elements containing ‘&’ characters should encode them as “&percnt;26”.
fragment – The fragment name for the new URI.

normalize() → bool

Normalization will remove extra path segments (“.” and “..”) from the URI. It will also convert the scheme and host name to lower case and any percent-encoded values to uppercase.

The Uri object must be writable. Check with is_writable() or use make_writable() first.

Added in version 1.6.

protocol_is_supported(type: URIType, protocol: str) → bool

Checks if an element exists that supports the given URI protocol. Note that a positive return value does not imply that a subsequent call to make_from_uri() is guaranteed to work.

Parameters:

type – Whether to check for a source or a sink
protocol – Protocol that should be checked for (e.g. “http” or “smb”)

protocol_is_valid(protocol: str) → bool

Tests if the given string is a valid protocol identifier. Protocols must consist of alphanumeric characters, ‘+’, ‘-’ and ‘.’ and must start with a alphabetic character. See RFC 3986 Section 3.1.

Parameters:: protocol – A string

query_has_key(query_key: str) → bool

Check if there is a query table entry for the query_key key.

Added in version 1.6.

Parameters:: query_key – The key to lookup.

remove_query_key(query_key: str) → bool

Remove an entry from the query table by key.

Added in version 1.6.

Parameters:: query_key – The key to remove.

set_fragment(fragment: str | None = None) → bool

Sets the fragment string in the URI. Use a value of None in fragment to unset the fragment string.

Added in version 1.6.

Parameters:: fragment – The fragment string to set.

set_host(host: str) → bool

Set or unset the host for the URI.

Added in version 1.6.

Parameters:: host – The new host string to set or None to unset.

set_path(path: str | None = None) → bool

Sets or unsets the path in the URI.

Added in version 1.6.

Parameters:: path – The new path to set with path segments separated by ‘/’, or use None to unset the path.

set_path_segments(path_segments: list[str] | None = None) → bool

Replace the path segments list in the URI.

Added in version 1.6.

Parameters:: path_segments – The new path list to set.

set_path_string(path: str) → bool

Sets or unsets the path in the URI.

Added in version 1.6.

Parameters:: path – The new percent encoded path to set with path segments separated by ‘/’, or use None to unset the path.

set_port(port: int) → bool

Set or unset the port number for the URI.

Added in version 1.6.

Parameters:: port – The new port number to set or URI_NO_PORT to unset.

set_query_string(query: str | None = None) → bool

Sets or unsets the query table in the URI.

Added in version 1.6.

Parameters:: query – The new percent encoded query string to use to populate the query table, or use None to unset the query table.

set_query_table(query_table: dict[str, str] | None = None) → bool

Set the query table to use in the URI. The old table is unreferenced and a reference to the new one is used instead. A value if None for query_table will remove the query string from the URI.

Added in version 1.6.

Parameters:: query_table – The new query table to use.

set_query_value(query_key: str, query_value: str | None = None) → bool

This inserts or replaces a key in the query table. A query_value of None indicates that the key has no associated value, but will still be present in the query string.

Added in version 1.6.

Parameters:

query_key – The key for the query entry.
query_value – The value for the key.

set_scheme(scheme: str) → bool

Set or unset the scheme for the URI.

Added in version 1.6.

Parameters:: scheme – The new scheme to set or None to unset the scheme.

set_userinfo(userinfo: str) → bool

Set or unset the user information for the URI.

Added in version 1.6.

Parameters:: userinfo – The new user-information string to set or None to unset.

to_string() → str

Convert the URI to a string.

Returns the URI as held in this object as a free the string once they are finished with it. The string is put together as described in RFC 3986.

Added in version 1.6.