AppStream.Component

g AppStream.Component AppStream.Component GObject.Object GObject.Object GObject.Object->AppStream.Component

Subclasses:None

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
class new ()
class scope_from_string (scope_str)
class scope_to_string (scope)
  add_addon (addon)
  add_agreement (agreement)
  add_bundle (bundle)
  add_category (category)
  add_content_rating (content_rating)
  add_extends (cpt_id)
  add_icon (icon)
  add_language (locale, percentage)
  add_launchable (launchable)
  add_provided (prov)
  add_relation (relation)
  add_release (release)
  add_screenshot (sshot)
  add_suggested (suggested)
  add_translation (tr)
  add_url (url_kind, url)
  get_active_locale ()
  get_addons ()
  get_agreement_by_kind (kind)
  get_bundle (bundle_kind)
  get_bundles ()
  get_categories ()
  get_compulsory_for_desktops ()
  get_content_rating (kind)
  get_content_ratings ()
  get_context ()
  get_custom ()
  get_custom_value (key)
  get_data_id ()
  get_description ()
  get_desktop_id ()
  get_developer_name ()
  get_extends ()
  get_icon_by_size (width, height)
  get_icons ()
  get_id ()
  get_keywords ()
  get_keywords_table ()
  get_kind ()
  get_language (locale)
  get_languages ()
  get_launchable (kind)
  get_launchables ()
  get_merge_kind ()
  get_metadata_license ()
  get_name ()
  get_name_table ()
  get_name_variant_suffix ()
  get_origin ()
  get_pkgname ()
  get_pkgnames ()
  get_project_group ()
  get_project_license ()
  get_provided ()
  get_provided_for_kind (kind)
  get_recommends ()
  get_releases ()
  get_requires ()
  get_scope ()
  get_screenshots ()
  get_search_tokens ()
  get_sort_score ()
  get_source_pkgname ()
  get_suggested ()
  get_summary ()
  get_summary_table ()
  get_translations ()
  get_url (url_kind)
  get_value_flags ()
  has_bundle ()
  has_category (category)
  insert_custom_value (key, value)
  is_compulsory_for_desktop (desktop)
  is_ignored ()
  is_member_of_category (category)
  is_valid ()
  load_from_xml_data (context, data)
  search_matches (term)
  search_matches_all (terms)
  set_active_locale (locale)
  set_compulsory_for_desktop (desktop)
  set_data_id (value)
  set_description (value, locale)
  set_developer_name (value, locale)
  set_id (value)
  set_keywords (value, locale)
  set_kind (value)
  set_merge_kind (kind)
  set_metadata_license (value)
  set_name (value, locale)
  set_name_variant_suffix (value, locale)
  set_origin (origin)
  set_pkgnames (packages)
  set_project_group (value)
  set_project_license (value)
  set_scope (scope)
  set_sort_score (score)
  set_source_pkgname (spkgname)
  set_summary (value, locale)
  set_value_flags (flags)
  to_string ()
  to_xml_data (context)

Virtual Methods

Inherited:GObject.Object (7)

Properties

Name Type Flags Short Description
categories GLib.PtrArray r categories
description str r/w description
developer-name str r/w developer-name
icons int r icons
id str r/w id
keywords [str] r/w keywords
kind AppStream.ComponentKind r/w kind
name str r/w name
pkgnames [str] r/w pkgnames
project-group str r/w project-group
project-license str r/w project-license
screenshots GLib.PtrArray r screenshots
summary str r/w summary
urls GLib.HashTable r urls

Signals

Inherited:GObject.Object (1)

Fields

Inherited:GObject.Object (1)
Name Type Access Description
parent_instance GObject.Object r  

Class Details

class AppStream.Component(**kwargs)
Bases:GObject.Object
Abstract:No
Structure:AppStream.ComponentClass
classmethod new()
Returns:a new AppStream.Component
Return type:AppStream.Component

Creates a new AppStream.Component.

classmethod scope_from_string(scope_str)
Parameters:scope_str (str) – the string.
Returns:a AppStream.ComponentScope or AppStream.ComponentScope.UNKNOWN for unknown
Return type:AppStream.ComponentScope

Converts the text representation to an enumerated value.

classmethod scope_to_string(scope)
Parameters:scope (AppStream.ComponentScope) – the AppStream.ComponentScope.
Returns:string version of scope
Return type:str

Converts the enumerated value to an text representation.

add_addon(addon)
Parameters:addon (AppStream.Component) – The AppStream.Component that extends self

Add a reference to the addon that is enhancing this component.

New in version 0.9.2.

add_agreement(agreement)
Parameters:agreement (AppStream.Agreement) – an AppStream.Agreement instance.

Adds an agreement to the software component.

New in version 0.12.1.

add_bundle(bundle)
Parameters:bundle (AppStream.Bundle) – The AppStream.Bundle to add.

Adds a bundle to the component.

New in version 0.8.0.

add_category(category)
Parameters:category (str) – the categories name to add.

Add a category.

add_content_rating(content_rating)
Parameters:content_rating (AppStream.ContentRating) – a AppStream.ContentRating instance.

Adds a content rating to this component.

New in version 0.11.0.

add_extends(cpt_id)
Parameters:cpt_id (str) – The id of a component which is extended by this component

Add a reference to the extended component

New in version 0.7.0.

add_icon(icon)
Parameters:icon (AppStream.Icon) – the valid AppStream.Icon instance to add.

Add an icon to this component.

add_language(locale, percentage)
Parameters:
  • locale (str or None) – the locale, or None. e.g. “en_GB”
  • percentage (int) – the percentage completion of the translation, 0 for locales with unknown amount of translation

Adds a language to the component.

New in version 0.7.0.

add_launchable(launchable)
Parameters:launchable (AppStream.Launchable) – a AppStream.Launchable instance.

Adds a AppStream.Launchable containing launchables entries for this component.

New in version 0.11.0.

add_provided(prov)
Parameters:prov (AppStream.Provided) – a AppStream.Provided instance.

Add a set of provided items to this component.

New in version 0.6.2.

add_relation(relation)
Parameters:relation (AppStream.Relation) – a AppStream.Relation instance.

Adds a AppStream.Relation to set a recommends or requires relation of component self on the item mentioned in the AppStream.Relation.

New in version 0.12.0.

add_release(release)
Parameters:release (AppStream.Release) – The AppStream.Release to add

Add an AppStream.Release to this component.

add_screenshot(sshot)
Parameters:sshot (AppStream.Screenshot) – The AppStream.Screenshot to add

Add an AppStream.Screenshot to this component.

add_suggested(suggested)
Parameters:suggested (AppStream.Suggested) – The AppStream.Suggested

Add an AppStream.Suggested to this component.

add_translation(tr)
Parameters:tr (AppStream.Translation) – an AppStream.Translation instance.

Assign an AppStream.Translation object describing the translation system used by this component.

New in version 0.9.2.

add_url(url_kind, url)
Parameters:

Adds some URL data to the component.

New in version 0.6.2.

get_active_locale()
Returns:the current active locale.
Return type:str

Get the current active locale for this component, which is used to get localized messages.

get_addons()
Returns:An array of AppStream.Component.
Return type:[AppStream.Component]

Returns a list of AppStream.Component objects which are addons extending this component in functionality.

This is the reverse of AppStream.Component.get_extends()

New in version 0.9.2.

get_agreement_by_kind(kind)
Parameters:kind (AppStream.AgreementKind) – an agreement kind, e.g. AppStream.AgreementKind.EULA
Returns:a AppStream.Agreement or None for not found
Return type:AppStream.Agreement or None

Gets an agreement the component has specified for the particular kind.

New in version 0.12.1.

get_bundle(bundle_kind)
Parameters:bundle_kind (AppStream.BundleKind) – the bundle kind, e.g. AppStream.BundleKind.LIMBA.
Returns:An AppStream.Bundle, or None if not set.
Return type:AppStream.Bundle or None

Gets a bundle identifier string.

New in version 0.8.0.

get_bundles()
Returns:A list of AppStream.Bundle.
Return type:[AppStream.Bundle]

Get a list of all software bundles associated with this component.

New in version 0.10.

get_categories()
Returns:String array of categories
Return type:[str]
get_compulsory_for_desktops()
Returns:A list of desktops where this component is compulsory
Return type:[str]
get_content_rating(kind)
Parameters:kind (str) – a ratings kind, e.g. “oars-1.0”
Returns:a AppStream.ContentRating or None if not found
Return type:AppStream.ContentRating or None

Gets a content ratings of a specific type that are defined for this component.

New in version 0.11.0.

get_content_ratings()
Returns:an array
Return type:[AppStream.ContentRating]

Gets all content ratings defined for this software.

New in version 0.11.0.

get_context()
Returns:the associated AppStream.Context or None
Return type:AppStream.Context or None

Get the AppStream.Context associated with this component. This function may return None if no context is set (which will be the case if the component was not loaded from a file or cache but constructed in memory).

New in version 0.11.2.

get_custom()
Returns:Hash table of custom user defined data fields.
Return type:{object: object}

New in version 0.10.5.

get_custom_value(key)
Parameters:key (str) – Field name.
Return type:str

Retrieve value for a custom data entry with the given key.

New in version 0.10.5.

get_data_id()
Returns:the unique session-specific identifier.
Return type:str

Get a unique identifier for this metadata set. This unique ID is only valid for the current session, as opposed to the AppStream ID which uniquely identifies a software component.

The format of the unique id usually is: %{scope}/%{origin}/%{distribution_system}/%{appstream_id}

For example: system/os/package/org.example.FooBar

get_description()
Returns:the description.
Return type:str

Get the localized long description of this component.

get_desktop_id()
Returns:The desktop file id.
Return type:str

Get the Desktop Entry ID for this component, if it is of type “desktop-application”. For most desktop-application components, this is the name of the .desktop file.

Refer to https://specifications.freedesktop.org/desktop-entry-spec/latest/ape.html for more information.

New in version 0.9.8.

Deprecated since version 0.11.0: Replaced by AppStream.Launchable and AppStream.Component.get_launchable

get_developer_name()
Returns:the developer name.
Return type:str

Get the component’s developer or development team name.

get_extends()
Returns:A GLib.PtrArray or None if not set.
Return type:[str] or None

Returns a string list of IDs of components which are extended by this addon.

See AppStream.Component.get_extends() for the reverse.

New in version 0.7.0.

get_icon_by_size(width, height)
Parameters:
  • width (int) – The icon width in pixels.
  • height (int) – the icon height in pixels.
Returns:

An icon matching the given width/height, or None if not found.

Return type:

AppStream.Icon or None

Gets an icon matching the size constraints. The icons are not filtered by type, and the first icon which matches the size is returned. If you want more control over which icons you use for displaying, use the AppStream.Component.get_icons() function to get a list of all icons.

Note that this function is not HiDPI aware! It will never return an icon with a scaling factor > 1.

get_icons()
Returns:A GLib.PtrArray of all icons for this component.
Return type:[AppStream.Icon]
get_id()
Returns:the unique AppStream identifier.
Return type:str

Get the unique AppStream identifier for this component. This ID is unique for the described component, but does not uniquely identify the metadata set.

For a unique ID for this metadata set in the current session, use AppStream.Component.get_data_id()

get_keywords()
Returns:String array of keywords
Return type:[str]
get_keywords_table()
Returns:Hash table locale->keyword arrays
Return type:{object: object}

Retrieve the internal hash table mapping languages to keword arrays.

get_kind()
Returns:the kind of #this.
Return type:AppStream.ComponentKind

Returns the AppStream.ComponentKind of this component.

get_language(locale)
Parameters:locale (str or None) – the locale, or None. e.g. “en_GB”
Returns:a percentage value, -1 if locale was not found
Return type:int

Gets the translation coverage in percent for a specific locale

New in version 0.7.0.

get_languages()
Returns:list of locales
Return type:[str]

Get a list of all languages.

New in version 0.7.0.

get_launchable(kind)
Parameters:kind (AppStream.LaunchableKind) – a launch kind, e.g. AppStream.LaunchableKind.DESKTOP_ID
Returns:a AppStream.Launchable or None if not found
Return type:AppStream.Launchable or None

Gets a AppStream.Launchable of a specific type that contains launchable entries for this component.

New in version 0.11.0.

get_launchables()
Returns:an array
Return type:[AppStream.Launchable]

New in version 0.11.0.

get_merge_kind()
Returns:the AppStream.MergeKind of this component.
Return type:AppStream.MergeKind

Get the merge method which should apply to duplicate components with this ID.

New in version 0.9.8.

get_metadata_license()
Returns:the license.
Return type:str

The license the metadata iself is subjected to.

get_name()
Returns:the name.
Return type:str

A human-readable name for this component.

get_name_table()
Returns:locale->names map
Return type:{object: object}

Get the internal locale to component name mapping table.

get_name_variant_suffix()
Returns:the variant suffix
Return type:str

Get variant suffix for the component name (only to be displayed if two components have the same name).

New in version 0.12.10.

get_origin()
Return type:str
get_pkgname()
Returns:String array of package names
Return type:str

Get the first package name of the list of packages that need to be installed for this component to be present on the system. Since most components consist of only one package, this is safe to use for about 90% of all cases.

However, to support a component fully, please use AppStream.Component.get_pkgnames() for getting all packages that need to be installed, and use this method only to e.g. get the main package to perform a quick “is it installed?” check.

get_pkgnames()
Returns:String array of package names
Return type:[str]

Get a list of package names which this component consists of. This usually is just one package name.

get_project_group()
Returns:the project group.
Return type:str

Get the component’s project group.

get_project_license()
Returns:the license.
Return type:str

Get the license of the project this component belongs to.

get_provided()
Returns:A list of AppStream.Provided objects.
Return type:[AppStream.Provided]

Get a list of AppStream.Provided objects associated with this component.

get_provided_for_kind(kind)
Parameters:kind (AppStream.ProvidedKind) – kind of the provided item, e.g. %AS_PROVIDED_KIND_MIMETYPE
Returns:AppStream.Provided containing the items this component provides, or None.
Return type:AppStream.Provided or None

Get an AppStream.Provided object for the given interface type, containing information about the public interfaces (mimetypes, firmware, DBus services, …) this component provides.

get_recommends()
Returns:an array
Return type:[AppStream.Relation]

Get an array of items that are recommended by this component.

New in version 0.12.0.

get_releases()
Returns:A list of releases
Return type:[AppStream.Release]

Get an array of the AppStream.Release items this component provides.

get_requires()
Returns:an array
Return type:[AppStream.Relation]

Get an array of items that are required by this component.

New in version 0.12.0.

get_scope()
Returns:the AppStream.ComponentScope of this component.
Return type:AppStream.ComponentScope

New in version 0.10.2.

get_screenshots()
Returns:an array of AppStream.Screenshot instances
Return type:[AppStream.Screenshot]

Get a list of associated screenshots.

get_search_tokens()
Returns:The string search tokens
Return type:[str]

Returns all search tokens for this component.

New in version 0.9.7.

get_sort_score()
Return type:int

Returns the sorting priority of this component.

This will only return a valid value if this component was the result of or involved in a search operation which returned sorted results. In most cases you will not need to access this value explicitly, as all results of search operations in AppStream are already sorted from best match to worst.

The returned value is an arbitrary integer value, valid only for the search terms involved in the search operation that yielded this component as a result.

New in version 0.12.11.

get_source_pkgname()
Returns:the source package name.
Return type:str
get_suggested()
Returns:an array of AppStream.Suggested instances
Return type:[AppStream.Suggested]

Get a list of associated suggestions.

get_summary()
Returns:the summary.
Return type:str

Get a short description of this component.

get_summary_table()
Returns:locale->summary map
Return type:{object: object}

Get the internal locale to component summary mapping table.

get_translations()
Returns:An array of AppStream.Translation objects.
Return type:[AppStream.Translation]

Get a GLib.PtrArray of AppStream.Translation objects describing the translation systems and translation-ids (e.g. Gettext domains) used by this software component.

Only set for metainfo files.

New in version 0.9.2.

get_url(url_kind)
Parameters:url_kind (AppStream.UrlKind) – the URL kind, e.g. AppStream.UrlKind.HOMEPAGE.
Returns:string, or None if unset
Return type:str or None

Gets a URL.

New in version 0.6.2.

get_value_flags()
Returns:The AppStream.ValueFlags that are set on self.
Return type:AppStream.ValueFlags
has_bundle()
Returns:True if this component has a bundle associated.
Return type:bool
has_category(category)
Parameters:category (str) – the specified category to check
Returns:True if the component is in the specified category.
Return type:bool

Check if component is in the specified category.

insert_custom_value(key, value)
Parameters:
  • key (str) – Key name.
  • value (str) – A string value.
Returns:

True if the key did not exist yet.

Return type:

bool

Add a key and value pair to the custom data table.

New in version 0.10.5.

is_compulsory_for_desktop(desktop)
Parameters:desktop (str) – the desktop-id to test for
Returns:True if compulsory, False otherwise.
Return type:bool

Check if this component is compulsory for the given desktop.

is_ignored()
Returns:Whether this component’s metadata should be ignored.
Return type:bool

New in version 0.10.2.

is_member_of_category(category)
Parameters:category (AppStream.Category) – The category to test.
Return type:bool

Test if the component self is a member of category category.

is_valid()
Returns:True if the component data was validated successfully.
Return type:bool

Check if the essential properties of this Component are populated with useful data.

load_from_xml_data(context, data)
Parameters:
Raises:

GLib.Error

Returns:

True on success.

Return type:

bool

Load metadata for this component from an XML string. You normally do not want to use this method directly and instead use the more convenient API of AppStream.Metadata to create and update components.

New in version 0.12.10.

search_matches(term)
Parameters:term (str) – the search term.
Returns:a match scrore, where 0 is no match and 100 is the best match.
Return type:int

Searches component data for a specific keyword.

New in version 0.9.7.

search_matches_all(terms)
Parameters:terms (str) – the search terms.
Returns:a match score, where 0 is no match and larger numbers are better matches.
Return type:int

Searches component data for all the specific keywords.

New in version 0.9.8.

set_active_locale(locale)
Parameters:locale (str or None) – the locale, or None. e.g. “en_GB”

Set the current active locale for this component, which is used to get localized messages. If the AppStream.Component was fetched from a localized database, usually only one locale is available.

set_compulsory_for_desktop(desktop)
Parameters:desktop (str) – The name of the desktop.

Mark this component to be compulsory for the specified desktop environment.

set_data_id(value)
Parameters:value (str) – the unique session-specific identifier.

Set the session-specific unique metadata identifier for this component. If two components have a different data_id but the same ID, they will be treated as independent sets of metadata describing the same component type.

set_description(value, locale)
Parameters:
  • value (str) – The long description
  • locale (str or None) – The locale the used for this value, or None to use the current active one.

Set long description for this component.

set_developer_name(value, locale)
Parameters:
  • value (str) – the developer or developer team name
  • locale (str or None) – the locale, or None. e.g. “en_GB”

Set the the component’s developer or development team name.

set_id(value)
Parameters:value (str) – the unique identifier.

Set the AppStream identifier for this component.

set_keywords(value, locale)
Parameters:
  • value ([str]) – String-array of keywords
  • locale (str or None) – Locale of the values, or None to use current locale.

Set keywords for this component.

set_kind(value)
Parameters:value (AppStream.ComponentKind) – the AppStream.ComponentKind.

Sets the AppStream.ComponentKind of this component.

set_merge_kind(kind)
Parameters:kind (AppStream.MergeKind) – the AppStream.MergeKind.

Sets the AppStream.MergeKind for this component.

New in version 0.9.8.

set_metadata_license(value)
Parameters:value (str) – the metadata license.

Set the license this metadata is licensed under.

set_name(value, locale)
Parameters:
  • value (str) – The name
  • locale (str or None) – The locale the used for this value, or None to use the current active one.

Set a human-readable name for this component.

set_name_variant_suffix(value, locale)
Parameters:
  • value (str) – the developer or developer team name
  • locale (str or None) – the locale, or None. e.g. “en_GB”

Set a variant suffix for the component name (only to be displayed if components have the same name).

New in version 0.12.10.

set_origin(origin)
Parameters:origin (str) – the origin.
set_pkgnames(packages)
Parameters:packages ([str]) –

Set a list of package names this component consists of. (This should usually be just one package name)

set_project_group(value)
Parameters:value (str) – the project group.

Set the component’s project group.

set_project_license(value)
Parameters:value (str) – the project license.

Set the project license.

set_scope(scope)
Parameters:scope (AppStream.ComponentScope) – the AppStream.ComponentKind.

Sets the AppStream.ComponentScope of this component.

set_sort_score(score)
Parameters:score (int) – the given sorting score

Sets the sorting score of this component.

New in version 0.9.8.

set_source_pkgname(spkgname)
Parameters:spkgname (str) – the source package name.
set_summary(value, locale)
Parameters:
  • value (str) – The summary
  • locale (str or None) – The locale the used for this value, or None to use the current active one.

Set a short description for this component.

set_value_flags(flags)
Parameters:flags (AppStream.ValueFlags) – AppStream.ValueFlags to set on self.
to_string()
Returns:A descriptive string
Return type:str

Returns a string identifying this component. (useful for debugging)

to_xml_data(context)
Parameters:context (AppStream.Context) – an AppStream.Context instance.
Raises:GLib.Error
Returns:True on success.
Return type:str

Serialize this component into an XML string. You normally do not want to use this method directly and instead use the more convenient API of AppStream.Metadata to serialize components.

New in version 0.12.10.

Property Details

AppStream.Component.props.categories
Name:categories
Type:GLib.PtrArray
Default Value:None
Flags:READABLE

string array of categories

AppStream.Component.props.description
Name:description
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the description

AppStream.Component.props.developer_name
Name:developer-name
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the developer name

AppStream.Component.props.icons
Name:icons
Type:int
Default Value:None
Flags:READABLE

hash map of icon urls and sizes

AppStream.Component.props.id
Name:id
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the unique identifier

AppStream.Component.props.keywords
Name:keywords
Type:[str]
Default Value:[]
Flags:READABLE, WRITABLE

string array of keywords

AppStream.Component.props.kind
Name:kind
Type:AppStream.ComponentKind
Default Value:AppStream.ComponentKind.UNKNOWN
Flags:READABLE, WRITABLE

the AppStream.ComponentKind of this component

AppStream.Component.props.name
Name:name
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the name

AppStream.Component.props.pkgnames
Name:pkgnames
Type:[str]
Default Value:[]
Flags:READABLE, WRITABLE

string array of packages name

AppStream.Component.props.project_group
Name:project-group
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the project group

AppStream.Component.props.project_license
Name:project-license
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the project license

AppStream.Component.props.screenshots
Name:screenshots
Type:GLib.PtrArray
Default Value:None
Flags:READABLE

An array of AppStream.Screenshot instances

AppStream.Component.props.summary
Name:summary
Type:str
Default Value:None
Flags:READABLE, WRITABLE

the summary

AppStream.Component.props.urls
Name:urls
Type:GLib.HashTable
Default Value:None
Flags:READABLE

the urls associated with this component