Settings, User Data and Files¶
Applications access three kinds of information from the user’s account: application settings, user data and files. These different kinds of data are used for different purposes, though sometimes those purposes may overlap with each other.
We describe each of these kinds of information before providing suggestions for where to store user and application data.
Settings¶
Application settings hold information about the way the user has configured an application, such as the font size, window size or theme. This information typically describes how the application itself functions.
GNOME applications access their settings using the Gio.Settings class. This stores data in a suitable directory located within the user’s home directory. The precise location of this directory can be found using the GLib.get_user_config_dir() function but most applications can simply use the Gio.Settings class to read and write settings without having to worry about where they are located.
Applications distributed as flatpaks require permissions to be granted in order to access the user’s settings for that application. The settings for an application is only available to that application, so one application cannot read or write the settings of another. See the Application Permissions guide for details about permissions.
User Data¶
Some applications prefer to store data that the user has created or imported in a special data directory set aside for the application. This frees the user from having to decide where the data should be stored. Access to a suitable data directory is obtained using the GLib.get_user_data_dir() function, as in the Simple Weather example:
def do_startup(self):
Gtk.Application.do_startup(self)
self.data_subdir = os.path.join(GLib.get_user_data_dir(),
'com.example.simple_weather')
Files are stored in a subdirectory of the general user data directory.
Simple data can be accessed using keyfiles that record pieces of information as key-value pairs. The GLib.KeyFile class is used to read and write keyfiles.
More complex and larger data is also stored in the user data directory by applications where it does not necessarily make sense for the user to decide where their data should be stored. These applications function like appliances, hiding the details of data storage, or using different ways to refer to user data than applications using the traditional Open, Load and Save actions.
Applications distributed as flatpaks do not need to request permissions in order to access user data stored in a data directory that has been set aside for that purpose.
Files¶
Traditional applications can load and save files from arbitrary directories as long as the user has permission to access them. For types of files that can be opened by many different applications, such as music and video files, it is common to find that directories have been set aside for these files in the user’s home directory. The XDG Base Directory Specification describes how these directories are organized.
Some applications rely on finding data files in these standard locations, though they may also allow the user to select files from elsewhere, like traditional applications. These obtain the directory to access via the GLib.get_user_special_dir() function, passing one of the Glib.UserDirectory values given in the table below.
| Directory | Contents |
|---|---|
DIRECTORY_DOCUMENTS |
Documents, such as text or word processing files |
DIRECTORY_DOWNLOAD |
Files downloaded by applications |
DIRECTORY_MUSIC |
Music files |
DIRECTORY_PICTURES |
Pictures and photographs |
DIRECTORY_VIDEOS |
Movies and videos |
The photographs and videos taken by the camera are stored in the directories represented by DIRECTORY_PICTURES and DIRECTORY_VIDEOS respectively.
A more complete list of directories that can be accessed is provided in the XDG Base Directory Specification document.
An application distributed as a flatpak needs to declare permissions in the finish-args entry of its manifest to be able to access these directories. The following table shows which permission corresponds to each directory, as described by the table above.
| Directory | Flatpak Permission |
|---|---|
DIRECTORY_DOCUMENTS |
--xdg-documents |
DIRECTORY_DOWNLOAD |
--xdg-download |
DIRECTORY_MUSIC |
--xdg-music |
DIRECTORY_PICTURES |
--xdg-pictures |
DIRECTORY_VIDEOS |
--xdg-videos |
See the Application Permissions for a more complete description of permissions, and consult the Sandbox Permissions section of the Flatpak documentation for a more extensive list of permissions.
Caches¶
Some applications benefit from having a temporary place to store data, either because it is costly to create or retrieve it, or just because it saves time to access it locally. Data like this can be stored in an application-specific cache directory.
Access to a suitable cache directory is obtained using the GLib.get_user_cache_dir() function. Each application stores cached data in its own subdirectory of the cache directory.
Caches are temporary and can be deleted at any time. As a result, applications should not rely on the availability of cached data, especially from previous running sessions.
Where to Store Data¶
Depending on the application, it can sometimes be difficult to determine whether certain pieces of information should be stored in the user data directory or in the application’s settings.
Application settings and user data differ from each other in what they describe. Application settings change how the application behaves. User data is processed by the application to produce something for the user and is, in theory, separate from the application itself. For example, an image viewing application could store images in the user data directory, thumbnail images in a cache directory, and the preferred size of the thumbnails in its settings.
When deciding where to store a piece of information, it may also help to consider how the application will function if the settings are reset to default values or if the user data or cached data is deleted. For example, if resetting the settings causes critical information to be lost, perhaps that information should be stored in the user data directory. Similarly, if removing all user data causes user preferences to be lost then those preferences may need to be kept in the application’s settings.