GLib.BookmarkFile¶

record (struct)

GBookmarkFile lets you parse, edit or create files containing bookmarks.

Bookmarks refer to a URI, along with some meta-data about the resource pointed by the URI like its MIME type, the application that is registering the bookmark and the icon that should be used to represent the bookmark. The data is stored using the Desktop Bookmark Specification.

The syntax of the bookmark files is described in detail inside the Desktop Bookmark Specification, here is a quick summary: bookmark files use a sub-class of the XML Bookmark Exchange Language specification, consisting of valid UTF-8 encoded XML, under the <xbel> root element; each bookmark is stored inside a <bookmark> element, using its URI: no relative paths can be used inside a bookmark file. The bookmark may have a user defined title and description, to be used instead of the URI. Under the <metadata> element, with its owner attribute set to http://freedesktop.org, is stored the meta-data about a resource pointed by its URI. The meta-data consists of the resource's MIME type; the applications that have registered a bookmark; the groups to which a bookmark belongs to; a visibility flag, used to set the bookmark as "private" to the applications and groups that has it registered; the URI and MIME type of an icon, to be used when displaying the bookmark inside a GUI.

Here is an example of a bookmark file: bookmarks.xbel

A bookmark file might contain more than one bookmark; each bookmark is accessed through its URI.

The important caveat of bookmark files is that when you add a new bookmark you must also add the application that is registering it, using BookmarkFile.add_application or BookmarkFile.set_application_info. If a bookmark has no applications then it won't be dumped when creating the on disk representation, using BookmarkFile.to_data or BookmarkFile.to_file.

Constructors¶

new¶

@classmethod
def new(cls) -> BookmarkFile

Creates a new empty BookmarkFile object.

Use BookmarkFile.load_from_file, BookmarkFile.load_from_data or BookmarkFile.load_from_data_dirs to read an existing bookmark file.

Methods¶

add_application¶

def add_application(self, uri: str, name: str | None = ..., exec: str | None = ...) -> None

Adds the application with name and exec to the list of applications that have registered a bookmark for uri into bookmark.

Every bookmark inside a BookmarkFile must have at least an application registered. Each application must provide a name, a command line useful for launching the bookmark, the number of times the bookmark has been registered by the application and the last time the application registered this bookmark.

If name is None, the name of the application will be the same returned by get_application_name; if exec is None, the command line will be a composition of the program name as returned by get_prgname and the "`u`" modifier, which will be expanded to the bookmark's URI.

This function will automatically take care of updating the registrations count and timestamping in case an application with the same name had already registered a bookmark for uri inside bookmark.

If no bookmark for uri is found, one is created.

Parameters:

uri — a valid URI
name — the name of the application registering the bookmark or None
exec — command line to be used to launch the bookmark or None

add_group¶

def add_group(self, uri: str, group: str) -> None

Adds group to the list of groups to which the bookmark for uri belongs to.

If no bookmark for uri is found then it is created.

Parameters:

uri — a valid URI
group — the group name to be added

copy¶

def copy(self) -> BookmarkFile

Deeply copies a bookmark BookmarkFile object to a new one.

free¶

def free(self) -> None

Frees a BookmarkFile.

get_added¶

def get_added(self, uri: str) -> int

:::warning Deprecated since 2.66 This API is deprecated. :::

Gets the time the bookmark for uri was added to bookmark

In the event the URI cannot be found, -1 is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_added_date_time¶

def get_added_date_time(self, uri: str) -> DateTime

Gets the time the bookmark for uri was added to bookmark

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_app_info¶

def get_app_info(self, uri: str, name: str) -> tuple[bool, str, int, int]

:::warning Deprecated since 2.66 This API is deprecated. :::

Gets the registration information of app_name for the bookmark for uri. See BookmarkFile.set_application_info for more information about the returned data.

The string returned in app_exec must be freed.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND. In the event that no application with name app_name has registered a bookmark for uri, False is returned and error is set to BookmarkFileError.APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the G_SHELL_ERROR domain is set and False is returned.

Parameters:

uri — a valid URI
name — an application's name

get_application_info¶

def get_application_info(self, uri: str, name: str) -> tuple[bool, str, int, DateTime]

Gets the registration information of app_name for the bookmark for uri. See BookmarkFile.set_application_info for more information about the returned data.

The string returned in app_exec must be freed.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND. In the event that no application with name app_name has registered a bookmark for uri, False is returned and error is set to BookmarkFileError.APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the G_SHELL_ERROR domain is set and False is returned.

Parameters:

uri — a valid URI
name — an application's name

get_applications¶

def get_applications(self, uri: str) -> list[str]

Retrieves the names of the applications that have registered the bookmark for uri.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_description¶

def get_description(self, uri: str) -> str

Retrieves the description of the bookmark for uri.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_groups¶

def get_groups(self, uri: str) -> list[str]

Retrieves the list of group names of the bookmark for uri.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

The returned array is None terminated, so length may optionally be None.

Parameters:

uri — a valid URI

get_icon¶

def get_icon(self, uri: str) -> tuple[bool, str, str]

Gets the icon of the bookmark for uri.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_is_private¶

def get_is_private(self, uri: str) -> bool

Gets whether the private flag of the bookmark for uri is set.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND. In the event that the private flag cannot be found, False is returned and error is set to BookmarkFileError.INVALID_VALUE.

Parameters:

uri — a valid URI

get_mime_type¶

def get_mime_type(self, uri: str) -> str

Retrieves the MIME type of the resource pointed by uri.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND. In the event that the MIME type cannot be found, None is returned and error is set to BookmarkFileError.INVALID_VALUE.

Parameters:

uri — a valid URI

get_modified¶

def get_modified(self, uri: str) -> int

:::warning Deprecated since 2.66 This API is deprecated. :::

Gets the time when the bookmark for uri was last modified.

In the event the URI cannot be found, -1 is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_modified_date_time¶

def get_modified_date_time(self, uri: str) -> DateTime

Gets the time when the bookmark for uri was last modified.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_size¶

def get_size(self) -> int

Gets the number of bookmarks inside bookmark.

get_title¶

def get_title(self, uri: str | None = ...) -> str

Returns the title of the bookmark for uri.

If uri is None, the title of bookmark is returned.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI or None

get_uris¶

def get_uris(self) -> list[str]

Returns all URIs of the bookmarks in the bookmark file bookmark. The array of returned URIs will be None-terminated, so length may optionally be None.

get_visited¶

def get_visited(self, uri: str) -> int

:::warning Deprecated since 2.66 This API is deprecated. :::

Gets the time the bookmark for uri was last visited.

In the event the URI cannot be found, -1 is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

get_visited_date_time¶

def get_visited_date_time(self, uri: str) -> DateTime

Gets the time the bookmark for uri was last visited.

In the event the URI cannot be found, None is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI

has_application¶

def has_application(self, uri: str, name: str) -> bool

Checks whether the bookmark for uri inside bookmark has been registered by application name.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI
name — the name of the application

has_group¶

def has_group(self, uri: str, group: str) -> bool

Checks whether group appears in the list of groups to which the bookmark for uri belongs to.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

uri — a valid URI
group — the group name to be searched

has_item¶

def has_item(self, uri: str) -> bool

Looks whether the desktop bookmark has an item with its URI set to uri.

Parameters:

uri — a valid URI

load_from_data¶

def load_from_data(self, data: list[int]) -> bool

Loads a bookmark file from memory into an empty BookmarkFile structure. If the object cannot be created then error is set to a BookmarkFileError.

Parameters:

data — desktop bookmarks loaded in memory

load_from_data_dirs¶

def load_from_data_dirs(self, file: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> tuple[bool, str]

This function looks for a desktop bookmark file named file in the paths returned from get_user_data_dir and get_system_data_dirs, loads the file into bookmark and returns the file's full path in full_path. If the file could not be loaded then error is set to either a FileError or BookmarkFileError.

Parameters:

file — a relative path to a filename to open and parse

load_from_file¶

def load_from_file(self, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> bool

Loads a desktop bookmark file into an empty BookmarkFile structure. If the file could not be loaded then error is set to either a FileError or BookmarkFileError.

Parameters:

filename — the path of a filename to load, in the GLib file name encoding

move_item¶

def move_item(self, old_uri: str, new_uri: str | None = ...) -> bool

Changes the URI of a bookmark item from old_uri to new_uri. Any existing bookmark for new_uri will be overwritten. If new_uri is None, then the bookmark is removed.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND.

Parameters:

old_uri — a valid URI
new_uri — a valid URI, or None

remove_application¶

def remove_application(self, uri: str, name: str) -> bool

Removes application registered with name from the list of applications that have registered a bookmark for uri inside bookmark.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND. In the event that no application with name app_name has registered a bookmark for uri, False is returned and error is set to BookmarkFileError.APP_NOT_REGISTERED.

Parameters:

uri — a valid URI
name — the name of the application

remove_group¶

def remove_group(self, uri: str, group: str) -> bool

Removes group from the list of groups to which the bookmark for uri belongs to.

In the event the URI cannot be found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND. In the event no group was defined, False is returned and error is set to BookmarkFileError.INVALID_VALUE.

Parameters:

uri — a valid URI
group — the group name to be removed

remove_item¶

def remove_item(self, uri: str) -> bool

Removes the bookmark for uri from the bookmark file bookmark.

Parameters:

uri — a valid URI

set_added¶

def set_added(self, uri: str, added: int) -> None

:::warning Deprecated since 2.66 This API is deprecated. :::

Sets the time the bookmark for uri was added into bookmark.

If no bookmark for uri is found then it is created.

Parameters:

uri — a valid URI
added — a timestamp or -1 to use the current time

set_added_date_time¶

def set_added_date_time(self, uri: str, added: DateTime) -> None

Sets the time the bookmark for uri was added into bookmark.

If no bookmark for uri is found then it is created.

Parameters:

uri — a valid URI
added — a DateTime

set_app_info¶

def set_app_info(self, uri: str, name: str, exec: str, count: int, stamp: int) -> bool

:::warning Deprecated since 2.66 This API is deprecated. :::

Sets the meta-data of application name inside the list of applications that have registered a bookmark for uri inside bookmark.

You should rarely use this function; use BookmarkFile.add_application and BookmarkFile.remove_application instead.

name can be any UTF-8 encoded string used to identify an application. exec can have one of these two modifiers: "`f", which will be expanded as the local file name retrieved from the bookmark's URI; "\u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the [BookmarkFile.get_application_info](./BookmarkFile.md#method-get_application_info) function.countis the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application withnamewill be removed from the list of registered applications.stamp` is the Unix time of the last registration; if it is -1, the current time will be used.

If you try to remove an application by setting its registration count to zero, and no bookmark for uri is found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND; similarly, in the event that no application name has registered a bookmark for uri, False is returned and error is set to BookmarkFileError.APP_NOT_REGISTERED. Otherwise, if no bookmark for uri is found, one is created.

Parameters:

uri — a valid URI
name — an application's name
exec — an application's command line
count — the number of registrations done for this application
stamp — the time of the last registration for this application

set_application_info¶

def set_application_info(self, uri: str, name: str, exec: str, count: int, stamp: DateTime | None = ...) -> bool

Sets the meta-data of application name inside the list of applications that have registered a bookmark for uri inside bookmark.

You should rarely use this function; use BookmarkFile.add_application and BookmarkFile.remove_application instead.

name can be any UTF-8 encoded string used to identify an application. exec can have one of these two modifiers: "`f", which will be expanded as the local file name retrieved from the bookmark's URI; "\u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the [BookmarkFile.get_application_info](./BookmarkFile.md#method-get_application_info) function.countis the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application withnamewill be removed from the list of registered applications.stamp` is the Unix time of the last registration.

If you try to remove an application by setting its registration count to zero, and no bookmark for uri is found, False is returned and error is set to BookmarkFileError.URI_NOT_FOUND; similarly, in the event that no application name has registered a bookmark for uri, False is returned and error is set to BookmarkFileError.APP_NOT_REGISTERED. Otherwise, if no bookmark for uri is found, one is created.

Parameters:

uri — a valid URI
name — an application's name
exec — an application's command line
count — the number of registrations done for this application
stamp — the time of the last registration for this application, which may be None if count is 0

set_description¶

def set_description(self, uri: str | None, description: str) -> None

Sets description as the description of the bookmark for uri.

If uri is None, the description of bookmark is set.

If a bookmark for uri cannot be found then it is created.

Parameters:

uri — a valid URI or None
description — a string

set_groups¶

def set_groups(self, uri: str, groups: list[str] | None = ...) -> None

Sets a list of group names for the item with URI uri. Each previously set group name list is removed.

If uri cannot be found then an item for it is created.

Parameters:

uri — an item's URI
groups — an array of group names, or None to remove all groups

set_icon¶

def set_icon(self, uri: str, href: str | None, mime_type: str) -> None

Sets the icon for the bookmark for uri. If href is None, unsets the currently set icon. href can either be a full URL for the icon file or the icon name following the Icon Naming specification.

If no bookmark for uri is found one is created.

Parameters:

uri — a valid URI
href — the URI of the icon for the bookmark, or None
mime_type — the MIME type of the icon for the bookmark

set_is_private¶

def set_is_private(self, uri: str, is_private: bool) -> None

Sets the private flag of the bookmark for uri.

If a bookmark for uri cannot be found then it is created.

Parameters:

uri — a valid URI
is_private — True if the bookmark should be marked as private

set_mime_type¶

def set_mime_type(self, uri: str, mime_type: str) -> None

Sets mime_type as the MIME type of the bookmark for uri.

If a bookmark for uri cannot be found then it is created.

Parameters:

uri — a valid URI
mime_type — a MIME type

set_modified¶

def set_modified(self, uri: str, modified: int) -> None

:::warning Deprecated since 2.66 This API is deprecated. :::

Sets the last time the bookmark for uri was last modified.

If no bookmark for uri is found then it is created.

The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of BookmarkFile that modifies a bookmark also changes the modification time, except for BookmarkFile.set_visited_date_time.

Parameters:

uri — a valid URI
modified — a timestamp or -1 to use the current time

set_modified_date_time¶

def set_modified_date_time(self, uri: str, modified: DateTime) -> None

Sets the last time the bookmark for uri was last modified.

If no bookmark for uri is found then it is created.

The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of BookmarkFile that modifies a bookmark also changes the modification time, except for BookmarkFile.set_visited_date_time.

Parameters:

uri — a valid URI
modified — a DateTime

set_title¶

def set_title(self, uri: str | None, title: str) -> None

Sets title as the title of the bookmark for uri inside the bookmark file bookmark.

If uri is None, the title of bookmark is set.

If a bookmark for uri cannot be found then it is created.

Parameters:

uri — a valid URI or None
title — a UTF-8 encoded string

set_visited¶

def set_visited(self, uri: str, visited: int) -> None

:::warning Deprecated since 2.66 This API is deprecated. :::

Sets the time the bookmark for uri was last visited.

If no bookmark for uri is found then it is created.

The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by BookmarkFile.get_application_info or by the default application for the bookmark's MIME type, retrieved using BookmarkFile.get_mime_type. Changing the "visited" time does not affect the "modified" time.

Parameters:

uri — a valid URI
visited — a timestamp or -1 to use the current time

set_visited_date_time¶

def set_visited_date_time(self, uri: str, visited: DateTime) -> None

Sets the time the bookmark for uri was last visited.

If no bookmark for uri is found then it is created.

The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by BookmarkFile.get_application_info or by the default application for the bookmark's MIME type, retrieved using BookmarkFile.get_mime_type. Changing the "visited" time does not affect the "modified" time.

Parameters:

uri — a valid URI
visited — a DateTime

to_data¶

def to_data(self) -> list[int]

This function outputs bookmark as a string.

to_file¶

def to_file(self, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> bool

This function outputs bookmark into a file. The write process is guaranteed to be atomic by using file_set_contents internally.

Parameters:

filename — path of the output file

Static functions¶

error_quark¶

@staticmethod
def error_quark() -> Quark