:right-sidebar: True KeyFile =================================================================== .. currentmodule:: gi.repository.GLib .. class:: KeyFile(**kwargs) :no-contents-entry: ``GKeyFile`` parses .ini-like config files. ``GKeyFile`` lets you parse, edit or create files containing groups of key-value pairs, which we call "key files" for lack of a better name. Several freedesktop.org specifications use key files now, e.g the `Desktop Entry Specification `__ and the `Icon Theme Specification `__\. The syntax of key files is described in detail in the `Desktop Entry Specification `__\, here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments. .. code-block:: txt :dedent: # this is just an example # there can be comments before the first group [First Group] Name=Key File Example\tthis value shows\nescaping # localized strings are stored in multiple key-value pairs Welcome=Hello Welcome[de]=Hallo Welcome[fr_FR]=Bonjour Welcome[it]=Ciao [Another Group] Numbers=2;20;-200;0 Booleans=true;false;true;true Lines beginning with a '#' and blank lines are considered comments. Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group. Key-value pairs generally have the form ``key=value``\, with the exception of localized strings, which have the form ``key[locale]=value``\, with a locale identifier of the form ``lang_COUNTRY@MODIFIER`` where ``COUNTRY`` and ``MODIFIER`` are optional. Space before and after the '=' character are ignored. Newline, tab, carriage return and backslash characters in value are escaped as ``\n``\, ``\t``\, ``\r``\, and ``\\\\``\, respectively. To preserve leading spaces in values, these can also be escaped as ``\s``\. Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, typically ';' or ','. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash. This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences: - .ini files use the ';' character to begin comments, key files use the '#' character. - Key files do not allow for ungrouped keys meaning only comments can precede the first group. - Key files are always encoded in UTF-8. - Key and Group names are case-sensitive. For example, a group called [GROUP] is a different from [group]. - .ini files don't have a strongly typed boolean entry type, they only have GetProfileInt(). In key files, only true and false (in lower case) are allowed. Note that in contrast to the `Desktop Entry Specification `__\, groups in key files may contain the same key multiple times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged together. Another difference is that keys and group names in key files are not restricted to ASCII characters. Here is an example of loading a key file and reading a value: .. code-block:: c :dedent: g_autoptr(GError) error = NULL; g_autoptr(GKeyFile) key_file = g_key_file_new (); if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) { if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) g_warning ("Error loading key file: %s", error->message); return; } g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); if (val == NULL && !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) { g_warning ("Error finding key in key file: %s", error->message); return; } else if (val == NULL) { // Fall back to a default value. val = g_strdup ("default-value"); } Here is an example of creating and saving a key file: .. code-block:: c :dedent: g_autoptr(GKeyFile) key_file = g_key_file_new (); const gchar *val = …; g_autoptr(GError) error = NULL; g_key_file_set_string (key_file, "Group Name", "SomeKey", val); // Save as a file. if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) { g_warning ("Error saving key file: %s", error->message); return; } // Or store to a GBytes for use elsewhere. gsize data_len; g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); if (data == NULL) { g_warning ("Error saving key file: %s", error->message); return; } g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); Constructors ------------ .. rst-class:: interim-class .. class:: KeyFile :no-index: .. classmethod:: new() -> ~gi.repository.GLib.KeyFile Creates a new empty :obj:`~gi.repository.GLib.KeyFile` object. Use :func:`~gi.repository.GLib.KeyFile.load_from_file`, :func:`~gi.repository.GLib.KeyFile.load_from_data`, :func:`~gi.repository.GLib.KeyFile.load_from_dirs` or :func:`~gi.repository.GLib.KeyFile.load_from_data_dirs` to read an existing key file. .. versionadded:: 2.6 Methods ------- .. rst-class:: interim-class .. class:: KeyFile :no-index: .. classmethod:: error_quark() -> int .. method:: get_boolean(group_name: str, key: str) -> bool Returns the value associated with ``key`` under ``group_name`` as a boolean. If ``key`` cannot be found then :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. Likewise, if the value associated with ``key`` cannot be interpreted as a boolean then :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.INVALID_VALUE`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: get_boolean_list(group_name: str, key: str) -> list[bool] Returns the values associated with ``key`` under ``group_name`` as booleans. If ``key`` cannot be found then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. Likewise, if the values associated with ``key`` cannot be interpreted as booleans then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.INVALID_VALUE`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: get_comment(group_name: str | None = None, key: str | None = None) -> str Retrieves a comment above ``key`` from ``group_name``\. If ``key`` is :const:`None` then ``comment`` will be read from above ``group_name``\. If both ``key`` and ``group_name`` are :const:`None`, then ``comment`` will be read from above the first group in the file. Note that the returned string does not include the '#' comment markers, but does include any whitespace after them (on each line). It includes the line breaks between lines, but does not include the final line break. .. versionadded:: 2.6 :param group_name: a group name, or :const:`None` :param key: a key .. method:: get_double(group_name: str, key: str) -> float Returns the value associated with ``key`` under ``group_name`` as a double. If ``group_name`` is :const:`None`, the start_group is used. If ``key`` cannot be found then 0.0 is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. Likewise, if the value associated with ``key`` cannot be interpreted as a double then 0.0 is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.INVALID_VALUE`. .. versionadded:: 2.12 :param group_name: a group name :param key: a key .. method:: get_double_list(group_name: str, key: str) -> list[float] Returns the values associated with ``key`` under ``group_name`` as doubles. If ``key`` cannot be found then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. Likewise, if the values associated with ``key`` cannot be interpreted as doubles then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.INVALID_VALUE`. .. versionadded:: 2.12 :param group_name: a group name :param key: a key .. method:: get_groups() -> ~typing.Tuple[list[str], int] Returns all groups in the key file loaded with ``key_file``\. The array of returned groups will be :const:`None`-terminated, so ``length`` may optionally be :const:`None`. .. versionadded:: 2.6 .. method:: get_int64(group_name: str, key: str) -> int Returns the value associated with ``key`` under ``group_name`` as a signed 64-bit integer. This is similar to :func:`~gi.repository.GLib.KeyFile.get_integer` but can return 64-bit results without truncation. .. versionadded:: 2.26 :param group_name: a non-:const:`None` group name :param key: a non-:const:`None` key .. method:: get_integer(group_name: str, key: str) -> int Returns the value associated with ``key`` under ``group_name`` as an integer. If ``key`` cannot be found then 0 is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. Likewise, if the value associated with ``key`` cannot be interpreted as an integer, or is out of range for a :obj:`int`, then 0 is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.INVALID_VALUE`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: get_integer_list(group_name: str, key: str) -> list[int] Returns the values associated with ``key`` under ``group_name`` as integers. If ``key`` cannot be found then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. Likewise, if the values associated with ``key`` cannot be interpreted as integers, or are out of range for :obj:`int`, then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.INVALID_VALUE`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: get_keys(group_name: str) -> ~typing.Tuple[list[str], int] Returns all keys for the group name ``group_name``\. The array of returned keys will be :const:`None`-terminated, so ``length`` may optionally be :const:`None`. In the event that the ``group_name`` cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.GROUP_NOT_FOUND`. .. versionadded:: 2.6 :param group_name: a group name .. method:: get_locale_for_key(group_name: str, key: str, locale: str | None = None) -> str | None Returns the actual locale which the result of :func:`~gi.repository.GLib.KeyFile.get_locale_string` or :func:`~gi.repository.GLib.KeyFile.get_locale_string_list` came from. If calling :func:`~gi.repository.GLib.KeyFile.get_locale_string` or :func:`~gi.repository.GLib.KeyFile.get_locale_string_list` with exactly the same ``key_file``\, ``group_name``\, ``key`` and ``locale``\, the result of those functions will have originally been tagged with the locale that is the result of this function. .. versionadded:: 2.56 :param group_name: a group name :param key: a key :param locale: a locale identifier or :const:`None` .. method:: get_locale_string(group_name: str, key: str, locale: str | None = None) -> str Returns the value associated with ``key`` under ``group_name`` translated in the given ``locale`` if available. If ``locale`` is :const:`None` then the current locale is assumed. If ``locale`` is to be non-:const:`None`, or if the current locale will change over the lifetime of the :obj:`~gi.repository.GLib.KeyFile`\, it must be loaded with :const:`~gi.repository.GLib.KeyFileFlags.KEEP_TRANSLATIONS` in order to load strings for all locales. If ``key`` cannot be found then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. If the value associated with ``key`` cannot be interpreted or no suitable translation can be found then the untranslated value is returned. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param locale: a locale identifier or :const:`None` .. method:: get_locale_string_list(group_name: str, key: str, locale: str | None = None) -> list[str] Returns the values associated with ``key`` under ``group_name`` translated in the given ``locale`` if available. If ``locale`` is :const:`None` then the current locale is assumed. If ``locale`` is to be non-:const:`None`, or if the current locale will change over the lifetime of the :obj:`~gi.repository.GLib.KeyFile`\, it must be loaded with :const:`~gi.repository.GLib.KeyFileFlags.KEEP_TRANSLATIONS` in order to load strings for all locales. If ``key`` cannot be found then :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. If the values associated with ``key`` cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The returned array is :const:`None`-terminated, so ``length`` may optionally be :const:`None`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param locale: a locale identifier or :const:`None` .. method:: get_start_group() -> str | None Returns the name of the start group of the file. .. versionadded:: 2.6 .. method:: get_string(group_name: str, key: str) -> str Returns the string value associated with ``key`` under ``group_name``\. Unlike :func:`~gi.repository.GLib.KeyFile.get_value`, this function handles escape sequences like \s. In the event the key cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. In the event that the ``group_name`` cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.GROUP_NOT_FOUND`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: get_string_list(group_name: str, key: str) -> list[str] Returns the values associated with ``key`` under ``group_name``\. In the event the key cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. In the event that the ``group_name`` cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.GROUP_NOT_FOUND`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: get_uint64(group_name: str, key: str) -> int Returns the value associated with ``key`` under ``group_name`` as an unsigned 64-bit integer. This is similar to :func:`~gi.repository.GLib.KeyFile.get_integer` but can return large positive results without truncation. .. versionadded:: 2.26 :param group_name: a non-:const:`None` group name :param key: a non-:const:`None` key .. method:: get_value(group_name: str, key: str) -> str Returns the raw value associated with ``key`` under ``group_name``\. Use :func:`~gi.repository.GLib.KeyFile.get_string` to retrieve an unescaped UTF-8 string. In the event the key cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.KEY_NOT_FOUND`. In the event that the ``group_name`` cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.KeyFileError.GROUP_NOT_FOUND`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key .. method:: has_group(group_name: str) -> bool Looks whether the key file has the group ``group_name``\. .. versionadded:: 2.6 :param group_name: a group name .. method:: load_from_bytes(bytes: ~gi.repository.GLib.Bytes, flags: ~gi.repository.GLib.KeyFileFlags) -> bool Loads a key file from the data in ``bytes`` into an empty :obj:`~gi.repository.GLib.KeyFile` structure. If the object cannot be created then %error is set to a ``GKeyFileError``. .. versionadded:: 2.50 :param bytes: a :obj:`~gi.repository.GLib.Bytes` :param flags: flags from :obj:`~gi.repository.GLib.KeyFileFlags` .. method:: load_from_data(data: str, length: int, flags: ~gi.repository.GLib.KeyFileFlags) -> bool Loads a key file from memory into an empty :obj:`~gi.repository.GLib.KeyFile` structure. If the object cannot be created then %error is set to a ``GKeyFileError``. .. versionadded:: 2.6 :param data: key file loaded in memory :param length: the length of ``data`` in bytes (or (gsize)-1 if data is nul-terminated) :param flags: flags from :obj:`~gi.repository.GLib.KeyFileFlags` .. method:: load_from_data_dirs(file: str, flags: ~gi.repository.GLib.KeyFileFlags) -> ~typing.Tuple[bool, str] This function looks for a key file named ``file`` in the paths returned from :func:`~gi.repository.GLib.get_user_data_dir` and :func:`~gi.repository.GLib.get_system_data_dirs`, loads the file into ``key_file`` and returns the file's full path in ``full_path``\. If the file could not be loaded then an %error is set to either a :obj:`~gi.repository.GLib.FileError` or ``GKeyFileError``. .. versionadded:: 2.6 :param file: a relative path to a filename to open and parse :param flags: flags from :obj:`~gi.repository.GLib.KeyFileFlags` .. method:: load_from_dirs(file: str, search_dirs: list[str], flags: ~gi.repository.GLib.KeyFileFlags) -> ~typing.Tuple[bool, str] This function looks for a key file named ``file`` in the paths specified in ``search_dirs``\, loads the file into ``key_file`` and returns the file's full path in ``full_path``\. If the file could not be found in any of the ``search_dirs``\, :const:`~gi.repository.GLib.KeyFileError.NOT_FOUND` is returned. If the file is found but the OS returns an error when opening or reading the file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a %G_KEY_FILE_ERROR is returned. .. versionadded:: 2.14 :param file: a relative path to a filename to open and parse :param search_dirs: :const:`None`-terminated array of directories to search :param flags: flags from :obj:`~gi.repository.GLib.KeyFileFlags` .. method:: load_from_file(file: str, flags: ~gi.repository.GLib.KeyFileFlags) -> bool Loads a key file into an empty :obj:`~gi.repository.GLib.KeyFile` structure. If the OS returns an error when opening or reading the file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a %G_KEY_FILE_ERROR is returned. This function will never return a :const:`~gi.repository.GLib.KeyFileError.NOT_FOUND` error. If the ``file`` is not found, :const:`~gi.repository.GLib.FileError.NOENT` is returned. .. versionadded:: 2.6 :param file: the path of a filename to load, in the GLib filename encoding :param flags: flags from :obj:`~gi.repository.GLib.KeyFileFlags` .. method:: remove_comment(group_name: str | None = None, key: str | None = None) -> bool Removes a comment above ``key`` from ``group_name``\. If ``key`` is :const:`None` then ``comment`` will be removed above ``group_name``\. If both ``key`` and ``group_name`` are :const:`None`, then ``comment`` will be removed above the first group in the file. .. versionadded:: 2.6 :param group_name: a group name, or :const:`None` :param key: a key .. method:: remove_group(group_name: str) -> bool Removes the specified group, ``group_name``\, from the key file. .. versionadded:: 2.6 :param group_name: a group name .. method:: remove_key(group_name: str, key: str) -> bool Removes ``key`` in ``group_name`` from the key file. .. versionadded:: 2.6 :param group_name: a group name :param key: a key name to remove .. method:: save_to_file(filename: str) -> bool Writes the contents of ``key_file`` to ``filename`` using :func:`~gi.repository.GLib.file_set_contents`. If you need stricter guarantees about durability of the written file than are provided by :func:`~gi.repository.GLib.file_set_contents`, use :func:`~gi.repository.GLib.file_set_contents_full` with the return value of :func:`~gi.repository.GLib.KeyFile.to_data`. This function can fail for any of the reasons that :func:`~gi.repository.GLib.file_set_contents` may fail. .. versionadded:: 2.40 :param filename: the name of the file to write to .. method:: set_boolean(group_name: str, key: str, value: bool) -> None Associates a new boolean value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param value: :const:`True` or :const:`False` .. method:: set_boolean_list(group_name: str, key: str, list: list[bool]) -> None Associates a list of boolean values with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. If ``group_name`` is :const:`None`, the start_group is used. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param list: an array of boolean values .. method:: set_comment(group_name: str | None, key: str | None, comment: str) -> bool Places a comment above ``key`` from ``group_name``\. If ``key`` is :const:`None` then ``comment`` will be written above ``group_name``\. If both ``key`` and ``group_name`` are :const:`None`, then ``comment`` will be written above the first group in the file. Note that this function prepends a '#' comment marker to each line of ``comment``\. .. versionadded:: 2.6 :param group_name: a group name, or :const:`None` :param key: a key :param comment: a comment .. method:: set_double(group_name: str, key: str, value: float) -> None Associates a new double value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.12 :param group_name: a group name :param key: a key :param value: a double value .. method:: set_double_list(group_name: str, key: str, list: list[float]) -> None Associates a list of double values with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.12 :param group_name: a group name :param key: a key :param list: an array of double values .. method:: set_int64(group_name: str, key: str, value: int) -> None Associates a new integer value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.26 :param group_name: a group name :param key: a key :param value: an integer value .. method:: set_integer(group_name: str, key: str, value: int) -> None Associates a new integer value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param value: an integer value .. method:: set_integer_list(group_name: str, key: str, list: list[int]) -> None Associates a list of integer values with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param list: an array of integer values .. method:: set_list_separator(separator: int) -> None Sets the character which is used to separate values in lists. Typically ';' or ',' are used as separators. The default list separator is ';'. .. versionadded:: 2.6 :param separator: the separator .. method:: set_locale_string(group_name: str, key: str, locale: str, string: str) -> None Associates a string value for ``key`` and ``locale`` under ``group_name``\. If the translation for ``key`` cannot be found then it is created. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param locale: a locale identifier :param string: a string .. method:: set_locale_string_list(group_name: str, key: str, locale: str, list: list[str]) -> None Associates a list of string values for ``key`` and ``locale`` under ``group_name``\. If the translation for ``key`` cannot be found then it is created. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param locale: a locale identifier :param list: a :const:`None`-terminated array of locale string values .. method:: set_string(group_name: str, key: str, string: str) -> None Associates a new string value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. If ``group_name`` cannot be found then it is created. Unlike :func:`~gi.repository.GLib.KeyFile.set_value`, this function handles characters that need escaping, such as newlines. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param string: a string .. method:: set_string_list(group_name: str, key: str, list: list[str]) -> None Associates a list of string values for ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. If ``group_name`` cannot be found then it is created. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param list: an array of string values .. method:: set_uint64(group_name: str, key: str, value: int) -> None Associates a new integer value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. .. versionadded:: 2.26 :param group_name: a group name :param key: a key :param value: an integer value .. method:: set_value(group_name: str, key: str, value: str) -> None Associates a new value with ``key`` under ``group_name``\. If ``key`` cannot be found then it is created. If ``group_name`` cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use :func:`~gi.repository.GLib.KeyFile.set_string`. .. versionadded:: 2.6 :param group_name: a group name :param key: a key :param value: a string .. method:: to_data() -> ~typing.Tuple[str, int] This function outputs ``key_file`` as a string. Note that this function never reports an error, so it is safe to pass :const:`None` as ``error``\. .. versionadded:: 2.6