Implement common functionality for an app.

An app is composed of components which actually performs various tasks. App itself delegates tasks for individual components. Applications can show a variation in their behavior by choosing which components to have and by customizing the components themselves.

‘app_id’ property of the app must be a string that is a globally unique ID. This is typically also the name of the python module handling the app. So, it should be all lower-case English alphabet and digits without any special characters.

‘can_be_disabled’ is a boolean indicating whether an app can be disabled by the user. Enable/disable button for this app will not be shown. Default value is True, so the app can be disabled.

‘locked’ is a boolean indicating whether the user can perform operations on the app. This flag is currently set during backup and restore operations but UI changes are currently not implemented.

class SetupState(value)[source]

Various states of app being setup.


Build the app by adding components.

App may be built just for the purpose for querying. For example, when querying the list of package dependencies of essential apps, an app is minimally constructed under a read-only environment for querying from a specific component. So, this operation should have no side-effects such connecting to signals, running configuration corrections and scheduling operations.


Add a component to an app.


Run diagnostics and return results.

Return value must be a list of results. Each result is a two-tuple with first value as user visible description of the test followed by the result. The test result is a string enumeration from ‘failed’, ‘passed’, ‘error’ and ‘warning’.

Results are typically collected by diagnosing each component of the app and then supplementing the results with any app level diagnostic tests.

Also see has_diagnostics().


Enable all the components of the app.


Enable all the components of the app.

classmethod get(app_id)[source]

Return an app with given ID.


Return a component given the component’s ID.


Return all components of a given type.


Return whether the app is not setup or needs upgrade.


Return the setup version of the app.


Return whether at least one diagnostic test is implemented.

If this method returns True, a button or menu item is shown to the user to run diagnostics on this app. When the action is selected by the user, the diagnose() method is called and the results are presented to the user. Additionally collection of diagnostic results of all apps can be obtained by the user from the Diagnostics module in System section.

If a component of this app implements a diagnostic test, this method returns True.

Further, if a subclass of App overrides the diagnose() method, it is assumed that it is for implementing diagnostic tests and this method returns True for such an app. Override this method if this default behavior does not fit the needs.

property info

Return the information component of the app.

It is mandatory to have one Info component in every app to provide basic information about the app. Trying to access this property without having the Info component will result in a KeyError exception being raised. The lookup for the Info component is performed using the auto-generated component_id assigned to the Info component based on the app_id.


Return whether all the leader components are enabled.

Return True when there are no leader components.

classmethod list()[source]

Return a list of all apps.


Return whether the app needs to be setup.

A simple shortcut for get_setup_state() == NEEDS_SETUP


Perform post initialization operations.

Additional initialization operations such as connecting to signals, running configuration corrections and scheduling operations should be done in this method rather than in __init__().


Remove a component from the app.


Update the status of all follower components.

Do not query or update the status of the leader components.

set_setup_version(version: int)None[source]

Set the app’s setup version.


Install and configure the app and its components.