Portal

class Portal(**properties: Any)

Superclasses: Object

Implemented Interfaces: Initable

Context for portal calls.

The XdpPortal object provides the main context object for the portal operations of libportal.

Typically, an application will create a single XdpPortal object with new and use it throughout its lifetime.

Constructors

class Portal

classmethod initable_new() → Portal | None: Creates a new Portal object.

classmethod new() → Portal: Creates a new Portal object. If D-Bus is unavailable this API will abort. We recommend using initable_new() to safely handle this failure.

Methods

class Portal

access_camera(parent: Parent | None, flags: CameraFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Request access to a camera.

When the request is done, callback will be called. You can then call access_camera_finish to get the results.

Parameters:

parent – parent window information
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

access_camera_finish(result: AsyncResult) → bool

Finishes a camera acess request.

Returns the result as a boolean.

If the access was granted, you can then call open_pipewire_remote_for_camera to obtain a pipewire remote.

Parameters:: result – a AsyncResult

add_notification(id: str, notification: Variant, flags: NotificationFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Sends a desktop notification.

The following keys may be present in notification:

title 's: a user-visible string to display as title
body 's: a user-visible string to display as body
icon v: a serialized icon (in the format produced by serialize)
priority 's: “low”, “normal”, “high” or “urgent”
default-action 's: name of an action that
will be activated when the user clicks on the notification
default-action-target v: target parameter to send along when
activating the default action.
buttons aa{sv}: array of serialized buttons

Each serialized button is a dictionary with the following supported keys:

label 's: user-visible lable for the button. Mandatory
action 's: name of an action that will be activated when
the user clicks on the button. Mandatory
target v: target parameter to send along when activating
the button

Actions with a prefix of “app.” are assumed to be exported by the application and will be activated via the org.freedesktop.Application interface, others are activated by emitting the notification_action_invoked signal.

It is the callers responsibility to ensure that the ID is unique among all notifications.

To withdraw a notification, use remove_notification.

Parameters:

id – unique ID for the notification
notification – a Variant dictionary with the content of the notification
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

add_notification_finish(result: AsyncResult) → bool

Finishes the notification request.

Returns the result as a boolean.

Parameters:: result – a AsyncResult

Presents a window that lets the user compose an email, with some pre-filled information.

When the request is done, callback will be called. You can then call compose_email_finish to get the results.

Parameters:

parent – parent window information
addresses – the email addresses to send to
cc – the email addresses to cc
bcc – the email addresses to bcc
subject – the subject for the email
body – the body for the email
attachments – an array of paths for files to attach
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

compose_email_finish(result: AsyncResult) → bool

Finishes the compose-email request.

Parameters:: result – a AsyncResult

create_remote_desktop_session(devices: DeviceType, outputs: OutputType, flags: RemoteDesktopFlags, cursor_mode: CursorMode, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Creates a session for remote desktop.

When the request is done, callback will be called. You can then call create_remote_desktop_session_finish to get the results.

Parameters:

devices – which kinds of input devices to ofer in the new dialog
outputs – which kinds of source to offer in the dialog
flags – options for this call
cursor_mode – the cursor mode of the session
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

create_remote_desktop_session_finish(result: AsyncResult) → Session

Finishes the create-remote-desktop request, and returns a Session.

Parameters:: result – a AsyncResult

create_screencast_session(outputs: OutputType, flags: ScreencastFlags, cursor_mode: CursorMode, persist_mode: PersistMode, restore_token: str | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Creates a session for a screencast.

When the request is done, callback will be called. You can then call create_screencast_session_finish to get the results.

Parameters:

outputs – which kinds of source to offer in the dialog
flags – options for this call
cursor_mode – the cursor mode of the session
persist_mode – the persist mode of the session
restore_token – the token of a previous screencast session to restore
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

create_screencast_session_finish(result: AsyncResult) → Session

Finishes the create-screencast request, and returns a Session.

Parameters:: result – a AsyncResult

dynamic_launcher_get_desktop_entry(desktop_file_id: str) → str

This function gets the contents of a .desktop file that was previously installed by the dynamic launcher portal.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

Parameters:: desktop_file_id – the .desktop file name

dynamic_launcher_get_icon(desktop_file_id: str, out_icon_format: str | None = None, out_icon_size: int | None = None) → Variant

This function gets the icon associated with a .desktop file that was previously installed by the dynamic launcher portal.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

Parameters:

desktop_file_id – the .desktop file name
out_icon_format – return location for icon format string, one of “png”, “jpeg”, “svg”
out_icon_size – return location for icon size

dynamic_launcher_install(token: str, desktop_file_id: str, desktop_entry: str) → bool

This function completes installation of a launcher so that the icon and name given in previous method calls will show up in the desktop environment’s menu.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

The desktop_entry data need not include Icon= or Name= entries since these will be added by the portal, and the Exec= entry will be rewritten to call the application with e.g. “flatpak run” depending on the sandbox status of the app.

Parameters:

token – a token acquired via a dynamic_launcher_request_install_token or dynamic_launcher_prepare_install call
desktop_file_id – the .desktop file name to be used
desktop_entry – the key-file to be used for the contents of the .desktop file

dynamic_launcher_launch(desktop_file_id: str, activation_token: str) → bool

Parameters:

desktop_file_id
activation_token

dynamic_launcher_prepare_install(parent: Parent | None, name: str, icon_v: Variant, launcher_type: LauncherType, target: str | None, editable_name: bool, editable_icon: bool, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Presents a dialog to the user so they can confirm they want to install a launcher to their desktop.

When the request is done, callback will be called. You can then call dynamic_launcher_prepare_install_finish to get the results.

Parameters:

parent – parent window information
name – the name for the launcher
icon_v – a BytesIcon as returned by serialize(). Must be a png or jpeg no larger than 512x512, or an svg
launcher_type – the type of the launcher
target – the URL if the launcher is for a web app, or None
editable_name – if True, the user will be able to edit the name of the launcher
editable_icon – if True, the user will be able to edit the icon of the launcher, if the implementation supports this
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

dynamic_launcher_prepare_install_finish(result: AsyncResult) → Variant

Finishes the prepare-install-launcher request, and returns Variant dictionary with the following information:

name s: the name chosen by the user (or the provided name if the
editable_name option was not set)
token s: a token that can by used in a dynamic_launcher_install
call to complete the installation

Parameters:: result – a AsyncResult

dynamic_launcher_request_install_token(name: str, icon_v: Variant) → str

Requests a token which can be passed to dynamic_launcher_install to complete installation of the launcher without user interaction.

This function only works when the caller’s app ID is in the allowlist for the portal backend being used. It’s intended for software centers such as GNOME Software or KDE Discover.

Parameters:

name – the name for the launcher
icon_v – a BytesIcon as returned by serialize(). Must be a png or jpeg no larger than 512x512, or an svg

dynamic_launcher_uninstall(desktop_file_id: str) → bool

This function uninstalls a launcher that was previously installed using the dynamic launcher portal, resulting in the .desktop file and icon being deleted.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

Parameters:: desktop_file_id – the .desktop file name

get_user_information(parent: Parent | None, reason: str | None, flags: UserInformationFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Gets information about the user.

When the request is done, callback will be called. You can then call get_user_information_finish to get the results.

Parameters:

parent – parent window information
reason – a string that can be shown in the dialog to explain why the information is needed
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

get_user_information_finish(result: AsyncResult) → Variant

Finishes the get-user-information request.

Returns the result in the form of a Variant dictionary containing the following fields:

id 's: the user ID
name 's: the users real name
image 's: the uri of an image file for the users avatar picture

Parameters:: result – a AsyncResult

is_camera_present() → bool: Returns whether any camera are present.

location_monitor_start(parent: Parent | None, distance_threshold: int, time_threshold: int, accuracy: LocationAccuracy, flags: LocationMonitorFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Makes XdpPortal start monitoring location changes.

When the location changes, the location_updated. signal is emitted.

Use location_monitor_stop to stop monitoring.

Note that Portal only maintains a single location monitor at a time. If you want to change the distance_threshold, time_threshold or accuracy of the current monitor, you first have to call location_monitor_stop to stop monitoring.

Parameters:

parent – a Parent, or NULL
distance_threshold – distance threshold, in meters
time_threshold – time threshold, in seconds
accuracy – desired accuracy
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

location_monitor_start_finish(result: AsyncResult) → bool

Finishes a location-monitor request.

Returns result in the form of boolean.

Parameters:: result – a AsyncResult

location_monitor_stop() → None: Stops location monitoring that was started with location_monitor_start.

open_directory(parent: Parent, uri: str, flags: OpenUriFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Opens the directory containing the file specified by the uri.

which must be a file: uri pointing to a file that the application has access to.

Parameters:

parent – parent window information
uri – the URI to open
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

open_directory_finish(result: AsyncResult) → bool

Finishes the open-directory request.

Returns the result in the form of a boolean.

Parameters:: result – a AsyncResult

Asks the user to open one or more files.

The format for the filters argument is a(sa(us)). Each item in the array specifies a single filter to offer to the user. The first string is a user-visible name for the filter. The a(us) specifies a list of filter strings, which can be either a glob pattern (indicated by 0) or a mimetype (indicated by 1).

Example: [('Images', [(0, '*.ico'), (1, 'image/png')]), ('Text', [(0, '*.txt')])]

The format for the choices argument is a(ssa(ss)s). For each element, the first string is an ID that will be returned with the response, te second string is a user-visible label. The a(ss) is the list of choices, each being a is an ID and a user-visible label. The final string is the initial selection, or "", to let the portal decide which choice will be initially selected. None of the strings, except for the initial selection, should be empty.

As a special case, passing an empty array for the list of choices indicates a boolean choice that is typically displayed as a check button, using "true" and "false" as the choices.

Example: [('encoding', 'Encoding', [('utf8', 'Unicode (UTF-8)'), ('latin15', 'Western')], 'latin15'), ('reencode', 'Reencode', [], 'false')]

When the request is done, callback will be called. You can then call open_file_finish to get the results.

Parameters:

parent – parent window information
title – title for the file chooser dialog
filters – a Variant describing file filters
current_filter – a Variant describing the current file filter
choices – a Variant describing extra widgets
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

open_file_finish(result: AsyncResult) → Variant

Finishes the open-file request

Returns the result in the form of a Variant dictionary containing the following fields:

uris as: an array of strings containing the uris of selected files
choices a(ss): an array of pairs of strings, the first string being the
ID of a combobox that was passed into this call, the second string being the selected option.

Parameters:: result – a AsyncResult

open_pipewire_remote_for_camera() → int

Opens a file descriptor to the pipewire remote where the camera nodes are available.

The file descriptor should be used to create a pw_core object, by using pw_context_connect_fd(). Only the camera nodes will be available from this pipewire node.

open_uri(parent: Parent, uri: str, flags: OpenUriFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Opens uri with an external handler.

Parameters:

parent – parent window information
uri – the URI to open
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

open_uri_finish(result: AsyncResult) → bool

Finishes the open-uri request.

Returns the result in the form of a boolean.

Parameters:: result – a AsyncResult

pick_color(parent: Parent | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Lets the user pick a color from the screen.

When the request is done, callback will be called. You can then call pick_color_finish to get the results.

Parameters:

parent – parent window information
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

pick_color_finish(result: AsyncResult) → Variant

Finishes a pick-color request.

Returns the result in the form of a GVariant of the form (ddd), containing red, green and blue components in the range [0,1].

Parameters:: result – a AsyncResult

Presents a print dialog to the user and returns print settings and page setup.

When the request is done, callback will be called. You can then call prepare_print_finish to get the results.

Parameters:

parent – parent window information
title – tile for the print dialog
settings – Serialized print settings
page_setup – Serialized page setup
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

prepare_print_finish(result: AsyncResult) → Variant

Finishes the prepare-print request.

Returns a Variant dictionary with the following information:

settings a{sv}: print settings as set up by the user in the print dialog
page-setup `a{sv}: page setup as set up by the user in the print dialog
token u: a token that can by used in a print_file call to
avoid the print dialog

Parameters:: result – a AsyncResult

print_file(parent: Parent | None, title: str, token: int, file: str, flags: PrintFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *data: Any) → None

Prints a file.

If a valid token is present in the options, then this call will print with the settings from the Print call that the token refers to. If no token is present, then a print dialog will be presented to the user.

When the request is done, callback will be called. You can then call print_file_finish to get the results.

Parameters:

parent – parent window information
title – tile for the print dialog
token – token that was returned by a previous prepare_print call, or 0
file – path of the document to print
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
data – data to pass to callback

print_file_finish(result: AsyncResult) → bool

Finishes the print request.

Parameters:: result – a AsyncResult

remove_notification(id: str) → None

Withdraws a desktop notification.

Parameters:: id – the ID of an notification

request_background(parent: Parent | None, reason: str | None, commandline: Sequence[str], flags: BackgroundFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Requests background permissions.

When the request is done, callback will be called. You can then call request_background_finish to get the results.

Parameters:

parent – parent window information
reason – reason to present to user for request
commandline – command line to autostart
flags – options for this call
cancellable – optional Cancellable
callback – a callback to call when the request is done
user_data – data to pass to callback

request_background_finish(result: AsyncResult) → bool

Finishes the request.

Returns TRUE if successful.

Parameters:: result – a AsyncResult

running_under_flatpak() → bool

Detects if running inside of a Flatpak or WebKit sandbox.

Signals

class Portal.signals

location_updated(latitude: float, longitude: float, altitude: float, accuracy: float, speed: float, heading: float, description: str, timestamp_s: int, timestamp_ms: int) → None

Emitted when location monitoring is enabled and the location changes.

Parameters:

latitude – the latitude, in degrees
longitude – the longitude, in degrees
altitude – the altitude, in meters
accuracy – the accuracy, in meters
speed – the speed, in meters per second
heading – the heading, in degrees
description – the description
timestamp_s – the timestamp seconds since the Unix epoch
timestamp_ms – the microseconds fraction of the timestamp

notification_action_invoked(id: str, action: str, parameter: Variant | None = None) → None

Emitted when a non-exported action is activated on a notification.

Parameters:

id – the notification ID
action – the action name
parameter – the target parameter for the action

session_state_changed(screensaver_active: bool, session_state: LoginSessionState) → None

Emitted when session state monitoring is enabled and the state of the login session changes or the screensaver is activated or deactivated.

Parameters:

screensaver_active – whether the screensaver is active
session_state – the current state of the login session

spawn_exited(pid: int, exit_status: int) → None

Emitted when a process that was spawned with spawn exits.

Parameters:

pid – the pid of the process
exit_status – the exit status of the process

update_available(running_commit: str, local_commit: str, remote_commit: str) → None

Emitted when updates monitoring is enabled and a new update is available.

It is only sent once with the same information, but it can be sent many times if new updates appear.

Parameters:

running_commit – the commit that the sandbox is running with
local_commit – the commit that is currently deployed. Restarting the app will use this commit
remote_commit – the commit that is available as an update. Updating the app will deloy this commit

update_progress(n_ops: int, op: int, progress: int, status: UpdateStatus, error: str, error_message: str) → None

Emitted to indicate progress of an update installation.

It is undefined exactly how often it is sent, but it will be emitted at least once at the end with a non-zero status. For each successful operation in the update, we’re also guaranteed to send exactly one signal with progress 100.

Parameters:

n_ops – the number of operations that the update consists of
op – the position of the currently active operation
progress – the progress of the currently active operation, as a number between 0 and 100
status – the overall status of the update
error – the error name if the status is ‘failed’
error_message – the error message if the status is ‘failed’