urllib.parse — URLs in Komponenten zerlegen

Quellcode: Lib/urllib/parse.py

---

Dieses Modul definiert eine Standardoberfläche zum Zerlegen von Uniform Resource Locator (URL)-Zeichenketten in Komponenten (Adressierungsschema, Netzwerkstandort, Pfad usw.), zum Zusammenfügen der Komponenten zurück zu einer URL-Zeichenkette und zur Umwandlung einer „relativen URL“ in eine absolute URL unter Angabe einer „Basis-URL“.

Das Modul wurde so konzipiert, dass es mit den Internet-RFCs für Relative Uniform Resource Locators übereinstimmt. Es unterstützt die folgenden URL-Schemata: file, ftp, gopher, hdl, http, https, imap, itms-services, mailto, mms, news, nntp, prospero, rsync, rtsp, rtsps, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

CPython-Implementierungsdetail: Die Aufnahme des itms-services URL-Schemas kann verhindern, dass eine App den macOS- und iOS-App-Store-Überprüfungsprozess von Apple besteht. Die Handhabung des itms-services Schemas wird unter iOS immer entfernt; unter macOS kann es entfernt werden, wenn CPython mit der Option --with-app-store-compliance erstellt wurde.

Das Modul urllib.parse definiert Funktionen, die in zwei Hauptkategorien fallen: URL-Parsing und URL-Quoting. Diese werden in den folgenden Abschnitten detailliert behandelt.

Die Funktionen dieses Moduls verwenden den veralteten Begriff netloc (oder net_loc), der in RFC 1808 eingeführt wurde. Dieser Begriff wurde jedoch durch RFC 3986 abgelöst, die den Begriff authority als dessen Ersatz eingeführt hat. Die Verwendung von netloc wird aus Kompatibilitätsgründen beibehalten.

URL-Parsing

Die URL-Parsing-Funktionen konzentrieren sich darauf, eine URL-Zeichenkette in ihre Komponenten aufzuteilen oder URL-Komponenten zu einer URL-Zeichenkette zusammenzufügen.

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)

Zerlegt eine URL in sechs Komponenten und gibt ein 6-elementiges Named Tuple zurück. Dies entspricht der allgemeinen Struktur einer URL: scheme://netloc/path;parameters?query#fragment. Jedes Tupel-Element ist eine Zeichenkette, möglicherweise leer. Die Komponenten werden nicht in kleinere Teile zerlegt (z. B. ist der Netzwerkstandort eine einzelne Zeichenkette), und %-Escapes werden nicht erweitert. Die oben gezeigten Trennzeichen sind nicht Teil des Ergebnisses, mit Ausnahme eines führenden Schrägstrichs in der path-Komponente, der bei Vorhandensein beibehalten wird. Zum Beispiel

>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
            query='query', fragment='fragment')
>>> o = urlparse("https://docs.pythonlang.de:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='',
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'https://docs.pythonlang.de:80/3/library/urllib.parse.html?highlight=params'

Gemäß den Syntaxspezifikationen in RFC 1808 erkennt `urlparse` eine `netloc` nur, wenn sie korrekt mit '//' eingeleitet wird. Andernfalls wird angenommen, dass die Eingabe eine relative URL ist und daher mit einer `path`-Komponente beginnt.

>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('help/Python.html')
ParseResult(scheme='', netloc='', path='help/Python.html', params='',
            query='', fragment='')

Das Argument scheme gibt das Standard-Adressierungsschema an, das nur verwendet werden soll, wenn die URL keines angibt. Es sollte denselben Typ (Text oder Bytes) wie urlstring haben, außer dass der Standardwert '' immer zulässig ist und automatisch in b'' konvertiert wird, falls dies angemessen ist.

Wenn das Argument allow_fragments falsch ist, werden Fragment-Identifikatoren nicht erkannt. Stattdessen werden sie als Teil der Pfad-, Parameter- oder Abfragekomponente geparst, und fragment wird im Rückgabewert auf die leere Zeichenkette gesetzt.

Der Rückgabewert ist ein Named Tuple, was bedeutet, dass seine Elemente nach Index oder als benannte Attribute zugegriffen werden können, die da sind

Attribut	Index	Wert	Wert, wenn nicht vorhanden
scheme	0	URL-Schema-Spezifizierer	scheme Parameter
netloc	1	Netzwerkstandort-Teil	leere Zeichenkette
path	2	Hierarchischer Pfad	leere Zeichenkette
params	3	Parameter für das letzte Pfadsegment	leere Zeichenkette
query	4	Query-Komponente	leere Zeichenkette
fragment	5	Fragment-Identifikator	leere Zeichenkette
username		Benutzername	None
password		Passwort	None
hostname		Hostname (kleingeschrieben)	None
port		Portnummer als Ganzzahl, falls vorhanden	None

Das Lesen des Attributs port löst eine ValueError aus, wenn ein ungültiger Port in der URL angegeben ist. Siehe Abschnitt Strukturierte Parse-Ergebnisse für weitere Informationen über das Ergebnisobjekt.

Nicht übereinstimmende eckige Klammern im Attribut netloc lösen eine ValueError aus.

Zeichen in der netloc-Attribut, die unter NFKC-Normalisierung (wie bei der IDNA-Kodierung verwendet) in eines der Zeichen /, ?, #, @ oder : zerfallen, lösen eine ValueError aus. Wenn die URL vor dem Parsen zerlegt wird, wird kein Fehler ausgelöst.

Wie bei allen Named Tuples hat die Unterklasse einige zusätzliche Methoden und Attribute, die besonders nützlich sind. Eine solche Methode ist _replace(). Die Methode _replace() gibt ein neues ParseResult-Objekt zurück, das angegebene Felder durch neue Werte ersetzt.

>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')

Warnung

urlparse() führt keine Validierung durch. Siehe URL-Parsing-Sicherheit für Details.

Geändert in Version 3.2: Hinzugefügte IPv6-URL-Parsing-Funktionen.

Geändert in Version 3.3: Das Fragment wird jetzt für alle URL-Schemata geparst (sofern allow_fragments nicht falsch ist), gemäß RFC 3986. Zuvor gab es eine Whitelist von Schemata, die Fragmente unterstützten.

Geändert in Version 3.6: Portnummern außerhalb des Bereichs lösen nun ValueError aus, anstatt None zurückzugeben.

Geändert in Version 3.8: Zeichen, die das `netloc`-Parsing unter NFKC-Normalisierung beeinflussen, lösen nun ValueError aus.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Zerlegt eine als Zeichenkettenargument übergebene Abfragezeichenkette (Daten vom Typ application/x-www-form-urlencoded). Die Daten werden als Wörterbuch zurückgegeben. Die Wörterbuchschlüssel sind die eindeutigen Namen der Abfragevariablen und die Werte sind Listen von Werten für jeden Namen.

Das optionale Argument keep_blank_values ist eine Flag, die angibt, ob leere Werte in prozentkodierten Abfragen als leere Zeichenketten behandelt werden sollen. Ein wahrer Wert gibt an, dass Leerzeichen als leere Zeichenketten beibehalten werden sollen. Der standardmäßige falsche Wert gibt an, dass leere Werte ignoriert und so behandelt werden sollen, als wären sie nicht enthalten.

Das optionale Argument strict_parsing ist eine Flag, die angibt, was bei Parsing-Fehlern zu tun ist. Wenn es falsch ist (Standardwert), werden Fehler stillschweigend ignoriert. Wenn es wahr ist, lösen Fehler eine Ausnahme ValueError aus.

Die optionalen Parameter encoding und errors geben an, wie prozentkodierte Sequenzen in Unicode-Zeichen dekodiert werden, wie sie von der Methode bytes.decode() akzeptiert werden.

Das optionale Argument max_num_fields gibt die maximale Anzahl der zu lesenden Felder an. Wenn gesetzt, wird eine ValueError ausgelöst, wenn mehr als max_num_fields Felder gelesen werden.

Das optionale Argument separator ist das Symbol, das zur Trennung der Abfrageargumente verwendet wird. Es hat standardmäßig den Wert '&'.

Verwenden Sie die Funktion urllib.parse.urlencode() (mit dem Parameter doseq auf True gesetzt), um solche Wörterbücher in Abfragezeichenketten umzuwandeln.

Geändert in Version 3.2: Parameter encoding und errors hinzugefügt.

Geändert in Version 3.8: Parameter max_num_fields hinzugefügt.

Geändert in Version 3.10: Parameter separator hinzugefügt mit dem Standardwert '&'. Python-Versionen vor Python 3.10 erlaubten die Verwendung von ; und & als Trennzeichen für Abfrageparameter. Dies wurde geändert, um nur einen einzigen Trennschlüssel zuzulassen, wobei & das Standardtrennzeichen ist.

Veraltet seit Version 3.14: Das Akzeptieren von Objekten mit falschen Werten (wie 0 und []) außer leeren Zeichenketten und byte-ähnlichen Objekten und None ist jetzt veraltet.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Zerlegt eine als Zeichenkettenargument übergebene Abfragezeichenkette (Daten vom Typ application/x-www-form-urlencoded). Die Daten werden als Liste von Namens-Wert-Paaren zurückgegeben.

Das optionale Argument keep_blank_values ist eine Flag, die angibt, ob leere Werte in prozentkodierten Abfragen als leere Zeichenketten behandelt werden sollen. Ein wahrer Wert gibt an, dass Leerzeichen als leere Zeichenketten beibehalten werden sollen. Der standardmäßige falsche Wert gibt an, dass leere Werte ignoriert und so behandelt werden sollen, als wären sie nicht enthalten.

Das optionale Argument strict_parsing ist eine Flag, die angibt, was bei Parsing-Fehlern zu tun ist. Wenn es falsch ist (Standardwert), werden Fehler stillschweigend ignoriert. Wenn es wahr ist, lösen Fehler eine Ausnahme ValueError aus.

Die optionalen Parameter encoding und errors geben an, wie prozentkodierte Sequenzen in Unicode-Zeichen dekodiert werden, wie sie von der Methode bytes.decode() akzeptiert werden.

Das optionale Argument max_num_fields gibt die maximale Anzahl der zu lesenden Felder an. Wenn gesetzt, wird eine ValueError ausgelöst, wenn mehr als max_num_fields Felder gelesen werden.

Das optionale Argument separator ist das Symbol, das zur Trennung der Abfrageargumente verwendet wird. Es hat standardmäßig den Wert '&'.

Verwenden Sie die Funktion urllib.parse.urlencode(), um solche Listen von Paaren in Abfragezeichenketten umzuwandeln.

Geändert in Version 3.2: Parameter encoding und errors hinzugefügt.

Geändert in Version 3.8: Parameter max_num_fields hinzugefügt.

Geändert in Version 3.10: Parameter separator hinzugefügt mit dem Standardwert '&'. Python-Versionen vor Python 3.10 erlaubten die Verwendung von ; und & als Trennzeichen für Abfrageparameter. Dies wurde geändert, um nur einen einzigen Trennschlüssel zuzulassen, wobei & das Standardtrennzeichen ist.

urllib.parse.urlunparse(parts)

Konstruiert eine URL aus einem Tupel, wie es von urlparse() zurückgegeben wird. Das Argument parts kann ein beliebiges sechs-elementiges Iterable sein. Dies kann zu einer geringfügig anderen, aber äquivalenten URL führen, wenn die ursprünglich geparste URL unnötige Trennzeichen enthielt (z. B. ein ? mit einer leeren Abfrage; die RFC besagt, dass diese äquivalent sind).

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)

Dies ist ähnlich wie urlparse(), zerlegt aber die Parameter nicht aus der URL. Dies sollte im Allgemeinen anstelle von urlparse() verwendet werden, wenn die neuere URL-Syntax gewünscht ist, die es ermöglicht, Parameter auf jedes Segment des path-Teils der URL anzuwenden (siehe RFC 2396). Eine separate Funktion ist erforderlich, um die Pfadsegmente und Parameter zu trennen. Diese Funktion gibt ein 5-elementiges Named Tuple zurück.

(addressing scheme, network location, path, query, fragment identifier).

Der Rückgabewert ist ein Named Tuple, seine Elemente können nach Index oder als benannte Attribute zugegriffen werden.

Attribut	Index	Wert	Wert, wenn nicht vorhanden
scheme	0	URL-Schema-Spezifizierer	scheme Parameter
netloc	1	Netzwerkstandort-Teil	leere Zeichenkette
path	2	Hierarchischer Pfad	leere Zeichenkette
query	3	Query-Komponente	leere Zeichenkette
fragment	4	Fragment-Identifikator	leere Zeichenkette
username		Benutzername	None
password		Passwort	None
hostname		Hostname (kleingeschrieben)	None
port		Portnummer als Ganzzahl, falls vorhanden	None

Das Lesen des Attributs port löst eine ValueError aus, wenn ein ungültiger Port in der URL angegeben ist. Siehe Abschnitt Strukturierte Parse-Ergebnisse für weitere Informationen über das Ergebnisobjekt.

Nicht übereinstimmende eckige Klammern im Attribut netloc lösen eine ValueError aus.

Zeichen in der netloc-Attribut, die unter NFKC-Normalisierung (wie bei der IDNA-Kodierung verwendet) in eines der Zeichen /, ?, #, @ oder : zerfallen, lösen eine ValueError aus. Wenn die URL vor dem Parsen zerlegt wird, wird kein Fehler ausgelöst.

Folgend der WHATWG-Spezifikation, die RFC 3986 aktualisiert, werden führende C0-Kontrollzeichen und Leerzeichen von der URL gestrippt. \n, \r und Tabulator \t Zeichen werden an jeder Position aus der URL entfernt.

Warnung

urlsplit() führt keine Validierung durch. Siehe URL-Parsing-Sicherheit für Details.

Geändert in Version 3.6: Portnummern außerhalb des Bereichs lösen nun ValueError aus, anstatt None zurückzugeben.

Geändert in Version 3.8: Zeichen, die das `netloc`-Parsing unter NFKC-Normalisierung beeinflussen, lösen nun ValueError aus.

Geändert in Version 3.10: ASCII-Zeilenumbruchs- und Tabulatorzeichen werden von der URL gestrippt.

Geändert in Version 3.12: Führende WHATWG C0-Kontrollzeichen und Leerzeichen werden von der URL gestrippt.

urllib.parse.urlunsplit(parts)

Kombiniert die Elemente eines Tupels, wie von urlsplit() zurückgegeben, zu einer vollständigen URL als Zeichenkette. Das Argument parts kann ein beliebiges fünf-elementiges Iterable sein. Dies kann zu einer geringfügig anderen, aber äquivalenten URL führen, wenn die ursprünglich geparste URL unnötige Trennzeichen enthielt (z. B. ein ? mit einer leeren Abfrage; die RFC besagt, dass diese äquivalent sind).

urllib.parse.urljoin(base, url, allow_fragments=True)

Konstruiert eine vollständige („absolute“) URL durch Kombination einer „Basis-URL“ (base) mit einer anderen URL (url). Informell nutzt dies Komponenten der Basis-URL, insbesondere das Adressierungsschema, den Netzwerkstandort und (Teile des) Pfades, um fehlende Komponenten in der relativen URL bereitzustellen. Zum Beispiel

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

Das Argument allow_fragments hat dieselbe Bedeutung und denselben Standardwert wie für urlparse().

Hinweis

Wenn url eine absolute URL ist (d. h. sie beginnt mit // oder scheme://), sind der Hostname und/oder das Schema von url im Ergebnis enthalten. Zum Beispiel

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//pythonlang.de/%7Eguido')
'https://pythonlang.de/%7Eguido'

Wenn Sie dieses Verhalten nicht wünschen, bereiten Sie url mit urlsplit() und urlunsplit() vor und entfernen Sie mögliche scheme- und netloc-Teile.

Warnung

Da eine absolute URL als Parameter url übergeben werden kann, ist es im Allgemeinen **nicht sicher**, urljoin mit einer vom Angreifer kontrollierten url zu verwenden. Zum Beispiel in urljoin("https://website.com/users/", username), wenn username eine absolute URL enthalten kann, ist das Ergebnis von urljoin die absolute URL.

Geändert in Version 3.5: Verhalten wurde aktualisiert, um mit den in RFC 3986 definierten Semantiken übereinzustimmen.

urllib.parse.urldefrag(url)

Wenn url einen Fragment-Identifikator enthält, wird eine modifizierte Version von url ohne Fragment-Identifikator und der Fragment-Identifikator als separate Zeichenkette zurückgegeben. Wenn kein Fragment-Identifikator in url vorhanden ist, wird url unverändert und eine leere Zeichenkette zurückgegeben.

Der Rückgabewert ist ein Named Tuple, seine Elemente können nach Index oder als benannte Attribute zugegriffen werden.

Attribut	Index	Wert	Wert, wenn nicht vorhanden
url	0	URL ohne Fragment	leere Zeichenkette
fragment	1	Fragment-Identifikator	leere Zeichenkette

Siehe Abschnitt Strukturierte Parse-Ergebnisse für weitere Informationen über das Ergebnisobjekt.

Geändert in Version 3.2: Ergebnis ist ein strukturiertes Objekt statt eines einfachen 2-Tupels.

urllib.parse.unwrap(url)

Extrahiert die URL aus einer verpackten URL (d. h. einer Zeichenkette im Format <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path oder scheme://host/path). Wenn url keine verpackte URL ist, wird sie unverändert zurückgegeben.

URL-Parsing-Sicherheit

Die APIs urlsplit() und urlparse() führen keine **Validierung** von Eingaben durch. Sie lösen möglicherweise keine Fehler bei Eingaben aus, die andere Anwendungen als ungültig betrachten. Sie können auch bei einigen Eingaben erfolgreich sein, die anderswo möglicherweise nicht als URLs betrachtet werden. Ihr Zweck ist die praktische Funktionalität und nicht die Reinheit.

Anstatt bei ungewöhnlichen Eingaben eine Ausnahme auszulösen, geben sie möglicherweise einige Komponenten als leere Zeichenketten zurück. Oder Komponenten enthalten möglicherweise mehr, als sie sollten.

Wir empfehlen Benutzern dieser APIs, bei denen die Werte möglicherweise irgendwo mit Sicherheitsimplikationen verwendet werden, defensiv zu programmieren. Führen Sie einige Überprüfungen in Ihrem Code durch, bevor Sie einem zurückgegebenen Teil einer Komponente vertrauen. Macht der scheme Sinn? Ist das ein sinnvoller path? Gibt es etwas Seltsames an diesem hostname? usw.

Was eine URL ausmacht, ist nicht universell gut definiert. Unterschiedliche Anwendungen haben unterschiedliche Bedürfnisse und gewünschte Einschränkungen. Zum Beispiel beschreibt die lebende WHATWG-Spezifikation, was benutzernahe Webclients wie ein Webbrowser benötigen. Während RFC 3986 allgemeiner ist. Diese Funktionen integrieren einige Aspekte beider, können aber nicht als konform mit einer von beiden beansprucht werden. Die APIs und bestehender Benutzercode mit Erwartungen an spezifische Verhaltensweisen gehen beiden Standards voraus, was uns sehr vorsichtig macht, API-Verhaltensänderungen vorzunehmen.

Parsing von ASCII-kodierten Bytes

Die URL-Parsing-Funktionen wurden ursprünglich nur für die Arbeit mit Zeichenketten entwickelt. In der Praxis ist es nützlich, richtig kodierte und maskierte URLs als ASCII-Byte-Sequenzen manipulieren zu können. Daher arbeiten die URL-Parsing-Funktionen in diesem Modul zusätzlich zu str-Objekten auch mit bytes- und bytearray-Objekten.

Wenn str-Daten übergeben werden, enthält das Ergebnis auch nur str-Daten. Wenn bytes- oder bytearray-Daten übergeben werden, enthält das Ergebnis nur bytes-Daten.

Der Versuch, str-Daten mit bytes oder bytearray in einem einzigen Funktionsaufruf zu mischen, führt zu einer TypeError, während der Versuch, nicht-ASCII-Byte-Werte zu übergeben, eine UnicodeDecodeError auslöst.

Um die einfachere Konvertierung von Ergebnisobjekten zwischen str und bytes zu unterstützen, bieten alle Rückgabewerte von URL-Parsing-Funktionen entweder eine encode()-Methode (wenn das Ergebnis str-Daten enthält) oder eine decode()-Methode (wenn das Ergebnis bytes-Daten enthält). Die Signaturen dieser Methoden entsprechen denen der entsprechenden str- und bytes-Methoden (außer dass die Standardkodierung 'ascii' statt 'utf-8' ist). Jede erzeugt einen Wert vom entsprechenden Typ, der entweder bytes-Daten (für encode()-Methoden) oder str-Daten (für decode()-Methoden) enthält.

Anwendungen, die mit potenziell falsch maskierten URLs arbeiten müssen, die Nicht-ASCII-Daten enthalten können, müssen ihre eigene Dekodierung von Bytes in Zeichen vornehmen, bevor sie die URL-Parsing-Methoden aufrufen.

Das in diesem Abschnitt beschriebene Verhalten gilt nur für die URL-Parsing-Funktionen. Die URL-Quoting-Funktionen verwenden ihre eigenen Regeln beim Erzeugen oder Verbrauchen von Byte-Sequenzen, wie in der Dokumentation der einzelnen URL-Quoting-Funktionen beschrieben.

Geändert in Version 3.2: URL-Parsing-Funktionen akzeptieren jetzt ASCII-kodierte Byte-Sequenzen.

Strukturierte Analyseergebnisse

Die Ergebnisobjekte der Funktionen urlparse(), urlsplit() und urldefrag() sind Unterklassen des tuple-Typs. Diese Unterklassen fügen die in der Dokumentation für diese Funktionen aufgeführten Attribute, die im vorherigen Abschnitt beschriebene Unterstützung für Kodierung und Dekodierung sowie eine zusätzliche Methode hinzu.

urllib.parse.SplitResult.()

Gibt die wieder zusammengefügte Version der ursprünglichen URL als String zurück. Diese kann sich von der ursprünglichen URL unterscheiden, da das Schema in Kleinbuchstaben normalisiert und leere Komponenten entfernt werden können. Insbesondere werden leere Parameter, Abfragen und Fragmentbezeichner entfernt.

Für Ergebnisse von urldefrag() werden nur leere Fragmentbezeichner entfernt. Für Ergebnisse von urlsplit() und urlparse() werden alle genannten Änderungen an der von dieser Methode zurückgegebenen URL vorgenommen.

Das Ergebnis dieser Methode bleibt unverändert, wenn es erneut durch die ursprüngliche Parsing-Funktion geleitet wird.

>>> from urllib.parse import urlsplit
>>> url = 'https://pythonlang.de/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'https://pythonlang.de/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'https://pythonlang.de/doc/'

Die folgenden Klassen implementieren die strukturierten Analyseergebnisse, wenn sie auf str-Objekte angewendet werden.

class urllib.parse.DefragResult(url, fragment)

Konkrete Klasse für Ergebnisse von urldefrag(), die str-Daten enthält. Die Methode encode() gibt eine Instanz von DefragResultBytes zurück.

Hinzugefügt in Version 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

Konkrete Klasse für Ergebnisse von urlparse(), die str-Daten enthält. Die Methode encode() gibt eine Instanz von ParseResultBytes zurück.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

Konkrete Klasse für Ergebnisse von urlsplit(), die str-Daten enthält. Die Methode encode() gibt eine Instanz von SplitResultBytes zurück.

Die folgenden Klassen implementieren die Analyseergebnisse, wenn sie auf bytes- oder bytearray-Objekte angewendet werden.

class urllib.parse.DefragResultBytes(url, fragment)

Konkrete Klasse für Ergebnisse von urldefrag(), die bytes-Daten enthält. Die Methode decode() gibt eine Instanz von DefragResult zurück.

Hinzugefügt in Version 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

Konkrete Klasse für Ergebnisse von urlparse(), die bytes-Daten enthält. Die Methode decode() gibt eine Instanz von ParseResult zurück.

Hinzugefügt in Version 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

Konkrete Klasse für Ergebnisse von urlsplit(), die bytes-Daten enthält. Die Methode decode() gibt eine Instanz von SplitResult zurück.

Hinzugefügt in Version 3.2.

URL-Kodierung

Die URL-Kodierungsfunktionen konzentrieren sich darauf, Programmdaten zu nehmen und sie durch Kodierung von Sonderzeichen und entsprechende Kodierung von Nicht-ASCII-Texten für die Verwendung als URL-Komponenten sicher zu machen. Sie unterstützen auch das Umkehren dieser Operationen, um die ursprünglichen Daten aus dem Inhalt einer URL-Komponente wiederherzustellen, falls diese Aufgabe nicht bereits von den oben genannten URL-Parsing-Funktionen abgedeckt wird.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

Ersetzt Sonderzeichen in string mit dem %xx-Escape. Buchstaben, Ziffern und die Zeichen '_.-~' werden nie kodiert. Standardmäßig ist diese Funktion für die Kodierung des Pfadteils einer URL gedacht. Der optionale Parameter safe gibt zusätzliche ASCII-Zeichen an, die nicht kodiert werden sollen – sein Standardwert ist '/'.

string kann entweder ein str- oder ein bytes-Objekt sein.

Geändert in Version 3.7: Von RFC 2396 zu RFC 3986 für die Kodierung von URL-Strings verschoben. „~“ ist jetzt in der Menge der unreservierten Zeichen enthalten.

Die optionalen Parameter encoding und errors geben an, wie mit Nicht-ASCII-Zeichen umzugehen ist, wie sie von der Methode str.encode() akzeptiert werden. encoding ist standardmäßig 'utf-8'. errors ist standardmäßig 'strict', was bedeutet, dass nicht unterstützte Zeichen einen UnicodeEncodeError auslösen. encoding und errors dürfen nicht angegeben werden, wenn string ein bytes ist, andernfalls wird ein TypeError ausgelöst.

Beachten Sie, dass quote(string, safe, encoding, errors) äquivalent zu quote_from_bytes(string.encode(encoding, errors), safe) ist.

Beispiel: quote('/El Niño/') ergibt '/El%20Ni%C3%B1o/'.

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)

Ähnlich wie quote(), ersetzt jedoch auch Leerzeichen durch Pluszeichen, wie es für die Kodierung von HTML-Formularwerten beim Erstellen einer Abfragezeichenfolge für eine URL erforderlich ist. Pluszeichen in der ursprünglichen Zeichenfolge werden kodiert, es sei denn, sie sind in safe enthalten. Es hat auch nicht safe standardmäßig auf '/' gesetzt.

Beispiel: quote_plus('/El Niño/') ergibt '%2FEl+Ni%C3%B1o%2F'.

urllib.parse.quote_from_bytes(bytes, safe='/')

Ähnlich wie quote(), akzeptiert jedoch ein bytes-Objekt anstelle eines str und führt keine String-zu-Bytes-Kodierung durch.

Beispiel: quote_from_bytes(b'a&\xef') ergibt 'a%26%EF'.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

Ersetzt %xx-Escapes durch ihre Einzeichen-Entsprechung. Die optionalen Parameter encoding und errors geben an, wie prozent-kodierte Sequenzen in Unicode-Zeichen dekodiert werden sollen, wie sie von der Methode bytes.decode() akzeptiert werden.

string kann entweder ein str- oder ein bytes-Objekt sein.

encoding ist standardmäßig 'utf-8'. errors ist standardmäßig 'replace', was bedeutet, dass ungültige Sequenzen durch ein Platzhalterzeichen ersetzt werden.

Beispiel: unquote('/El%20Ni%C3%B1o/') ergibt '/El Niño/'.

Geändert in Version 3.9: Der Parameter string unterstützt Bytes- und str-Objekte (zuvor nur str).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

Ähnlich wie unquote(), ersetzt jedoch auch Pluszeichen durch Leerzeichen, wie es für das Dekodieren von HTML-Formularwerten erforderlich ist.

string muss ein str sein.

Beispiel: unquote_plus('/El+Ni%C3%B1o/') ergibt '/El Niño/'.

urllib.parse.unquote_to_bytes(string)

Ersetzt %xx-Escapes durch ihre Ein-Oktett-Entsprechung und gibt ein bytes-Objekt zurück.

string kann entweder ein str- oder ein bytes-Objekt sein.

Wenn es sich um ein str handelt, werden nicht kodierte Nicht-ASCII-Zeichen in string in UTF-8-Bytes kodiert.

Beispiel: unquote_to_bytes('a%26%EF') ergibt b'a&\xef'.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

Konvertiert ein Mapping-Objekt oder eine Sequenz von Tupeln mit zwei Elementen, die str- oder bytes-Objekte enthalten kann, in eine prozent-kodierte ASCII-Zeichenfolge. Wenn die resultierende Zeichenfolge als data für eine POST-Operation mit der Funktion urlopen() verwendet werden soll, sollte sie in Bytes kodiert werden, andernfalls führt dies zu einem TypeError.

Die resultierende Zeichenfolge ist eine Reihe von key=value-Paaren, die durch '&'-Zeichen getrennt sind, wobei sowohl key als auch value mit der quote_via-Funktion kodiert werden. Standardmäßig wird quote_plus() verwendet, um die Werte zu kodieren, was bedeutet, dass Leerzeichen als '+'-Zeichen kodiert und „/“-Zeichen als %2F kodiert werden, was dem Standard für GET-Anfragen (application/x-www-form-urlencoded) entspricht. Eine alternative Funktion, die als quote_via übergeben werden kann, ist quote(), die Leerzeichen als %20 kodiert und „/“-Zeichen nicht kodiert. Für maximale Kontrolle darüber, was kodiert wird, verwenden Sie quote und geben Sie einen Wert für safe an.

Wenn eine Sequenz von Tupeln mit zwei Elementen als query-Argument verwendet wird, ist das erste Element jedes Tupels ein Schlüssel und das zweite ein Wert. Das Wertelement selbst kann eine Sequenz sein, und in diesem Fall werden, wenn der optionale Parameter doseq zu True ausgewertet wird, einzelne key=value-Paare, getrennt durch '&', für jedes Element der Wertsequenz für den Schlüssel generiert. Die Reihenfolge der Parameter in der kodierten Zeichenfolge entspricht der Reihenfolge der Parameter-Tupel in der Sequenz.

Die Parameter safe, encoding und errors werden an quote_via weitergegeben (die Parameter encoding und errors werden nur weitergegeben, wenn ein Query-Element ein str ist).

Um diesen Kodierungsprozess umzukehren, werden in diesem Modul parse_qs() und parse_qsl() bereitgestellt, um Abfragezeichenfolgen in Python-Datenstrukturen zu parsen.

Siehe urllib-Beispiele, um zu erfahren, wie die Methode urllib.parse.urlencode() zum Erstellen der Abfragezeichenfolge einer URL oder von Daten für eine POST-Anfrage verwendet werden kann.

Geändert in Version 3.2: query unterstützt Bytes- und String-Objekte.

Geändert in Version 3.5: Der Parameter quote_via wurde hinzugefügt.

Veraltet seit Version 3.14: Das Akzeptieren von Objekten mit falschen Werten (wie 0 und []) außer leeren Zeichenketten und byte-ähnlichen Objekten und None ist jetzt veraltet.

Siehe auch

WHATWG - URL Living Standard

Arbeitsgruppe für den URL-Standard, die URLs, Domänen, IP-Adressen, das Format application/x-www-form-urlencoded und ihre APIs definiert.

RFC 3986 - Uniform Resource Identifiers

Dies ist der aktuelle Standard (STD66). Jegliche Änderungen am Modul urllib.parse sollten diesem entsprechen. Bestimmte Abweichungen sind möglich, die meist aus Gründen der Abwärtskompatibilität und für bestimmte De-facto-Parsing-Anforderungen, wie sie üblicherweise in großen Browsern beobachtet werden, erfolgen.

RFC 2732 - Format für Literal-IPv6-Adressen in URLs.

Dies spezifiziert die Parsing-Anforderungen von IPv6-URLs.

RFC 2396 - Uniform Resource Identifiers (URI): Generische Syntax

Dokument, das die generischen syntaktischen Anforderungen für Uniform Resource Names (URNs) und Uniform Resource Locators (URLs) beschreibt.

RFC 2368 - Das mailto-URL-Schema.

Parsing-Anforderungen für mailto-URL-Schemata.

RFC 1808 - Relative Uniform Resource Locators

Diese Request For Comments enthält die Regeln für die Verknüpfung einer absoluten und einer relativen URL, einschließlich einer beträchtlichen Anzahl von „ungewöhnlichen Beispielen“, die die Behandlung von Grenzfällen regeln.

RFC 1738 - Uniform Resource Locators (URL)

Dies spezifiziert die formale Syntax und Semantik von absoluten URLs.