Skip to content

PythonQt.Qt.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 (shared captured text)
ComponentFormattingOption attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ComponentFormattingOptions attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
DecodeReserved attribute Any (shared captured text)
DecodedMode attribute Any (shared captured text)
DefaultResolution attribute Any (shared captured text)
EncodeDelimiters attribute Any (shared captured text)
EncodeReserved attribute Any (shared captured text)
EncodeSpaces attribute Any (shared captured text)
EncodeUnicode attribute Any (shared captured text)
FullyDecoded attribute Any (shared captured text)
FullyEncoded attribute Any (shared captured text)
None_ attribute Any (shared captured text)
NormalizePathSegments attribute Any (shared captured text)
ParsingMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
PreferLocalFile attribute Any (shared captured text)
PrettyDecoded attribute Any (shared captured text)
RemoveAuthority attribute Any (shared captured text)
RemoveFilename attribute Any (shared captured text)
RemoveFragment attribute Any (shared captured text)
RemovePassword attribute Any (shared captured text)
RemovePath attribute Any (shared captured text)
RemovePort attribute Any (shared captured text)
RemoveQuery attribute Any (shared captured text)
RemoveScheme attribute Any (shared captured text)
RemoveUserInfo attribute Any (shared captured text)
StrictMode attribute Any (shared captured text)
StripTrailingSlash attribute Any (shared captured text)
TolerantMode attribute Any (shared captured text)
UrlFormattingOption attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
UserInputResolutionOption attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
__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 (shared captured text)
authority function (self, options: Any) -> str X.authority(options) -> str (shared captured text)
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). (shared captured text)
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 (shared captured text)
fileName function (self, options: Any) -> str X.fileName(options) -> str (shared captured text)
fragment function (self, options: Any) -> str X.fragment(options) -> str (shared captured text)
fromAce function (self, arg__1: Any) -> str X.fromAce(arg__1) -> str (shared captured text)
fromEncoded function (self, url: Any, mode: Any) -> Any X.fromEncoded(url, mode) -> PythonQt.QtCore.QUrl (shared captured text)
fromLocalFile function (self, localfile: str) -> Any X.fromLocalFile(localfile) -> PythonQt.QtCore.QUrl (shared captured text)
fromPercentEncoding function (self, arg__1: Any) -> str X.fromPercentEncoding(arg__1) -> str (shared captured text)
fromStringList function (self, uris: Any, mode: Any) -> tuple X.fromStringList(uris, mode) -> tuple (shared captured text)
fromUserInput function (self, userInput: str) -> Any X.fromUserInput(userInput) -> PythonQt.QtCore.QUrl (shared captured text)
hasFragment function (self) -> bool X.hasFragment() -> bool (shared captured text)
hasQuery function (self) -> bool X.hasQuery() -> bool (shared captured text)
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 (shared captured text)
idnWhitelist function (self) -> tuple X.idnWhitelist() -> tuple (shared captured text)
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 (shared captured text)
isLocalFile function (self) -> bool X.isLocalFile() -> bool (shared captured text)
isParentOf function (self, url: Any) -> bool X.isParentOf(url) -> bool (shared captured text)
isRelative function (self) -> bool X.isRelative() -> bool (shared captured text)
isValid function (self) -> bool X.isValid() -> bool (shared captured text)
matches function (self, url: Any, options: Any) -> bool X.matches(url, options) -> bool (shared captured text)
password function (self, arg__1: Any) -> str X.password(arg__1) -> str (shared captured text)
path function (self, options: Any) -> str X.path(options) -> str (shared captured text)
port function (self, defaultPort: int) -> int X.port(defaultPort) -> int (shared captured text)
query function (self, arg__1: Any) -> str X.query(arg__1) -> str (shared captured text)
readFrom function (self, arg__1: Any) -> Any (shared captured text)
resolved function (self, relative: Any) -> Any X.resolved(relative) -> PythonQt.QtCore.QUrl (shared captured text)
scheme function (self) -> str X.scheme() -> str (shared captured text)
setAuthority function (self, authority: str, mode: Any) -> None X.setAuthority(authority, mode) (shared captured text)
setFragment function (self, fragment: str, mode: Any) -> None X.setFragment(fragment, mode) (shared captured text)
setHost function (self, host: str, mode: Any) -> None X.setHost(host, mode) (shared captured text)
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. (shared captured text)
setPassword function (self, password: str, mode: Any) -> None X.setPassword(password, mode) (shared captured text)
setPath function (self, path: str, mode: Any) -> None X.setPath(path, mode) (shared captured text)
setPort function (self, port: int) -> None Sets the port of the URL to port. (shared captured text)
setQuery function (self, query: Any, mode: Any) -> None X.setQuery(query, mode) (shared captured text)
setScheme function (self, scheme: str) -> None Sets the scheme of the URL to scheme. (shared captured text)
setUrl function (self, url: str, mode: Any) -> None X.setUrl(url, mode) (shared captured text)
setUserInfo function (self, userInfo: str, mode: Any) -> None X.setUserInfo(userInfo, mode) (shared captured text)
setUserName function (self, userName: str, mode: Any) -> None X.setUserName(userName, mode) (shared captured text)
swap function (self, other: Any) -> None Swaps URL other with this URL. (shared captured text)
toAce function (self, arg__1: str) -> Any X.toAce(arg__1) -> PythonQt.QtCore.QByteArray (shared captured text)
toDisplayString function (self, options: Any) -> str X.toDisplayString(options) -> str (shared captured text)
toEncoded function (self, options: Any) -> Any X.toEncoded(options) -> PythonQt.QtCore.QByteArray (shared captured text)
toLocalFile function (self) -> str X.toLocalFile() -> str (shared captured text)
toPercentEncoding function (self, arg__1: str, exclude: Any, include: Any) -> Any X.toPercentEncoding(arg__1, exclude, include) -> PythonQt.QtCore.QByteArray (shared captured text)
toString function (self, options: Any) -> str X.toString(options) -> str (shared captured text)
toStringList function (self, uris: Any, options: Any) -> tuple X.toStringList(uris, options) -> tuple (shared captured text)
topLevelDomain function (self, options: Any) -> str X.topLevelDomain(options) -> str (shared captured text)
url function (self, options: Any) -> str X.url(options) -> str (shared captured text)
userInfo function (self, options: Any) -> str X.userInfo(options) -> str (shared captured text)
userName function (self, options: Any) -> str X.userName(options) -> str (shared captured text)
writeTo function (self, arg__1: Any) -> Any (shared captured text)