class QWebEngineProfile

The QWebEngineProfile class provides a web engine profile shared by multiple pages. More…

Inheritance diagram of PySide6.QtWebEngineCore.QWebEngineProfile

Synopsis

Methods

Signals

Static functions

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

A web engine profile contains settings, scripts, persistent cookie policy, and the list of visited links shared by all web engine pages that belong to the profile.

All pages that belong to the profile share a common QWebEngineSettings instance, which can be accessed with the settings() method. Likewise, the scripts() method provides access to a common QWebEngineScriptCollection instance.

Information about visited links is stored together with persistent cookies and other persistent data in a storage returned by storageName() . Persistent data is stored in a subdirectory set by calling setPersistentStoragePath() , and the cache is located in a subdirectory set by calling setCachePath() . The cache type can be set to in-memory or on-disk by calling setHttpCacheType() . If only the storage name is set, the subdirectories are created and named automatically. If you set any of the values manually, you should do it before creating any pages that belong to the profile.

The cache can be cleared of links by calling clearVisitedLinks() or clearAllVisitedLinks() . PersistentCookiesPolicy describes whether session and persistent cookies are saved to and restored from memory or disk.

Profiles can be used to isolate pages from each other. A typical use case is a dedicated off-the-record profile for a private browsing mode. Using QWebEngineProfile() without defining a storage name constructs a new off-the-record profile that leaves no record on the local machine, and has no persistent data or cache. The isOffTheRecord() method can be used to check whether a profile is off-the-record.

The default profile can be accessed by defaultProfile() . It is a built-in profile that all web pages not specifically created with another profile belong to.

Implementing the QWebEngineUrlRequestInterceptor interface and registering the interceptor on a profile by setUrlRequestInterceptor() enables intercepting, blocking, and modifying URL requests ( QWebEngineUrlRequestInfo ) before they reach the networking stack of Chromium.

A QWebEngineUrlSchemeHandler can be registered for a profile by installUrlSchemeHandler() to add support for custom URL schemes. Requests for the scheme are then issued to requestStarted() as QWebEngineUrlRequestJob objects.

Spellchecking HTML form fields can be enabled per profile by using the setSpellCheckEnabled() method and the current languages used for spellchecking can be set by using the setSpellCheckLanguages() method.

class HttpCacheType

This enum describes the HTTP cache type:

Constant

Description

QWebEngineProfile.MemoryHttpCache

Use an in-memory cache. This is the default if off-the-record is set.

QWebEngineProfile.DiskHttpCache

Use a disk cache. This is the default if the profile is not off-the-record. If set on an off-the-record profile will instead set MemoryHttpCache.

QWebEngineProfile.NoCache

Disable both in-memory and disk caching. (Added in Qt 5.7)
class PersistentCookiesPolicy

This enum describes policy for cookie persistence:

Constant

Description

QWebEngineProfile.NoPersistentCookies

Both session and persistent cookies are stored in memory. This is the only setting possible if off-the-record is set or no persistent data path is available.

QWebEngineProfile.AllowPersistentCookies

Cookies marked persistent are saved to and restored from disk, whereas session cookies are only stored to disk for crash recovery. This is the default setting.

QWebEngineProfile.ForcePersistentCookies

Both session and persistent cookies are saved to and restored from disk.
class PersistentPermissionsPolicy

This enum describes the policy for permission persistence:

Constant

Description

QWebEngineProfile.PersistentPermissionsPolicy.AskEveryTime

The application will ask for permissions every time they’re needed, regardless of whether they’ve been granted before or not. This is intended for backwards compatibility with existing applications, and otherwise not recommended.

QWebEngineProfile.PersistentPermissionsPolicy.StoreInMemory

A request will be made only the first time a permission is needed. Any subsequent requests will be automatically granted or denied, depending on the initial user choice. This carries over to all pages that use the same QWebEngineProfile instance, until the application is shut down. This is the setting applied if off-the-record is set or no persistent data path is available.

QWebEngineProfile.PersistentPermissionsPolicy.StoreOnDisk

Works the same way as StoreInMemory, but the permissions are saved to and restored from disk. This is the default setting.

Added in version 6.8.

__init__([parent=None])
Parameters:

parent – QObject

Constructs a new off-the-record profile with the parent parent.

An off-the-record profile leaves no record on the local machine, and has no persistent data or cache. Thus, the HTTP cache can only be in memory and the cookies can only be non-persistent. Trying to change these settings will have no effect.

See also

isOffTheRecord()

__init__(name[, parent=None])
Parameters:

Constructs a new profile with the storage name storageName and parent parent.

The storage name must be unique.

A disk-based QWebEngineProfile should be destroyed on or before application exit, otherwise the cache and persistent data may not be fully flushed to disk.

See also

storageName()

cachePath()
Return type:

str

Returns the path used for caches.

By default, this is below StandardPaths::CacheLocation in a QtWebengine/StorageName specific subdirectory.

Note

Use QStandardPaths::writableLocation(QStandardPaths::CacheLocation) to obtain the QStandardPaths::CacheLocation path.

See also

setCachePath() storageName() writableLocation()

Clears all links from the visited links database.

clearHttpCache()

Removes the profile’s cache entries.

Note

Make sure that you do not start new navigation or any operation on the profile while the clear operation is in progress. The clearHttpCacheCompleted() signal notifies about the completion.

See also

clearHttpCacheCompleted()

clearHttpCacheCompleted()

This signal is emitted when the clearHttpCache() operation is completed.

See also

clearHttpCache()

Parameters:

urls – .list of QUrl

Clears the links in urls from the visited links database.

clientCertificateStore()
Return type:

QWebEngineClientCertificateStore

Returns the profile’s client certificate store.

clientHints()
Return type:

QWebEngineClientHints

Return the Client Hints settings associated with this browsing context.

cookieStore()
Return type:

QWebEngineCookieStore

Returns the cookie store for this profile.

static defaultProfile()
Return type:

QWebEngineProfile

Returns the default profile.

The default profile is off-the-record.

See also

storageName()

downloadPath()
Return type:

str

The path to the location where the downloaded files are stored.

Note

By default, the download path is QStandardPaths::DownloadLocation.

See also

setDownloadPath() writableLocation()

downloadRequested(download)
Parameters:

download – QWebEngineDownloadRequest

This signal is emitted whenever a download has been triggered. The download argument holds the state of the download. The download has to be explicitly accepted with accept() or it will be cancelled by default. The download item is parented by the profile. If it is not accepted, it will be deleted immediately after the signal emission. This signal cannot be used with a queued connection.

httpAcceptLanguage()
Return type:

str

Returns the value of the Accept-Language HTTP request-header field.

httpCacheMaximumSize()
Return type:

int

Returns the maximum size of the HTTP cache in bytes.

Will return 0 if the size is automatically controlled by QtWebEngine .

httpCacheType()
Return type:

HttpCacheType

Returns the type of HTTP cache used.

If the profile is off-the-record, MemoryHttpCache is returned.

httpUserAgent()
Return type:

str

Returns the user-agent string sent with HTTP to identify the browser.

Note

On Windows 8.1 and newer, the default user agent will always report “Windows NT 6.2” (Windows 8), unless the application does contain a manifest that declares newer Windows versions as supported.

See also

setHttpUserAgent() Windows Application Manifest

installUrlSchemeHandler(scheme, arg__2)
Parameters:

Registers a handler handler for custom URL scheme scheme in the profile.

It is necessary to first register the scheme with registerScheme at application startup.

isOffTheRecord()
Return type:

bool

Returns true if this is an off-the-record profile that leaves no record on the computer.

This will force cookies and HTTP cache to be in memory, but also force all other normally persistent data to be stored in memory.

isPushServiceEnabled()
Return type:

bool

Returns true if the push messaging service is enabled.

Note

By default the push messaging service is disabled.

See also

setPushServiceEnabled()

isSpellCheckEnabled()
Return type:

bool

Returns true if the spell checker is enabled; otherwise returns false.

listAllPermissions()
Return type:

.list of QWebEnginePermission

Returns a QList of QWebEnginePermission objects, each one representing a single permission currently present in the permissions store. The returned list contains all previously granted/denied permissions for this profile, provided they are of a persistent type.

Note

When persistentPermissionPolicy() is set to AskEveryTime, this will return an empty list.

See also

queryPermission() PermissionType isPersistent()

listPermissionsForOrigin(securityOrigin)
Parameters:

securityOrigin – QUrl

Return type:

.list of QWebEnginePermission

Returns a QList of QWebEnginePermission objects, each one representing a single permission currently present in the permissions store. The returned list contains all previously granted/denied permissions associated with a specific securityOrigin for this profile, provided they are of a persistent type.

Note

Since permissions are granted on a per-origin basis, the provided securityOrigin will be stripped to its origin form, and the returned list will contain all permissions for the origin. Thus, passing https://www.example.com/some/page.html is the same as passing just https://www.example.com/.

Note

When persistentPermissionPolicy() is set to AskEveryTime, this will return an empty list.

See also

queryPermission() PermissionType isPersistent()

listPermissionsForPermissionType(permissionType)
Parameters:

permissionType – PermissionType

Return type:

.list of QWebEnginePermission

Returns a QList of QWebEnginePermission objects, each one representing a single permission currently present in the permissions store. The returned list contains all previously granted/denied permissions of the provided permissionType. If the permissionType is non-persistent, the list will be empty.

Note

When persistentPermissionPolicy() is set to AskEveryTime, this will return an empty list.

See also

queryPermission() PermissionType isPersistent()

persistentCookiesPolicy()
Return type:

PersistentCookiesPolicy

Returns the current policy for persistent cookies.

If the profile is off-the-record, NoPersistentCookies is returned.

persistentPermissionsPolicy()
Return type:

PersistentPermissionsPolicy

Returns the current policy for persistent permissions.

Off-the-record profiles are not allowed to save data to the disk, so they can only return StoreInMemory or AskEveryTime.

persistentStoragePath()
Return type:

str

Returns the path used to store persistent data for the browser and web content.

Persistent data includes persistent cookies, HTML5 local storage, and visited links.

By default, this is below QStandardPaths::DataLocation in a QtWebengine/StorageName specific subdirectory.

Note

Use QStandardPaths::writableLocation(QStandardPaths::DataLocation) to obtain the QStandardPaths::DataLocation path.

See also

setPersistentStoragePath() storageName() writableLocation()

queryPermission(securityOrigin, permissionType)
Parameters:
Return type:

QWebEnginePermission

Returns a QWebEnginePermission object corresponding to a single permission for the provided securityOrigin and permissionType. The object may be used to query for the current state of the permission, or to change it. It is not required for a permission to already exist; the returned object may also be used to pre-grant a permission if a website is known to use it.

You may use this to pre-grant a permission of a non-persistent type. Doing so will keep the permission in the granted (or denied) state until the next time a website with the associated origin requests it. At that point, the permission’s lifetime will be tied to that specific web page’s lifetime, and navigating away will invalidate the permission.

removeAllUrlSchemeHandlers()

Removes all custom URL scheme handlers installed in the profile.

removeUrlScheme(scheme)
Parameters:

scheme – QByteArray

Removes the custom URL scheme scheme from the profile.

removeUrlSchemeHandler(arg__1)
Parameters:

arg__1 – QWebEngineUrlSchemeHandler

Removes the custom URL scheme handler handler from the profile.

scripts()
Return type:

QWebEngineScriptCollection

Returns the collection of scripts that are injected into all pages that share this profile.

setCachePath(path)
Parameters:

path – str

Overrides the default path used for disk caches, setting it to path.

If set to the null string, the default path is restored.

See also

cachePath()

setDownloadPath(path)
Parameters:

path – str

Overrides the default path used for download location, setting it to path.

If set to the null string, the default path is restored.

See also

downloadPath()

setHttpAcceptLanguage(httpAcceptLanguage)
Parameters:

httpAcceptLanguage – str

Sets the value of the Accept-Language HTTP request-header field to httpAcceptLanguage.

setHttpCacheMaximumSize(maxSize)
Parameters:

maxSize – int

Sets the maximum size of the HTTP cache to maxSize bytes.

Setting it to 0 means the size will be controlled automatically by QtWebEngine .

setHttpCacheType(arg__1)
Parameters:

arg__1 – HttpCacheType

Sets the HTTP cache type to httpCacheType.

Note

Setting the httpCacheType to NoCache on the profile, which has already some cache entries does not trigger the removal of those entries.

See also

httpCacheType() setCachePath() clearHttpCache()

setHttpUserAgent(userAgent)
Parameters:

userAgent – str

Overrides the default user-agent string, setting it to userAgent.

See also

httpUserAgent()

setNotificationPresenter(notificationPresenter)
Parameters:

notificationPresenter – PyCallable

setPersistentCookiesPolicy(arg__1)
Parameters:

arg__1 – PersistentCookiesPolicy

Sets the policy for persistent cookies to newPersistentCookiesPolicy.

setPersistentPermissionsPolicy(arg__1)
Parameters:

arg__1 – PersistentPermissionsPolicy

Sets the policy for persistent permissions to newPersistentPermissionsPolicy.

setPersistentStoragePath(path)
Parameters:

path – str

Overrides the default path used to store persistent web engine data.

If path is set to the null string, the default path is restored.

setPushServiceEnabled(enabled)
Parameters:

enabled – bool

Enables the push messaging service if enable is true, otherwise disables it.

Note

Qt WebEngine uses Firebase Cloud Messaging (FCM) as a browser push service. Therefore, all push messages will go through the Google push service and its respective servers.

See also

isPushServiceEnabled()

setSpellCheckEnabled(enabled)
Parameters:

enabled – bool

Enables spell checker if enable is true, otherwise disables it.

setSpellCheckLanguages(languages)
Parameters:

languages – list of strings

Sets the current list of languages for the spell checker. Each language should match the name of the .bdic dictionary. For example, the language en-US will load the en-US.bdic dictionary file.

See the Spellchecker feature documentation for how dictionary files are searched.

For more information about how to compile .bdic dictionaries, see the Spellchecker Example .

setUrlRequestInterceptor(interceptor)
Parameters:

interceptor – QWebEngineUrlRequestInterceptor

Registers a request interceptor singleton interceptor to intercept URL requests.

The profile does not take ownership of the pointer.

settings()
Return type:

QWebEngineSettings

Returns the default settings for all pages in this profile.

spellCheckLanguages()
Return type:

list of strings

Returns the list of languages used by the spell checker.

storageName()
Return type:

str

Returns the storage name for the profile.

The storage name is used to give each profile that uses the disk separate subdirectories for persistent data and cache.

urlSchemeHandler(arg__1)
Parameters:

arg__1 – QByteArray

Return type:

QWebEngineUrlSchemeHandler

Returns the custom URL scheme handler register for the URL scheme scheme.

visitedLinksContainsUrl(url)
Parameters:

url – QUrl

Return type:

bool

Returns true if url is considered a visited link by this profile.