Functions¶

	`build_component_global_id` (component_id, checksum)
	`component_get_source_icon` (cpt)
	`compose_error_quark` ()
	`compute_content_checksum_for_data` (data, length)
	`globals_add_hint_tag` (tag, severity, explanation, override_existing)
	`globals_fetch_hint_tags` ()
	`globals_get_ffprobe_binary` ()
	`globals_get_optipng_binary` ()
	`globals_get_tmp_dir` ()
	`globals_get_use_optipng` ()
	`globals_hint_tag_exists` (tag)
	`globals_hint_tag_explanation` (tag)
	`globals_hint_tag_severity` (tag)
	`globals_set_ffprobe_binary` (path)
	`globals_set_optipng_binary` (path)
	`globals_set_tmp_dir` (path)
	`globals_set_use_optipng` (enabled)
	`icon_state_from_string` (state_str)
	`icon_state_to_string` (istate)
	`image_format_from_filename` (fname)
	`image_format_from_string` (str)
	`image_format_to_string` (format)
	`media_error_is_worker_failure` (error)
	`media_error_quark` ()

Details¶

AppStreamCompose.build_component_global_id(component_id, checksum)¶

Parameters:

component_id (str) – an AppStream component ID.
checksum (str) – a checksum as string generated from the component’s combined metadata.

Raises:

GLib.Error

Returns:

The new global ID, or None on error.

Return type:

str or None

Builds a global component ID from a component-id and a checksum (usually Blake3) generated from the component data.

The global-id is used as a global, unique identifier for a component. (while the component-ID is local, e.g. for one source). Its primary usecase is to identify a media directory on the filesystem which is associated with this component.

Since the result is used to construct filesystem paths, this function will refuse to build a global ID unless every segment it is made of - the pieces of the component-ID as well as checksum - is safe to use as a directory name. The error that is set in that case names the offending piece, and is meant to be shown to whoever wrote the metadata.

Added in version 0.13.0.

AppStreamCompose.component_get_source_icon(cpt)¶

Parameters:: cpt (AppStream.Component) – an AppStream.Component instance.
Returns:: The source AppStream.Icon, or None if the component has none.
Return type:: AppStream.Icon or None

Find the unprocessed icon that a component was created with, that is the icon reference that came straight from its metainfo or desktop-entry file. A stock icon is preferred, but a local one is accepted as well to accommodate for applications that used the “local” icon type wrong.

This is the icon that appstream-compose renders its icon set from. If AppStreamCompose.ComposeFlags.IGNORE_ICONS is set, it is left on the component untouched, so that the caller can run its own icon processing on it.

Added in version 1.2.0.

AppStreamCompose.compose_error_quark()¶

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

Added in version 0.13.0.

AppStreamCompose.compute_content_checksum_for_data(data, length)¶

Parameters:

data (str) – The data to hash.
length (int) – Length of data.

Returns:

The hash as hexadecimal string. Free with GLib.free

Return type:

str

Compute a checksum for the given content.

The output of this function is intended to be used with AppStreamCompose.build_component_global_id to form a unique global ID. The generated checksum is intended to be used as content-ID. Do not assume it is cryptographically secure or has a certain length!

Added in version 1.1.3.

AppStreamCompose.globals_add_hint_tag(tag, severity, explanation, override_existing)¶

Parameters:

tag (str) – the tag-ID to add
severity (AppStream.IssueSeverity) – the tag severity as AppStream.IssueSeverity
explanation (str) – the tag explanatory message
override_existing (bool) – whether an existing tag should be replaced

Returns:

True if the tag was registered and did not exist previously.

Return type:

bool

Register a new hint tag. If a previous tag with the given name already existed, the existing tag will not be replaced unless override_existing is set to True. Please be careful when overriding tags! Tag severities can not be lowered by overriding a tag.

Added in version 0.14.0.

AppStreamCompose.globals_fetch_hint_tags()¶

Returns:: A list of valid hint tags. Free with GLib.strfreev
Return type:: [str]

Retrieve all hint tags that we know.

Added in version 0.14.0.

AppStreamCompose.globals_get_ffprobe_binary()¶

Returns:: The binary path, or None if ffprobe was not found. The string is owned by the global state and is valid until the setting is changed, which is prohibited once composing metadata has started.
Return type:: str or None

Get path to the “ffprobe” binary we should use.

Added in version 0.14.6.

AppStreamCompose.globals_get_optipng_binary()¶

Returns:: The binary path, or None if optipng was not found. The string is owned by the global state and is valid until the setting is changed, which is prohibited once composing metadata has started.
Return type:: str or None

Get path to the “optipng” binary we should use.

Added in version 0.13.0.

AppStreamCompose.globals_get_tmp_dir()¶

Returns:: The temporary directory. The string is owned by the global state and is valid until the setting is changed, which is prohibited once composing metadata has started.
Return type:: str

Get temporary directory used by appstream-compose.

Added in version 0.13.0.

AppStreamCompose.globals_get_use_optipng()¶

Returns:: True if optipng should be used.
Return type:: bool

Get whether images should be optimized using optipng.

Added in version 0.13.0.

AppStreamCompose.globals_hint_tag_exists(tag)¶

Parameters:: tag (str) – A hint tag name.
Returns:: True if the tag is known.
Return type:: bool

Check whether a hint tag with the given name is registered.

Added in version 1.2.0.

AppStreamCompose.globals_hint_tag_explanation(tag)¶

Parameters:: tag (str)
Returns:: An explanation template, or None if the tag was not found.
Return type:: str

Retrieve the explanation template of the given hint tag.

Added in version 0.14.0.

AppStreamCompose.globals_hint_tag_severity(tag)¶

Parameters:: tag (str)
Returns:: An AppStream.IssueSeverity or AppStream.IssueSeverity.UNKNOWN if the tag did not exist or has an unknown severity.
Return type:: AppStream.IssueSeverity

Retrieve the severity of the given hint tag.

Added in version 0.14.0.

AppStreamCompose.globals_set_ffprobe_binary(path)¶

Parameters:: path (str or None) – the “ffprobe” binary path, or None.

Set path to the “ffprobe” binary we should use.

This has to be done before composing metadata starts. Once work has begun, changing any global setting is forbidden.

Added in version 0.14.6.

AppStreamCompose.globals_set_optipng_binary(path)¶

Parameters:: path (str or None) – the “optipng” binary path, or None.

Set path to the “optipng” binary we should use.

This has to be done before composing metadata starts. Once work has begun, changing any global setting is forbidden.

Added in version 0.13.0.

AppStreamCompose.globals_set_tmp_dir(path)¶

Parameters:: path (str) – the new temporary directory.

Set temporary directory used by appstream-compose.

This has to be done before composing metadata starts. Once work has begun, changing any global setting is forbidden.

Added in version 0.13.0.

AppStreamCompose.globals_set_use_optipng(enabled)¶

Parameters:: enabled (bool) – True to optimize images with optipng.

Set whether images should be optimized using optipng.

This has to be done before composing metadata starts. Once work has begun, changing any global setting is forbidden.

Added in version 0.13.0.

AppStreamCompose.icon_state_from_string(state_str)¶

Parameters:: state_str (str) – the string.
Returns:: a AppStreamCompose.IconState
Return type:: AppStreamCompose.IconState

Converts the text representation to an enumerated value.

Added in version 1.0.2.

AppStreamCompose.icon_state_to_string(istate)¶

Parameters:: istate (AppStreamCompose.IconState) – the AppStreamCompose.IconState.
Returns:: string version of istate
Return type:: str

Converts the enumerated value to an text representation.

Added in version 1.0.2.

AppStreamCompose.image_format_from_filename(fname)¶

Parameters:: fname (str) – the filename.
Returns:: a AppStreamCompose.ImageFormat or AppStreamCompose.ImageFormat.UNKNOWN for unknown
Return type:: AppStreamCompose.ImageFormat

Returns the image format type based on the given file’s filename.

Added in version 0.13.0.

AppStreamCompose.image_format_from_string(str)¶

Parameters:: str (str) – the string.
Returns:: a AppStreamCompose.ImageFormat or AppStreamCompose.ImageFormat.UNKNOWN for unknown
Return type:: AppStreamCompose.ImageFormat

Converts the text representation to an enumerated value.

Added in version 0.13.0.

AppStreamCompose.image_format_to_string(format)¶

Parameters:: format (AppStreamCompose.ImageFormat) – the AppStreamCompose.ImageFormat.
Returns:: string version of format
Return type:: str

Converts the enumerated value to an text representation.

Added in version 0.13.0.

AppStreamCompose.media_error_is_worker_failure(error)¶

Parameters:: error (GLib.Error or None) – A GLib.Error returned by a media operation.
Returns:: True if the worker misbehaved.
Return type:: bool

Check whether the given error indicates that the media worker itself malfunctioned, as opposed to the processed media simply being broken. Only the former should be reported to users as a worker problem.

Added in version 1.2.0.

AppStreamCompose.media_error_quark()¶

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

Added in version 1.2.0.