Functions ¶

Returns:

the version string, or None for error.

Return type:

Parses the DriverVer string into a recognisable version and timestamp;

New in version 0.3.5.

AppStreamGlib.inf_load_data(keyfile, data, flags)[source]¶

Parameters:

keyfile (GLib.KeyFile) – a GLib.KeyFile
data (str) – the .inf file date to parse
flags (AppStreamGlib.InfLoadFlags) – AppStreamGlib.InfLoadFlags, e.g. AppStreamGlib.InfLoadFlags.NONE

Raises:

Returns:

True for success

Return type:

Repairs .inf file data and opens it as a keyfile.

Important: The group and keynames are all forced to lower case as INF files are specified as case insensitive and GLib.KeyFile *is* case sensitive. Any backslashes or spaces in the key name are also converted to ‘_’.

New in version 0.3.5.

AppStreamGlib.inf_load_file(keyfile, filename, flags)[source]¶

Parameters:

keyfile (GLib.KeyFile) – a GLib.KeyFile
filename (str) – the .inf file to open
flags (AppStreamGlib.InfLoadFlags) – AppStreamGlib.InfLoadFlags, e.g. AppStreamGlib.InfLoadFlags.NONE

Raises:

Returns:

True for success

Return type:

Repairs an .inf file and opens it as a keyfile.

New in version 0.3.5.

AppStreamGlib.kudo_kind_from_string(kudo_kind)[source]¶

Parameters:: kudo_kind (str) – the string.
Returns:: a AppStreamGlib.KudoKind or AppStreamGlib.KudoKind.UNKNOWN for unknown
Return type:: AppStreamGlib.KudoKind

Converts the text representation to an enumerated value.

New in version 0.2.2.

AppStreamGlib.kudo_kind_to_string(kudo_kind)[source]¶

Parameters:: kudo_kind (AppStreamGlib.KudoKind) – the AsKudoKind.
Returns:: string version of kudo_kind
Return type:: str

Converts the enumerated value to an text representation.

New in version 0.2.2.

AppStreamGlib.markup_convert(markup, format)[source]¶

Parameters:

markup (str) – the text to copy.
format (AppStreamGlib.MarkupConvertFormat) – the AppStreamGlib.MarkupConvertFormat, e.g. AppStreamGlib.MarkupConvertFormat.MARKDOWN

Raises:

Returns:

a newly allocated None terminated string

Return type:

Converts an XML description into a printable form.

New in version 0.3.5.

AppStreamGlib.markup_convert_full(markup, format, flags)[source]¶

Parameters:

markup (str) – the text to copy.
format (AppStreamGlib.MarkupConvertFormat) – the AppStreamGlib.MarkupConvertFormat, e.g. AppStreamGlib.MarkupConvertFormat.MARKDOWN
flags (AppStreamGlib.MarkupConvertFlag) – the AppStreamGlib.MarkupConvertFlag, e.g. AppStreamGlib.MarkupConvertFlag.IGNORE_ERRORS

Raises:

Returns:

a newly allocated None terminated string

Return type:

Converts an XML description into a printable form.

New in version 0.3.5.

AppStreamGlib.markup_convert_simple(markup)[source]¶

Parameters:: markup (str) – the text to copy.
Raises:: GLib.Error
Returns:: a newly allocated None terminated string
Return type:: str

Converts an XML description into a printable form.

New in version 0.1.0.

AppStreamGlib.markup_import(text, format)[source]¶

Parameters:

text (str) – the text to import.
format (AppStreamGlib.MarkupConvertFormat) – the AppStreamGlib.MarkupConvertFormat, e.g. AppStreamGlib.MarkupConvertFormat.SIMPLE

Raises:

Returns:

appstream markup, or None in event of an error

Return type:

Imports text and converts to AppStream markup.

New in version 0.5.11.

AppStreamGlib.markup_strsplit_words(text, line_len)[source]¶

Parameters:

text (str) – the text to split.
line_len (int) – the maximum length of the output line

Returns:

lines, or None in event of an error

Return type:

[str]

Splits up a long line into an array of smaller strings, each being no longer than line_len. Words are not split.

New in version 0.3.5.

AppStreamGlib.markup_validate(markup)[source]¶

Parameters:: markup (str) – the text to validate
Raises:: GLib.Error
Returns:: True if the appstream description was valid
Return type:: bool

Validates some markup.

New in version 0.5.1.

AppStreamGlib.node_error_quark()[source]¶

Returns:: An error quark.
Return type:: int

New in version 0.1.0.

AppStreamGlib.node_get_attribute(node, key)[source]¶

Parameters:

node (GLib.Node) – a #AsNode
key (str) – the attribute key

Returns:

string value

Return type:

Gets a node attribute, e.g. “false”

New in version 0.1.0.

AppStreamGlib.node_get_attribute_as_int(node, key)[source]¶

Parameters:

node (GLib.Node) – a #AsNode
key (str) – the attribute key

Returns:

integer value, or GObject.G_MAXINT for error

Return type:

Gets a node attribute, e.g. 34

New in version 0.1.0.

AppStreamGlib.node_get_attribute_as_uint(node, key)[source]¶

Parameters:

node (GLib.Node) – a #AsNode
key (str) – the attribute key

Returns:

integer value, or GObject.G_MAXINT for error

Return type:

Gets a node attribute, e.g. 34

New in version 0.6.1.

AppStreamGlib.node_get_comment(node)[source]¶

Parameters:: node (GLib.Node) – a #AsNode
Returns:: string value, or None
Return type:: str

New in version 0.1.6.

AppStreamGlib.node_get_data(node)[source]¶

Parameters:: node (GLib.Node) – a #AsNode
Returns:: string value
Return type:: str

Gets the node data, e.g. “paragraph text”

New in version 0.1.0.

AppStreamGlib.node_get_localized(node, key)[source]¶

Parameters:

node (GLib.Node) – a #AsNode
key (str) – the key to use, e.g. “copyright”

Returns:

A hash table with the locale (e.g. en_GB) as the key

Return type:

{object: object}

Extracts localized values from the DOM tree

New in version 0.1.0.

AppStreamGlib.node_get_localized_best(node, key)[source]¶

Parameters:

node (GLib.Node) – a #AsNode.
key (str) – the tag name.

Returns:

the string value, or None if there was no data

Return type:

Gets the ‘best’ locale version of a specific data value.

New in version 0.1.0.

AppStreamGlib.node_get_localized_unwrap(node)[source]¶

Parameters:: node (GLib.Node) – a #AsNode.
Raises:: GLib.Error
Returns:: a hash table of data
Return type:: {object: object}

Denormalize AppData data like this:

<description>
 <p>Hi</p>
 <p xml:lang="pl">Czesc</p>
 <ul>
  <li>First</li>
  <li xml:lang="pl">Pierwszy</li>
 </ul>
</description>

into a hash that contains:

"C"  ->  "<p>Hi</p><ul><li>First</li></ul>"
"pl" ->  "<p>Czesc</p><ul><li>Pierwszy</li></ul>"

New in version 0.1.0.

AppStreamGlib.node_get_name(node)[source]¶

Parameters:: node (GLib.Node) – a #AsNode
Returns:: string value
Return type:: str

Gets the node name, e.g. “body”

New in version 0.1.0.

AppStreamGlib.node_get_tag(node)[source]¶

Parameters:: node (GLib.Node) – a #AsNode
Returns:: AppStreamGlib.Tag, e.g. AppStreamGlib.Tag.PKGNAME
Return type:: AppStreamGlib.Tag

Gets the node tag enum.

New in version 0.1.2.

AppStreamGlib.node_insert_hash(parent, name, attr_key, hash, insert_flags)[source]¶

Parameters:

parent (GLib.Node) – a parent #AsNode.
name (str) – the tag name, e.g. “id”.
attr_key (str) – the key to use as the attribute in the XML, e.g. “key”.
hash ({object: object}) – the hash table with the key as the key to use in the XML.
insert_flags (AppStreamGlib.NodeInsertFlags) – any AppStreamGlib.NodeInsertFlags.

Inserts a hash table of data into the DOM.

New in version 0.1.0.

AppStreamGlib.node_insert_localized(parent, name, localized, insert_flags)[source]¶

Parameters:

parent (GLib.Node) – a parent #AsNode.
name (str) – the tag name, e.g. “id”.
localized ({object: object}) – the hash table of data, with the locale as the key.
insert_flags (AppStreamGlib.NodeInsertFlags) – any AppStreamGlib.NodeInsertFlags.

Inserts a localized key into the DOM.

New in version 0.1.0.

AppStreamGlib.node_to_xml(node, flags)[source]¶

Parameters:

node (GLib.Node) – a #AsNode.
flags (AppStreamGlib.NodeToXmlFlags) – the AppStreamGlib.NodeToXmlFlags, e.g. AppStreamGlib.NodeToXmlFlags.NONE.

Returns:

a GLib.String

Return type:

GLib.String

Converts a node and it’s children to XML.

New in version 0.1.0.

AppStreamGlib.node_unref(node)[source]¶

Parameters:: node (GLib.Node) – a #AsNode.

Deallocates all notes in the tree.

New in version 0.1.0.

AppStreamGlib.size_kind_from_string(size_kind)[source]¶

Parameters:: size_kind (str) – the string.
Returns:: a AppStreamGlib.SizeKind or AppStreamGlib.SizeKind.UNKNOWN for unknown
Return type:: AppStreamGlib.SizeKind

Converts the text representation to an enumerated value.

New in version 0.5.2.

AppStreamGlib.size_kind_to_string(size_kind)[source]¶

Parameters:: size_kind (AppStreamGlib.SizeKind) – the AppStreamGlib.SizeKind.
Returns:: string version of size_kind
Return type:: str

Converts the enumerated value to an text representation.

New in version 0.5.2.

AppStreamGlib.tag_from_string(tag)[source]¶

Parameters:: tag (str) – the string.
Returns:: a AppStreamGlib.Tag, or AppStreamGlib.Tag.UNKNOWN if not known.
Return type:: AppStreamGlib.Tag

Converts the text representation to an enumerated value.

New in version 0.1.0.

AppStreamGlib.tag_from_string_full(tag, flags)[source]¶

Parameters:

tag (str) – the string.
flags (AppStreamGlib.TagFlags) – the AppStreamGlib.TagFlags e.g. AppStreamGlib.TagFlags.USE_FALLBACKS

Returns:

a AppStreamGlib.Tag, or AppStreamGlib.Tag.UNKNOWN if not known.

Return type:

AppStreamGlib.Tag

Converts the text representation to an enumerated value also converting legacy key names.

New in version 0.1.2.

AppStreamGlib.tag_to_string(tag)[source]¶

Parameters:: tag (AppStreamGlib.Tag) – the AppStreamGlib.Tag value.
Returns:: string version of tag
Return type:: str

Converts the enumerated value to an text representation.

New in version 0.1.0.

AppStreamGlib.urgency_kind_from_string(urgency_kind)[source]¶

Parameters:: urgency_kind (str) – the string.
Returns:: a AppStreamGlib.UrgencyKind or AppStreamGlib.UrgencyKind.UNKNOWN for unknown
Return type:: AppStreamGlib.UrgencyKind

Converts the text representation to an enumerated value.

New in version 0.5.1.

AppStreamGlib.urgency_kind_to_string(urgency_kind)[source]¶

Parameters:: urgency_kind (AppStreamGlib.UrgencyKind) – the AppStreamGlib.UrgencyKind.
Returns:: string version of urgency_kind
Return type:: str

Converts the enumerated value to an text representation.

New in version 0.5.1.

AppStreamGlib.url_kind_from_string(url_kind)[source]¶

Parameters:: url_kind (str) – the string.
Returns:: a AppStreamGlib.UrlKind or AppStreamGlib.UrlKind.UNKNOWN for unknown
Return type:: AppStreamGlib.UrlKind

Converts the text representation to an enumerated value.

New in version 0.1.0.

AppStreamGlib.url_kind_to_string(url_kind)[source]¶

Parameters:: url_kind (AppStreamGlib.UrlKind) – the AsUrlKind.
Returns:: string version of url_kind
Return type:: str

Converts the enumerated value to an text representation.

New in version 0.1.0.

AppStreamGlib.utils_appstream_id_build(str)[source]¶

Parameters:: str (str) – a string to build the AppStream ID from
Returns:: a valid AppStream ID, or None if str is invalid
Return type:: str

Fixes a string to be a valid AppStream ID.

This function replaces any invalid chars with an underscore.

New in version 0.6.4.

AppStreamGlib.utils_appstream_id_valid(str)[source]¶

Parameters:: str (str) – a string
Returns:: True if the string is a valid AppStream ID
Return type:: bool

Checks to see if a string is a valid AppStream ID. A valid AppStream ID only contains alphanumeric chars, dots and dashes.

New in version 0.6.4.

AppStreamGlib.utils_error_quark()[source]¶

Returns:: An error quark.
Return type:: int

New in version 0.3.7.

AppStreamGlib.utils_find_icon_filename(destdir, search)[source]¶

Parameters:

destdir (str) – the destdir.
search (str) – the icon search name, e.g. “microphone.svg”

Raises:

Returns:

a newly allocated None terminated string

Return type:

Finds an icon filename from a filesystem root.

New in version 0.2.5.

AppStreamGlib.utils_find_icon_filename_full(destdir, search, flags)[source]¶

Parameters:

destdir (str) – the destdir.
search (str) – the icon search name, e.g. “microphone.svg”
flags (AppStreamGlib.UtilsFindIconFlag) – A AppStreamGlib.UtilsFindIconFlag bitfield

Raises:

Returns:

a newly allocated None terminated string

Return type:

Finds an icon filename from a filesystem root.

New in version 0.3.1.

AppStreamGlib.utils_guid_from_data(namespace_id, data, data_len)[source]¶

Parameters:

namespace_id (str) – A namespace ID, e.g. “6ba7b810-9dad-11d1-80b4-00c04fd430c8”
data (int) – data to hash
data_len (int) – length of data

Raises:

Returns:

A new GUID, or None if the namespace_id was invalid

Return type:

Returns a GUID for some data. This uses a hash and so even small differences in the data will produce radically different return values.

The implementation is taken from RFC4122, Section 4.1.3; specifically using a type-5 SHA-1 hash.

New in version 0.6.13.

AppStreamGlib.utils_guid_from_string(str)[source]¶

Parameters:: str (str) – A source string to use as a key
Returns:: A new GUID, or None if the string was invalid
Return type:: str

Returns a GUID for a given string. This uses a hash and so even small differences in the str will produce radically different return values.

The implementation is taken from RFC4122, Section 4.1.3; specifically using a type-5 SHA-1 hash with a DNS namespace. The same result can be obtained with this simple python program:

#!/usr/bin/python import uuid print uuid.uuid5(uuid.NAMESPACE_DNS, ‘python.org’)

New in version 0.5.0.

AppStreamGlib.utils_guid_is_valid(guid)[source]¶

Parameters:: guid (str) – string to check
Returns:: True if guid was a valid GUID, False otherwise
Return type:: bool

Checks the source string is a valid string GUID descriptor.

New in version 0.5.0.

AppStreamGlib.utils_install_filename(location, filename, origin, destdir)[source]¶

Parameters:

location (AppStreamGlib.UtilsLocation) – the AppStreamGlib.UtilsLocation, e.g. AppStreamGlib.UtilsLocation.CACHE
filename (str) – the full path of the file to install
origin (str) – the origin to use for the installation, or None
destdir (str) – the destdir to use, or None

Raises:

Returns:

True for success, False if error is set

Return type:

Installs an AppData, MetaInfo, AppStream XML or AppStream Icon metadata file.

New in version 0.3.4.

AppStreamGlib.utils_is_blacklisted_id(desktop_id)[source]¶

Parameters:: desktop_id (str) – a desktop ID, e.g. “gimp.desktop”
Returns:: True if the desktop ID is blacklisted
Return type:: bool

Searches the known list of blacklisted desktop IDs.

New in version 0.2.2.

AppStreamGlib.utils_is_category_id(category_id)[source]¶

Parameters:: category_id (str) – a desktop ID, e.g. “AudioVideoEditing”
Returns:: True if the category ID is valid
Return type:: bool

Searches the known list of registered category IDs.

New in version 0.2.4.

AppStreamGlib.utils_is_environment_id(environment_id)[source]¶

Parameters:: environment_id (str) – a desktop ID, e.g. “GNOME”
Returns:: True if the environment ID is valid
Return type:: bool

Searches the known list of registered environment IDs.

New in version 0.2.4.

AppStreamGlib.utils_is_spdx_license(license)[source]¶

Parameters:: license (str) – a SPDX license string, e.g. “CC-BY-3.0 and GFDL-1.3”
Returns:: True if the license is a valid “SPDX license”
Return type:: bool

Checks the licence string to check it being a valid licence. NOTE: SPDX licences can’t typically contain brackets.

New in version 0.2.5.

AppStreamGlib.utils_is_spdx_license_id(license_id)[source]¶

Parameters:: license_id (str) – a single SPDX license ID, e.g. “CC-BY-3.0”
Returns:: True if the license ID is a valid “SPDX license ID”
Return type:: bool

Searches the known list of SPDX license IDs.

New in version 0.1.5.

AppStreamGlib.utils_is_stock_icon_name(name)[source]¶

Parameters:: name (str) – an icon name
Returns:: True if the icon is a “stock icon name” and does not need to be included in the AppStream icon tarball
Return type:: bool

Searches the known list of stock icons.

New in version 0.1.3.

AppStreamGlib.utils_license_to_spdx(license)[source]¶

Parameters:: license (str) – a not-quite SPDX license string, e.g. “GPLv3+”
Returns:: the best-effort SPDX license string
Return type:: str

Converts a non-SPDX license into an SPDX format string where possible.

New in version 0.5.5.

AppStreamGlib.utils_search_token_valid(token)[source]¶

Parameters:: token (str) – the search token
Returns:: True is the search token was valid
Return type:: bool

Checks the search token if it is valid. Valid tokens are at least 3 chars in length, not common words like “and”, and do not contain markup.

New in version 0.3.4.

AppStreamGlib.utils_search_tokenize(search)[source]¶

Parameters:: search (str) – the search string
Returns:: Valid tokens to search for, or None for error
Return type:: [str]

Splits up a string into tokens and returns tokens that are suitable for searching. This includes taking out common words and casefolding the returned search tokens.

New in version 0.3.4.

AppStreamGlib.utils_spdx_license_detokenize(license_tokens)[source]¶

Parameters:: license_tokens (str) – license tokens, typically from AppStreamGlib.utils_spdx_license_tokenize()
Returns:: string, or None for invalid
Return type:: str

De-tokenizes the SPDX licenses into a string.

New in version 0.2.5.

AppStreamGlib.utils_spdx_license_tokenize(license)[source]¶

Parameters:: license (str) – a license string, e.g. “LGPLv2+ and (QPL or GPLv2) and MIT”
Returns:: array of strings, or None for invalid
Return type:: [str]

Tokenizes the SPDX license string (or any simarly formatted string) into parts. Any licence parts of the string e.g. “LGPL-2.0+” are prefexed with “@”, the conjunctive replaced with “&” and the disjunctive replaced with “|”. Brackets are added as indervidual tokens and other strings are appended into single tokens where possible.

New in version 0.1.5.

AppStreamGlib.utils_string_replace(string, search, replace)[source]¶

Parameters:

string (GLib.String) – The GLib.String to operate on
search (str) – The text to search for
replace (str) – The text to use for substitutions

Returns:

the number of replacements done, or 0 if search is not found.

Return type:

Performs multiple search and replace operations on the given string.

New in version 0.5.11.

AppStreamGlib.utils_unique_id_build(scope, bundle_kind, origin, kind, id, branch)[source]¶

Parameters:

scope (AppStreamGlib.AppScope) – a AppStreamGlib.AppScope e.g. AppStreamGlib.AppScope.SYSTEM
bundle_kind (AppStreamGlib.BundleKind) – System, e.g. ‘package’ or ‘flatpak’
origin (str) – Origin, e.g. ‘fedora’ or ‘gnome-apps-nightly’
kind (AppStreamGlib.AppKind) – AppStreamGlib.AppKind, e.g. AppStreamGlib.AppKind.DESKTOP
id (str) – AppStream ID, e.g. ‘gimp.desktop’
branch (str) – Branch, e.g. ‘3-20’ or ‘master’

Returns:

a unique name, or None for error;

Return type:

Builds a valid unique ID using available data.

New in version 0.6.1.

AppStreamGlib.utils_unique_id_equal(unique_id1, unique_id2)[source]¶

Parameters:

unique_id1 (str) – a unique ID
unique_id2 (str) – another unique ID

Returns:

True if the ID’s should be considered equal.

Return type:

Checks two unique IDs for equality allowing globs to match.

New in version 0.6.1.

AppStreamGlib.utils_unique_id_hash(unique_id)[source]¶

Parameters:: unique_id (str) – a unique ID
Returns:: a hash value corresponding to the key
Return type:: int

Converts a unique-id to a hash value.

This function implements the widely used DJB hash on the ID subset of the unique-id string.

It can be passed to g_hash_table_new() as the hash_func parameter, when using non-None strings or unique_ids as keys in a GLib.HashTable.

New in version 0.6.2.

AppStreamGlib.utils_unique_id_match(unique_id1, unique_id2, match_flags)[source]¶

Parameters:

unique_id1 (str) – a unique ID
unique_id2 (str) – another unique ID
match_flags (AppStreamGlib.UniqueIdMatchFlags) – a AppStreamGlib.UniqueIdMatchFlags bitfield, e.g. AppStreamGlib.UniqueIdMatchFlags.ID

Returns:

True if the ID’s should be considered equal.

Return type:

Checks two unique IDs for equality allowing globs to match, whilst also allowing clients to whitelist sections that have to match.

New in version 0.7.8.

AppStreamGlib.utils_unique_id_valid(unique_id)[source]¶

Parameters:: unique_id (str) – a unique ID
Returns:: True if the ID is valid
Return type:: bool

Checks if a unique ID is valid i.e. has the correct number of sections.

New in version 0.6.1.

AppStreamGlib.utils_vercmp(version_a, version_b)[source]¶

Parameters:

version_a (str) – the release version, e.g. 1.2.3
version_b (str) – the release version, e.g. 1.2.3.1

Returns:

-1 if a < b, +1 if a > b, 0 if they are equal, and GObject.G_MAXINT on error

Return type:

Compares version numbers for sorting.

New in version 0.3.5.

AppStreamGlib.utils_vercmp_full(version_a, version_b, flags)[source]¶

Parameters:

version_a (str) – the release version, e.g. 1.2.3
version_b (str) – the release version, e.g. 1.2.3.1
flags (AppStreamGlib.VersionCompareFlag) – some AppStreamGlib.VersionCompareFlag

Returns:

-1 if a < b, +1 if a > b, 0 if they are equal, and GObject.G_MAXINT on error

Return type:

Compares version numbers for sorting.

New in version 0.7.15.

AppStreamGlib.utils_version_from_uint16(val, flags)[source]¶

Parameters:

val (int) – A uint16le version number
flags (AppStreamGlib.VersionParseFlag) – flags used for formatting, e.g. AppStreamGlib.VersionParseFlag.USE_TRIPLET

Returns:

A version number, e.g. “1.3”

Return type:

Returns a dotted decimal version string from a 16 bit number.

New in version 0.5.2.

AppStreamGlib.utils_version_from_uint32(val, flags)[source]¶

Parameters:

val (int) – A uint32le version number
flags (AppStreamGlib.VersionParseFlag) – flags used for formatting, e.g. AppStreamGlib.VersionParseFlag.USE_TRIPLET

Returns:

A version number, e.g. “1.0.3”

Return type: