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:
- When creating a QString to contain a URL from a QByteArray or a char*, always use QString::fromUtf8().
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) |