Skip to content

PythonQt.QtCore.QUrl

QUrl

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

It can parse and construct URLs in both encoded and unencoded form. QUrl also has support for internationalized domain names (IDNs).

The most common way to use QUrl is to initialize it via the constructor by passing a QString. Otherwise, setUrl() can also be used.

URLs can be represented in two forms: encoded or unencoded. The unencoded representation is suitable for showing to users, but the encoded representation is typically what you would send to a web server. For example, the unencoded URL "http://bühler.example.com/List of applicants.xml" would be sent to the server as "http://xn--bhler-kva.example.com/List%20of%20applicants.xml".

A URL can also be constructed piece by piece by calling setScheme(), setUserName(), setPassword(), setHost(), setPort(), setPath(), setQuery() and setFragment(). Some convenience functions are also available: setAuthority() sets the user name, password, host and port. setUserInfo() sets the user name and password at once.

Call isValid() to check if the URL is valid. This can be done at any point during the constructing of a URL. If isValid() returns false, you should clear() the URL before proceeding, or start over by parsing a new URL with setUrl().

Constructing a query is particularly convenient through the use of the QUrlQuery class and its methods QUrlQuery::setQueryItems(), QUrlQuery::addQueryItem() and QUrlQuery::removeQueryItem(). Use QUrlQuery::setQueryDelimiters() to customize the delimiters used for generating the query string.

For the convenience of generating encoded URL strings or query strings, there are two static functions called fromPercentEncoding() and toPercentEncoding() which deal with percent encoding and decoding of QString objects.

fromLocalFile() constructs a QUrl by parsing a local file path. toLocalFile() converts a URL to a local file path.

The human readable representation of the URL is fetched with toString(). This representation is appropriate for displaying a URL to a user in unencoded form. The encoded form however, as returned by toEncoded(), is for internal use, passing to web servers, mail clients and so on. Both forms are technically correct and represent the same URL unambiguously -- in fact, passing either form to QUrl's constructor or to setUrl() will yield the same QUrl object.

QUrl conforms to the URI specification from RFC 3986 (Uniform Resource Identifier: Generic Syntax), and includes scheme extensions from RFC 1738 (Uniform Resource Locators). Case folding rules in QUrl conform to RFC 3491 (Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)). It is also compatible with the file URI specification from freedesktop.org, provided that the locale encodes file names using UTF-8 (required by IDN).

Relative URLs vs Relative Paths

Calling isRelative() will return whether or not the URL is relative. A relative URL has no scheme. For example:

    qDebug() << QUrl("main.qml").isRelative();          // true: no scheme
    qDebug() << QUrl("qml/main.qml").isRelative();      // true: no scheme
    qDebug() << QUrl("file:main.qml").isRelative();     // false: has "file" scheme
    qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" scheme

Notice that a URL can be absolute while containing a relative path, and vice versa:

    // Absolute URL, relative path
    QUrl url("file:file.txt");
    qDebug() << url.isRelative();                 // false: has "file" scheme
    qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path

    // Relative URL, absolute path
    url = QUrl("/home/user/file.txt");
    qDebug() << url.isRelative();                 // true: has no scheme
    qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute path

A relative URL can be resolved by passing it as an argument to resolved(), which returns an absolute URL. isParentOf() is used for determining whether one URL is a parent of another.

Error checking

QUrl is capable of detecting many errors in URLs while parsing it or when components of the URL are set with individual setter methods (like setScheme(), setHost() or setPath()). If the parsing or setter function is successful, any previously recorded error conditions will be discarded.

By default, QUrl setter methods operate in QUrl::TolerantMode, which means they accept some common mistakes and mis-representation of data. An alternate method of parsing is QUrl::StrictMode, which applies further checks. See QUrl::ParsingMode for a description of the difference of the parsing modes.

QUrl only checks for conformance with the URL specification. It does not try to verify that high-level protocol URLs are in the format they are expected to be by handlers elsewhere. For example, the following URIs are all considered valid by QUrl, even if they do not make sense when used:

  • "http:/filename.html"
  • "mailto://example.com"

When the parser encounters an error, it signals the event by making isValid() return false and toString() / toEncoded() return an empty string. If it is necessary to show the user the reason why the URL failed to parse, the error condition can be obtained from QUrl by calling errorString(). Note that this message is highly technical and may not make sense to end-users.

QUrl is capable of recording only one error condition. If more than one error is found, it is undefined which error is reported.

Character Conversions

Follow these rules to avoid erroneous character conversion when dealing with URLs and strings:

Source: https://doc.qt.io/archives/qt-5.15/qurl.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
AssumeLocalFile attribute Any
ComponentFormattingOption attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
ComponentFormattingOptions attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
DecodeReserved attribute Any
DecodedMode attribute Any
DefaultResolution attribute Any
EncodeDelimiters attribute Any
EncodeReserved attribute Any
EncodeSpaces attribute Any
EncodeUnicode attribute Any
FullyDecoded attribute Any
FullyEncoded attribute Any
None_ attribute Any (shared captured text)
NormalizePathSegments attribute Any
ParsingMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
PreferLocalFile attribute Any
PrettyDecoded attribute Any
RemoveAuthority attribute Any
RemoveFilename attribute Any
RemoveFragment attribute Any
RemovePassword attribute Any
RemovePath attribute Any
RemovePort attribute Any
RemoveQuery attribute Any
RemoveScheme attribute Any
RemoveUserInfo attribute Any
StrictMode attribute Any
StripTrailingSlash attribute Any
TolerantMode attribute Any
UrlFormattingOption attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
UserInputResolutionOption attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
adjusted function (self, options: Any) -> Any X.adjusted(options) -> PythonQt.QtCore.QUrl
authority function (self, options: Any) -> str X.authority(options) -> str
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
clear function (self) -> None Resets the content of the [QUrl](https://doc.qt.io/archives/qt-5.15/qurl.html).
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
errorString function (self) -> str X.errorString() -> str
fileName function (self, options: Any) -> str X.fileName(options) -> str
fragment function (self, options: Any) -> str X.fragment(options) -> str
fromAce function (self, arg__1: Any) -> str X.fromAce(arg__1) -> str
fromEncoded function (self, url: Any, mode: Any) -> Any X.fromEncoded(url, mode) -> PythonQt.QtCore.QUrl
fromLocalFile function (self, localfile: str) -> Any X.fromLocalFile(localfile) -> PythonQt.QtCore.QUrl
fromPercentEncoding function (self, arg__1: Any) -> str X.fromPercentEncoding(arg__1) -> str
fromStringList function (self, uris: Any, mode: Any) -> tuple X.fromStringList(uris, mode) -> tuple
fromUserInput function (self, userInput: str) -> Any X.fromUserInput(userInput) -> PythonQt.QtCore.QUrl
hasFragment function (self) -> bool X.hasFragment() -> bool
hasQuery function (self) -> bool X.hasQuery() -> bool
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
host function (self, arg__1: Any) -> str X.host(arg__1) -> str
idnWhitelist function (self) -> tuple X.idnWhitelist() -> tuple
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
isEmpty function (self) -> bool X.isEmpty() -> bool
isLocalFile function (self) -> bool X.isLocalFile() -> bool
isParentOf function (self, url: Any) -> bool X.isParentOf(url) -> bool
isRelative function (self) -> bool X.isRelative() -> bool
isValid function (self) -> bool X.isValid() -> bool
matches function (self, url: Any, options: Any) -> bool X.matches(url, options) -> bool
password function (self, arg__1: Any) -> str X.password(arg__1) -> str
path function (self, options: Any) -> str X.path(options) -> str
port function (self, defaultPort: int) -> int X.port(defaultPort) -> int
query function (self, arg__1: Any) -> str X.query(arg__1) -> str
readFrom function (self, arg__1: Any) -> Any (shared captured text)
resolved function (self, relative: Any) -> Any X.resolved(relative) -> PythonQt.QtCore.QUrl
scheme function (self) -> str X.scheme() -> str
setAuthority function (self, authority: str, mode: Any) -> None X.setAuthority(authority, mode)
setFragment function (self, fragment: str, mode: Any) -> None X.setFragment(fragment, mode)
setHost function (self, host: str, mode: Any) -> None X.setHost(host, mode)
setIdnWhitelist function (self, arg__1: Any) -> None Sets the whitelist of Top-Level Domains (TLDs) that are allowed to have non-ASCII characters in domains to the value of list.
setPassword function (self, password: str, mode: Any) -> None X.setPassword(password, mode)
setPath function (self, path: str, mode: Any) -> None X.setPath(path, mode)
setPort function (self, port: int) -> None Sets the port of the URL to port.
setQuery function (self, query: Any, mode: Any) -> None X.setQuery(query, mode)
setScheme function (self, scheme: str) -> None Sets the scheme of the URL to scheme.
setUrl function (self, url: str, mode: Any) -> None X.setUrl(url, mode)
setUserInfo function (self, userInfo: str, mode: Any) -> None X.setUserInfo(userInfo, mode)
setUserName function (self, userName: str, mode: Any) -> None X.setUserName(userName, mode)
swap function (self, other: Any) -> None Swaps URL other with this URL.
toAce function (self, arg__1: str) -> Any X.toAce(arg__1) -> PythonQt.QtCore.QByteArray
toDisplayString function (self, options: Any) -> str X.toDisplayString(options) -> str
toEncoded function (self, options: Any) -> Any X.toEncoded(options) -> PythonQt.QtCore.QByteArray
toLocalFile function (self) -> str X.toLocalFile() -> str
toPercentEncoding function (self, arg__1: str, exclude: Any, include: Any) -> Any X.toPercentEncoding(arg__1, exclude, include) -> PythonQt.QtCore.QByteArray
toString function (self, options: Any) -> str X.toString(options) -> str
toStringList function (self, uris: Any, options: Any) -> tuple X.toStringList(uris, options) -> tuple
topLevelDomain function (self, options: Any) -> str X.topLevelDomain(options) -> str
url function (self, options: Any) -> str X.url(options) -> str
userInfo function (self, options: Any) -> str X.userInfo(options) -> str
userName function (self, options: Any) -> str X.userName(options) -> str
writeTo function (self, arg__1: Any) -> Any (shared captured text)