:right-sidebar: True KeyFile =================================================================== .. currentmodule:: gi.repository.GLib .. class:: KeyFile(**kwargs) :no-contents-entry: :Constructors: :: new() -> GLib.KeyFile 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: .. method:: 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() -> 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) -> 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) -> 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: ~typing.Sequence[str], flags: ~gi.repository.GLib.KeyFileFlags) -> 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: ~typing.Sequence[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: ~typing.Sequence[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: ~typing.Sequence[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: ~typing.Sequence[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: ~typing.Sequence[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() -> 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