WebContext

class WebContext(**properties: Any)

Superclasses: Object

Manages aspects common to all :obj:`~gi.repository.WebKit.WebView`<!– –>s

The WebContext manages all aspects common to all :obj:`~gi.repository.WebKit.WebView`<!– –>s.

You can define the CacheModel with set_cache_model(), depending on the needs of your application. You can access the SecurityManager to specify the behaviour of your application regarding security using get_security_manager().

It is also possible to change your preferred language or enable spell checking, using set_preferred_languages(), set_spell_checking_languages() and set_spell_checking_enabled().

You can use register_uri_scheme() to register custom URI schemes, and manage several other settings.

TLS certificate validation failure is now treated as a transport error by default. To handle TLS failures differently, you can connect to WebView::load-failed-with-tls-errors. Alternatively, you can use webkit_web_context_set_tls_errors_policy() to set the policy IGNORE; however, this is not appropriate for Internet applications.

Constructors

class WebContext

classmethod new() → WebContext: Create a new WebContext.

Added in version 2.8.

Methods

class WebContext

add_path_to_sandbox(path: str, read_only: bool) → None

Adds a path to be mounted in the sandbox.

path must exist before any web process has been created; otherwise, it will be silently ignored. It is a fatal error to add paths after a web process has been spawned.

Paths under /sys, /proc, and /dev are invalid. Attempting to add all of / is not valid. Since 2.40, adding the user’s entire home directory or /home is also not valid.

See also webkit_web_context_set_sandbox_enabled()

Added in version 2.26.

Parameters:

path – an absolute path to mount in the sandbox
read_only – if True the path will be read-only

get_cache_model() → CacheModel

Returns the current cache model.

For more information about this value check the documentation of the function set_cache_model().

get_default() → WebContext: Gets the default web context.

get_geolocation_manager() → GeolocationManager: Get the GeolocationManager of context.

Added in version 2.26.

get_network_session_for_automation() → NetworkSession | None: Get the NetworkSession used for automation sessions started in context.

Added in version 2.40.

get_security_manager() → SecurityManager: Get the SecurityManager of context.

get_spell_checking_enabled() → bool: Get whether spell checking feature is currently enabled.

get_spell_checking_languages() → list[str]

Get the the list of spell checking languages.

Get the the list of spell checking languages associated with context, or None if no languages have been previously set.

See set_spell_checking_languages() for more details on the format of the languages in the list.

get_time_zone_override() → str: Get the WebContext:time-zone-override property.

Added in version 2.38.

initialize_notification_permissions(allowed_origins: list[SecurityOrigin], disallowed_origins: list[SecurityOrigin]) → None

Sets initial desktop notification permissions for the context.

allowed_origins and disallowed_origins must each be List of SecurityOrigin objects representing origins that will, respectively, either always or never have permission to show desktop notifications. No WebKitNotificationPermissionRequest will ever be generated for any of the security origins represented in allowed_origins or disallowed_origins. This function is necessary because some webpages proactively check whether they have permission to display notifications without ever creating a permission request.

This function only affects web processes that have not already been created. The best time to call it is when handling WebContext::initialize-notification-permissions so as to ensure that new web processes receive the most recent set of permissions.

Added in version 2.16.

Parameters:

allowed_origins – a List of security origins
disallowed_origins – a List of security origins

is_automation_allowed() → bool

Get whether automation is allowed in context.

See also set_automation_allowed().

Added in version 2.18.

register_uri_scheme(scheme: str, callback: Callable[[...], None], *user_data: Any) → None

Register scheme in context, so that when an URI request with scheme is made in the WebContext, the URISchemeRequestCallback registered will be called with a URISchemeRequest. It is possible to handle URI scheme requests asynchronously, by calling ref() on the URISchemeRequest and calling finish() later when the data of the request is available or finish_error() in case of error.

static void
about_uri_scheme_request_cb (WebKitURISchemeRequest *request,
                             gpointer                user_data)
{
    GInputStream *stream;
    gsize         stream_length;
    const gchar  *path = webkit_uri_scheme_request_get_path (request);

    if (!g_strcmp0 (path, "memory")) {
        // Create a GInputStream with the contents of memory about page, and set its length to stream_length
    } else if (!g_strcmp0 (path, "applications")) {
        // Create a GInputStream with the contents of applications about page, and set its length to stream_length
    } else if (!g_strcmp0 (path, "example")) {
        gchar *contents = g_strdup_printf ("<html><body><p>Example about page</p></body></html>");
        stream_length = strlen (contents);
        stream = g_memory_input_stream_new_from_data (contents, stream_length, g_free);
    } else {
        GError *error = g_error_new (ABOUT_HANDLER_ERROR, ABOUT_HANDLER_ERROR_INVALID, "Invalid about:``%s`` page.", path);
        webkit_uri_scheme_request_finish_error (request, error);
        g_error_free (error);
        return;
    }
    webkit_uri_scheme_request_finish (request, stream, stream_length, "text/html");
    g_object_unref (stream);
}

Parameters:

scheme – the network scheme to register
callback – a URISchemeRequestCallback
user_data – data to pass to callback function

send_message_to_all_extensions(message: UserMessage) → None

Send message to all web process extensions associated to context.

If message is floating, it’s consumed.

Added in version 2.28.

Parameters:: message – a UserMessage

set_automation_allowed(allowed: bool) → None

Set whether automation is allowed in context.

When automation is enabled the browser could be controlled by another process by requesting an automation session. When a new automation session is requested the signal WebContext::automation-started is emitted. Automation is disabled by default, so you need to explicitly call this method passing True to enable it.

Note that only one WebContext can have automation enabled, so this will do nothing if there’s another WebContext with automation already enabled.

Added in version 2.18.

Parameters:: allowed – value to set

set_cache_model(cache_model: CacheModel) → None

Specifies a usage model for WebViews.

Specifies a usage model for WebViews, which WebKit will use to determine its caching behavior. All web views follow the cache model. This cache model determines the RAM and disk space to use for caching previously viewed content .

Research indicates that users tend to browse within clusters of documents that hold resources in common, and to revisit previously visited documents. WebKit and the frameworks below it include built-in caches that take advantage of these patterns, substantially improving document load speed in browsing situations. The WebKit cache model controls the behaviors of all of these caches, including various WebCore caches.

Browsers can improve document load speed substantially by specifying WEB_BROWSER. Applications without a browsing interface can reduce memory usage substantially by specifying DOCUMENT_VIEWER. The default value is WEB_BROWSER.

Parameters:: cache_model – a CacheModel

set_preferred_languages(languages: Sequence[str] | None = None) → None

Set the list of preferred languages.

Set the list of preferred languages, sorted from most desirable to least desirable. The list will be used in the following ways:

Determining how to build the Accept-Language HTTP header that will be included in the network requests started by the WebContext.
Setting the values of navigator.language and navigator.languages.
The first item in the list sets the default locale for JavaScript Intl functions.

Parameters:: languages – a None-terminated list of language identifiers

set_spell_checking_enabled(enabled: bool) → None

Enable or disable the spell checking feature.

Parameters:: enabled – Value to be set

set_spell_checking_languages(languages: Sequence[str]) → None

Set the list of spell checking languages to be used for spell checking.

The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil.

You need to call this function with a valid list of languages at least once in order to properly enable the spell checking feature in WebKit.

Parameters:: languages – a None-terminated list of spell checking languages

set_web_process_extensions_directory(directory: str) → None

Set the directory where WebKit will look for web process extensions.

This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to WebContext::initialize-web-process-extensions to call this method before anything is loaded.

Parameters:: directory – the directory to add

set_web_process_extensions_initialization_user_data(user_data: Variant) → None

Set user data to be passed to Web Extensions on initialization.

The data will be passed to the WebKitWebProcessExtensionInitializeWithUserDataFunction. This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to WebContext::initialize-web-process-extensions to call this method before anything is loaded.

Added in version 2.4.

Parameters:: user_data – a Variant

Properties

class WebContext

props.memory_pressure_settings: MemoryPressureSettings: The MemoryPressureSettings applied to the web processes created by this context.

Added in version 2.34.

props.time_zone_override: str

The timezone override for this web context. Setting this property provides a better alternative to configure the timezone information for all webviews managed by the WebContext. The other, less optimal, approach is to globally set the TZ environment variable in the process before creating the context. However this approach might not be very convenient and can have side-effects in your application.

The expected values for this property are defined in the IANA timezone database. See this wikipedia page for instance, https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Added in version 2.38.

Signals

class WebContext.signals

automation_started(session: AutomationSession) → None

This signal is emitted when a new automation request is made. Note that it will never be emitted if automation is not enabled in context, see set_automation_allowed() for more details.

Added in version 2.18.

Parameters:: session – the AutomationSession associated with this event

initialize_notification_permissions() → None: This signal is emitted when a WebContext needs to set initial notification permissions for a web process. It is emitted when a new web process is about to be launched, and signals the most appropriate moment to use initialize_notification_permissions(). If no notification permissions have changed since the last time this signal was emitted, then there is no need to call initialize_notification_permissions() again.

Added in version 2.16.

initialize_web_process_extensions() → None: This signal is emitted when a new web process is about to be launched. It signals the most appropriate moment to use set_web_process_extensions_initialization_user_data() and set_web_process_extensions_directory().

Added in version 2.4.

user_message_received(message: UserMessage) → bool

This signal is emitted when a UserMessage is received from a web process extension. You can reply to the message using send_reply().

You can handle the user message asynchronously by calling ref() on message and returning True.

Added in version 2.28.

Parameters:: message – the UserMessage received