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
- classmethod new(scheme: str | None, userinfo: str | None, host: str | None, port: int, path: str | None = None, query: str | None = None, fragment: str | None = None) 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 “%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 tofrom_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. Ifuri
isNone
then returnsNone
.Added in version 1.6.
- get_host() str | None
Get the host name from the URI or
None
if it doesn’t exist. Ifuri
isNone
then returnsNone
.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 returnedHashTable
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_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. Ifuri
isNone
then returnsURI_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_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 returnedHashTable
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 returnNone
if the key has no value or if the key does not exist in the URI query table. BecauseNone
is returned for both missing keys and keys with no value, you should usequery_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. Ifuri
isNone
then returnsNone
.
- get_userinfo() str | None
Get the userinfo (usually in the form “username:password”) from the URI or
None
if it doesn’t exist. Ifuri
isNone
then returnsNone
.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. ANone
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 theUri
and that theUri
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 touri
and returns a reference to the newUri
. Ifuri
isNone
thenNone
is returned.Added in version 1.6.
- new_with_base(scheme: str | None, userinfo: str | None, host: str | None, port: int, path: str | None = None, query: str | None = None, fragment: str | None = None) Uri
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 “%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 withis_writable()
or usemake_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
infragment
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
forquery_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
ofNone
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.