`urllib.request` — Erweitert erweiterbare Bibliothek zum Öffnen von URLs¶

Quellcode: Lib/urllib/request.py

Das Modul urllib.request definiert Funktionen und Klassen, die beim Öffnen von URLs (hauptsächlich HTTP) in einer komplexen Welt helfen — grundlegende und Digest-Authentifizierung, Umleitungen, Cookies und mehr.

Siehe auch

Das Requests-Paket wird für eine höherwertige HTTP-Client-Schnittstelle empfohlen.

Warnung

Auf macOS ist es unsicher, dieses Modul in Programmen zu verwenden, die os.fork() verwenden, da die getproxies()-Implementierung für macOS eine höherwertige System-API verwendet. Setzen Sie die Umgebungsvariable no_proxy auf *, um dieses Problem zu vermeiden (z. B. os.environ["no_proxy"] = "*").

Verfügbarkeit: nicht WASI.

Dieses Modul funktioniert nicht oder ist nicht auf WebAssembly verfügbar. Weitere Informationen finden Sie unter WebAssembly-Plattformen.

Das Modul urllib.request definiert die folgenden Funktionen

urllib.request.urlopen(url, data=None, [timeout, ]*, context=None)¶

Öffnet url, was entweder eine Zeichenkette mit einer gültigen, korrekt kodierten URL oder ein Request-Objekt sein kann.

data muss ein Objekt sein, das zusätzliche Daten angibt, die an den Server gesendet werden sollen, oder None, wenn keine solchen Daten benötigt werden. Siehe Request für Details.

Das Modul urllib.request verwendet HTTP/1.1 und schließt den Header Connection:close in seinen HTTP-Anfragen ein.

Der optionale Parameter timeout gibt eine Zeitspanne in Sekunden für blockierende Operationen wie den Verbindungsversuch an (wenn nicht angegeben, wird die globale Standard-Timeout-Einstellung verwendet). Dies funktioniert tatsächlich nur für HTTP-, HTTPS- und FTP-Verbindungen.

Wenn context angegeben ist, muss es eine Instanz von ssl.SSLContext sein, die die verschiedenen SSL-Optionen beschreibt. Weitere Details finden Sie unter HTTPSConnection.

Diese Funktion gibt immer ein Objekt zurück, das als Kontextmanager arbeiten kann und die Eigenschaften url, headers und status hat. Weitere Details zu diesen Eigenschaften finden Sie unter urllib.response.addinfourl.

Für HTTP- und HTTPS-URLs gibt diese Funktion ein leicht modifiziertes Objekt von http.client.HTTPResponse zurück. Zusätzlich zu den drei neuen Methoden oben enthält das Attribut msg dieselben Informationen wie das Attribut reason — die vom Server zurückgegebene Begründungsphrase — anstelle der Antwort-Header, wie es in der Dokumentation für HTTPResponse angegeben ist.

Für FTP-, Datei- und Daten-URLs gibt diese Funktion ein Objekt von urllib.response.addinfourl zurück.

Löst URLError bei Protokollfehlern aus.

Beachten Sie, dass None zurückgegeben werden kann, wenn kein Handler die Anfrage bearbeitet (obwohl der standardmäßig installierte globale OpenerDirector UnknownHandler verwendet, um sicherzustellen, dass dies nie geschieht).

Zusätzlich, wenn Proxy-Einstellungen erkannt werden (z. B. wenn eine Umgebungsvariable *_proxy wie http_proxy gesetzt ist), wird ProxyHandler standardmäßig installiert und stellt sicher, dass die Anfragen über den Proxy bearbeitet werden.

Die veraltete Funktion urllib.urlopen aus Python 2.6 und früher wurde eingestellt; urllib.request.urlopen() entspricht dem alten urllib2.urlopen. Die Proxy-Verarbeitung, die durch Übergabe eines Dictionary-Parameters an urllib.urlopen erfolgte, kann durch die Verwendung von Objekten von ProxyHandler erreicht werden.

Der Standard-Opener löst ein Audit-Ereignis urllib.Request mit den Argumenten fullurl, data, headers, method aus, die aus dem Anfrageobjekt stammen.

Geändert in Version 3.2: cafile und capath wurden hinzugefügt.

HTTPS-Virtual-Hosts werden jetzt unterstützt, wenn möglich (d. h. wenn ssl.HAS_SNI wahr ist).

data kann ein iterierbares Objekt sein.

Geändert in Version 3.3: cadefault wurde hinzugefügt.

Geändert in Version 3.4.3: context wurde hinzugefügt.

Geändert in Version 3.10: HTTPS-Verbindungen senden jetzt eine ALPN-Erweiterung mit dem Protokollindikator http/1.1, wenn kein context angegeben ist. Benutzerdefinierte context sollten ALPN-Protokolle mit set_alpn_protocols() festlegen.

Geändert in Version 3.13: Entferne Parameter cafile, capath und cadefault: verwende stattdessen den Parameter context.

urllib.request.install_opener(opener)¶: Installiert eine Instanz von OpenerDirector als globalen Standard-Opener. Die Installation eines Openers ist nur notwendig, wenn Sie möchten, dass urlopen diesen Opener verwendet; andernfalls rufen Sie einfach OpenerDirector.open() anstelle von urlopen() auf. Der Code prüft nicht auf einen echten OpenerDirector, und jede Klasse mit der entsprechenden Schnittstelle funktioniert.

urllib.request.build_opener([handler, ...])¶

Gibt eine Instanz von OpenerDirector zurück, die die Handler in der angegebenen Reihenfolge verknüpft. handler können entweder Instanzen von BaseHandler oder Unterklassen von BaseHandler sein (in diesem Fall muss der Konstruktor ohne Parameter aufgerufen werden können). Instanzen der folgenden Klassen stehen vor den handlern, es sei denn, die handler enthalten sie, Instanzen davon oder Unterklassen davon: ProxyHandler (wenn Proxy-Einstellungen erkannt werden), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor.

Wenn die Python-Installation über SSL-Unterstützung verfügt (d. h. wenn das Modul ssl importiert werden kann), wird auch HTTPSHandler hinzugefügt.

Eine Unterklasse von BaseHandler kann auch ihr Attribut handler_order ändern, um ihre Position in der Handlerliste zu beeinflussen.

urllib.request.pathname2url(path, *, add_scheme=False)¶

Konvertiert den gegebenen lokalen Pfad in eine file:-URL. Diese Funktion verwendet die Funktion quote(), um den Pfad zu kodieren.

Wenn add_scheme falsch ist (Standard), lässt der Rückgabewert das Präfix file: weg. Setzen Sie add_scheme auf wahr, um eine vollständige URL zurückzugeben.

Dieses Beispiel zeigt die Verwendung der Funktion unter Windows

>>> from urllib.request import pathname2url
>>> path = 'C:\\Program Files'
>>> pathname2url(path, add_scheme=True)
'file:///C:/Program%20Files'

Geändert in Version 3.14: Windows-Laufwerksbuchstaben werden nicht mehr in Großbuchstaben umgewandelt, und :-Zeichen, die nicht auf einen Laufwerksbuchstaben folgen, führen unter Windows nicht mehr zu einer OSError-Ausnahme.

Geändert in Version 3.14: Pfade, die mit einem Schrägstrich beginnen, werden in URLs mit Autoritätsteilen konvertiert. Zum Beispiel wird der Pfad /etc/hosts in die URL ///etc/hosts konvertiert.

Geändert in Version 3.14: Der Parameter add_scheme wurde hinzugefügt.

urllib.request.url2pathname(url, *, require_scheme=False, resolve_host=False)¶

Konvertiert die gegebene file:-URL in einen lokalen Pfad. Diese Funktion verwendet die Funktion unquote(), um die URL zu dekodieren.

Wenn require_scheme falsch ist (Standard), sollte der gegebene Wert ein file:-Präfix weglassen. Wenn require_scheme auf wahr gesetzt ist, sollte der gegebene Wert das Präfix enthalten; eine URLError wird ausgelöst, wenn dies nicht der Fall ist.

Die URL-Autorität wird verworfen, wenn sie leer ist, localhost oder der lokale Hostname ist. Andernfalls, wenn resolve_host auf wahr gesetzt ist, wird die Autorität mit socket.gethostbyname() aufgelöst und verworfen, wenn sie mit einer lokalen IP-Adresse übereinstimmt (gemäß RFC 8089 §3). Wenn die Autorität immer noch nicht behandelt wird, wird unter Windows ein UNC-Pfad zurückgegeben, und auf anderen Plattformen wird eine URLError ausgelöst.

Dieses Beispiel zeigt die Verwendung der Funktion unter Windows

>>> from urllib.request import url2pathname
>>> url = 'file:///C:/Program%20Files'
>>> url2pathname(url, require_scheme=True)
'C:\\Program Files'

Geändert in Version 3.14: Windows-Laufwerksbuchstaben werden nicht mehr in Großbuchstaben umgewandelt, und :-Zeichen, die nicht auf einen Laufwerksbuchstaben folgen, führen unter Windows nicht mehr zu einer OSError-Ausnahme.

Geändert in Version 3.14: Die URL-Autorität wird verworfen, wenn sie mit dem lokalen Hostnamen übereinstimmt. Andernfalls, wenn die Autorität nicht leer oder localhost ist, wird unter Windows ein UNC-Pfad zurückgegeben (wie zuvor), und auf anderen Plattformen wird eine URLError ausgelöst.

Geändert in Version 3.14: Die URL-Abfrage- und Fragmentteile werden verworfen, wenn sie vorhanden sind.

Geändert in Version 3.14: Die Parameter require_scheme und resolve_host wurden hinzugefügt.

urllib.request.getproxies()¶: Diese Hilfsfunktion gibt ein Dictionary von Schema-zu-Proxy-Server-URL-Zuordnungen zurück. Sie scannt die Umgebung nach Variablen mit den Namen <schema>_proxy, unabhängig von der Groß-/Kleinschreibung, für alle Betriebssysteme zuerst, und wenn sie keine findet, sucht sie nach Proxy-Informationen aus der Systemkonfiguration für macOS und der Windows-Systemregistrierung für Windows. Wenn sowohl Kleinbuchstaben als auch Großbuchstaben der Umgebungsvariablen existieren (und sich widersprechen), werden Kleinbuchstaben bevorzugt.

Hinweis

Wenn die Umgebungsvariable REQUEST_METHOD gesetzt ist, was normalerweise darauf hinweist, dass Ihr Skript in einer CGI-Umgebung ausgeführt wird, wird die Umgebungsvariable HTTP_PROXY (Großbuchstaben _PROXY) ignoriert. Dies liegt daran, dass diese Variable von einem Client über den HTTP-Header "Proxy:" injiziert werden kann. Wenn Sie einen HTTP-Proxy in einer CGI-Umgebung verwenden müssen, verwenden Sie entweder explizit ProxyHandler oder stellen Sie sicher, dass der Variablenname in Kleinbuchstaben vorliegt (oder zumindest das Suffix _proxy).

Die folgenden Klassen werden bereitgestellt

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)¶

Diese Klasse ist eine Abstraktion einer URL-Anfrage.

url sollte eine Zeichenkette mit einer gültigen, korrekt kodierten URL sein.

data muss ein Objekt sein, das zusätzliche Daten für den Versand an den Server angibt, oder None, wenn keine solchen Daten benötigt werden. Derzeit sind nur HTTP-Anfragen die einzigen, die data verwenden. Die unterstützten Objekttypen umfassen Bytes, dateiähnliche Objekte und Iteratoren von bytes-ähnlichen Objekten. Wenn kein Headerfeld Content-Length oder Transfer-Encoding angegeben wurde, setzt HTTPHandler diese Header entsprechend dem Typ von data. Content-Length wird zum Senden von Byte-Objekten verwendet, während Transfer-Encoding: chunked gemäß RFC 7230, Abschnitt 3.3.1, zum Senden von Dateien und anderen Iterierbaren verwendet wird.

Für eine HTTP-POST-Anfragemethode sollte data ein Puffer im Standardformat application/x-www-form-urlencoded sein. Die Funktion urllib.parse.urlencode() nimmt eine Zuordnung oder Sequenz von 2-Tupeln und gibt eine ASCII-Zeichenkette in diesem Format zurück. Sie sollte in Bytes kodiert werden, bevor sie als Parameter data verwendet wird.

headers sollte ein Dictionary sein und so behandelt werden, als ob add_header() mit jedem Schlüssel und Wert als Argumente aufgerufen worden wäre. Dies wird oft verwendet, um den Wert des Headers User-Agent zu "spoofen", der von einem Browser zur Identifizierung verwendet wird – einige HTTP-Server erlauben nur Anfragen, die von gängigen Browsern stammen, im Gegensatz zu Skripten. Zum Beispiel könnte Mozilla Firefox sich als "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11" identifizieren, während die Standard-User-Agent-Zeichenkette von urllib "Python-urllib/2.6" ist (unter Python 2.6). Alle Header-Schlüssel werden in Camel Case gesendet.

Ein geeigneter Header Content-Type sollte enthalten sein, wenn das Argument data vorhanden ist. Wenn dieser Header nicht bereitgestellt wurde und data nicht None ist, wird Content-Type: application/x-www-form-urlencoded als Standard hinzugefügt.

Die nächsten beiden Argumente sind nur für die korrekte Verarbeitung von Drittanbieter-HTTP-Cookies von Interesse

origin_req_host sollte der Request-Host der ursprünglichen Transaktion sein, wie in RFC 2965 definiert. Er ist standardmäßig http.cookiejar.request_host(self). Dies ist der Hostname oder die IP-Adresse der ursprünglichen Anfrage, die vom Benutzer initiiert wurde. Wenn die Anfrage beispielsweise nach einem Bild in einem HTML-Dokument gestellt wird, sollte dies der Request-Host der Anfrage für die Seite sein, die das Bild enthält.

unverifiable sollte angeben, ob die Anfrage unverifizierbar ist, wie in RFC 2965 definiert. Sie ist standardmäßig False. Eine unverifizierbare Anfrage ist eine, deren URL der Benutzer nicht genehmigen konnte. Wenn die Anfrage beispielsweise nach einem Bild in einem HTML-Dokument gestellt wird und der Benutzer keine Möglichkeit hatte, das automatische Abrufen des Bildes zu genehmigen, sollte dies wahr sein.

method sollte eine Zeichenkette sein, die die zu verwendende HTTP-Anfragemethode angibt (z. B. 'HEAD'). Wenn sie angegeben ist, wird ihr Wert im Attribut method gespeichert und von get_method() verwendet. Standardmäßig ist 'GET', wenn data None ist, und 'POST' andernfalls. Unterklassen können eine andere Standardmethode angeben, indem sie das Attribut method in der Klasse selbst festlegen.

Hinweis

Die Anfrage funktioniert nicht wie erwartet, wenn das Datenobjekt seinen Inhalt nicht mehr als einmal liefern kann (z. B. eine Datei oder ein Iterator, der den Inhalt nur einmal produzieren kann) und die Anfrage aufgrund von HTTP-Umleitungen oder Authentifizierung erneut versucht wird. Die data werden unmittelbar nach den Headern an den HTTP-Server gesendet. Es gibt keine Unterstützung für eine 100-Continue-Erwartung in der Bibliothek.

Geändert in Version 3.3: Das Argument Request.method wurde der Klasse Request hinzugefügt.

Geändert in Version 3.4: Die Standardmethode Request.method kann auf Klassenebene angegeben werden.

Geändert in Version 3.6: Es wird kein Fehler ausgelöst, wenn Content-Length nicht angegeben wurde und data weder None noch ein Byte-Objekt ist. Es wird stattdessen auf die Verwendung von Chunked Transfer Encoding zurückgegriffen.

class urllib.request.OpenerDirector¶: Die Klasse OpenerDirector öffnet URLs über verknüpfte BaseHandler. Sie verwaltet die Verkettung von Handlern und die Wiederherstellung von Fehlern.

class urllib.request.BaseHandler¶: Dies ist die Basisklasse für alle registrierten Handler – und behandelt nur die einfache Mechanik der Registrierung.

class urllib.request.HTTPDefaultErrorHandler¶: Eine Klasse, die einen Standard-Handler für HTTP-Fehlerantworten definiert; alle Antworten werden in HTTPError-Ausnahmen umgewandelt.

class urllib.request.HTTPRedirectHandler¶: Eine Klasse zur Behandlung von Weiterleitungen.

class urllib.request.HTTPCookieProcessor(cookiejar=None)¶: Eine Klasse zur Behandlung von HTTP-Cookies.

class urllib.request.ProxyHandler(proxies=None)¶

Bewirkt, dass Anfragen über einen Proxy laufen. Wenn proxies angegeben ist, muss es ein Dictionary sein, das Protokollnamen auf Proxy-URLs abbildet. Standardmäßig wird die Liste der Proxys aus den Umgebungsvariablen <protocol>_proxy gelesen. Wenn keine Proxy-Umgebungsvariablen gesetzt sind, werden in einer Windows-Umgebung Proxy-Einstellungen aus der Registrierung im Abschnitt Internet-Einstellungen abgerufen, und in einer macOS-Umgebung werden Proxy-Informationen aus dem Systemkonfigurations-Framework bezogen.

Um automatisch erkannte Proxys zu deaktivieren, übergeben Sie ein leeres Dictionary.

Die Umgebungsvariable no_proxy kann verwendet werden, um Hosts anzugeben, die nicht über einen Proxy erreicht werden sollen; wenn sie gesetzt ist, sollte sie eine durch Kommas getrennte Liste von Hostnamen-Suffixen sein, optional mit angehängtem :port, z. B. cern.ch,ncsa.uiuc.edu,some.host:8080.

Hinweis

HTTP_PROXY wird ignoriert, wenn eine Variable REQUEST_METHOD gesetzt ist; siehe die Dokumentation zu getproxies().

class urllib.request.HTTPPasswordMgr¶: Verwaltet eine Datenbank von (realm, uri) -> (user, password)-Zuordnungen.

class urllib.request.HTTPPasswordMgrWithDefaultRealm¶: Verwaltet eine Datenbank von (realm, uri) -> (user, password)-Zuordnungen. Ein Realm von None gilt als Catch-all-Realm, der durchsucht wird, wenn kein anderer Realm passt.

class urllib.request.HTTPPasswordMgrWithPriorAuth¶: Eine Variante von HTTPPasswordMgrWithDefaultRealm, die auch eine Datenbank von uri -> is_authenticated-Zuordnungen enthält. Kann von einem BasicAuth-Handler verwendet werden, um zu bestimmen, wann Anmeldeinformationen sofort gesendet werden sollen, anstatt zuerst auf eine 401-Antwort zu warten.

Hinzugefügt in Version 3.5.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)¶: Dies ist eine Mixin-Klasse, die bei der HTTP-Authentifizierung sowohl gegenüber dem entfernten Host als auch gegenüber einem Proxy hilft. password_mgr, falls angegeben, sollte etwas sein, das mit HTTPPasswordMgr kompatibel ist; siehe Abschnitt HTTPPasswordMgr-Objekte für Informationen über die zu unterstützende Schnittstelle. Wenn passwd_mgr auch die Methoden is_authenticated und update_authenticated bereitstellt (siehe HTTPPasswordMgrWithPriorAuth-Objekte), verwendet der Handler das Ergebnis von is_authenticated für eine gegebene URI, um zu bestimmen, ob Authentifizierungsdaten mit der Anfrage gesendet werden sollen oder nicht. Wenn is_authenticated True für die URI zurückgibt, werden Anmeldeinformationen gesendet. Wenn is_authenticated False ist, werden keine Anmeldeinformationen gesendet, und wenn eine 401-Antwort empfangen wird, wird die Anfrage mit den Authentifizierungsdaten erneut gesendet. Wenn die Authentifizierung erfolgreich ist, wird update_authenticated aufgerufen, um is_authenticated für die URI auf True zu setzen, sodass nachfolgende Anfragen an die URI oder deren übergeordnete URIs automatisch die Authentifizierungsdaten enthalten.

Hinzugefügt in Version 3.5: Unterstützung für is_authenticated hinzugefügt.

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)¶: Behandelt die Authentifizierung beim entfernten Host. password_mgr sollte, falls angegeben, etwas sein, das mit HTTPPasswordMgr kompatibel ist; siehe Abschnitt HTTPPasswordMgr-Objekte für Informationen über die zu unterstützende Schnittstelle. HTTPBasicAuthHandler löst einen ValueError aus, wenn ein falsches Authentifizierungsschema präsentiert wird.

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)¶: Behandelt die Authentifizierung beim Proxy. password_mgr sollte, falls angegeben, etwas sein, das mit HTTPPasswordMgr kompatibel ist; siehe Abschnitt HTTPPasswordMgr-Objekte für Informationen über die zu unterstützende Schnittstelle.

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)¶: Dies ist eine Mixin-Klasse, die bei der HTTP-Authentifizierung sowohl gegenüber dem entfernten Host als auch gegenüber einem Proxy hilft. password_mgr sollte, falls angegeben, etwas sein, das mit HTTPPasswordMgr kompatibel ist; siehe Abschnitt HTTPPasswordMgr-Objekte für Informationen über die zu unterstützende Schnittstelle.

Geändert in Version 3.14: Unterstützung für den HTTP-Digest-Authentifizierungsalgorithmus SHA-256 hinzugefügt.

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)¶: Behandelt die Authentifizierung beim entfernten Host. password_mgr sollte, falls angegeben, etwas sein, das mit HTTPPasswordMgr kompatibel ist; siehe Abschnitt HTTPPasswordMgr-Objekte für Informationen über die zu unterstützende Schnittstelle. Wenn sowohl der Digest Authentication Handler als auch der Basic Authentication Handler hinzugefügt werden, wird immer zuerst die Digest Authentication versucht. Wenn die Digest Authentication erneut eine 40x-Antwort zurückgibt, wird sie an den Basic Authentication Handler gesendet, um sie zu behandeln. Diese Handler-Methode löst einen ValueError aus, wenn ein anderes Authentifizierungsschema als Digest oder Basic präsentiert wird.

Geändert in Version 3.3: Bei nicht unterstützten Authentifizierungsschemata wird ein ValueError ausgelöst.

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)¶: Behandelt die Authentifizierung beim Proxy. password_mgr sollte, falls angegeben, etwas sein, das mit HTTPPasswordMgr kompatibel ist; siehe Abschnitt HTTPPasswordMgr-Objekte für Informationen über die zu unterstützende Schnittstelle.

class urllib.request.HTTPHandler¶: Eine Klasse zur Handhabung der Öffnung von HTTP-URLs.

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)¶: Eine Klasse zur Handhabung der Öffnung von HTTPS-URLs. context und check_hostname haben dieselbe Bedeutung wie in http.client.HTTPSConnection.

Geändert in Version 3.2: context und check_hostname wurden hinzugefügt.

class urllib.request.FileHandler¶: Öffnet lokale Dateien.

class urllib.request.DataHandler¶: Öffnet Daten-URLs.

Hinzugefügt in Version 3.4.

class urllib.request.FTPHandler¶: Öffnet FTP-URLs.

class urllib.request.CacheFTPHandler¶: Öffnet FTP-URLs und hält einen Cache offener FTP-Verbindungen vor, um Verzögerungen zu minimieren.

class urllib.request.UnknownHandler¶: Eine Auffangkasse zur Handhabung unbekannter URLs.

class urllib.request.HTTPErrorProcessor¶: Verarbeitet HTTP-Fehlerantworten.

Request-Objekte¶

Die folgenden Methoden beschreiben die öffentliche Schnittstelle von Request und können daher in abgeleiteten Klassen überschrieben werden. Sie definiert auch mehrere öffentliche Attribute, die von Clients zur Inspektion der geparsten Anfrage verwendet werden können.

Request.full_url¶

Die ursprüngliche URL, die an den Konstruktor übergeben wurde.

Geändert in Version 3.4.

Request.full_url ist eine Eigenschaft mit Setter, Getter und Deleter. Das Abrufen von full_url gibt die ursprüngliche Anforderungs-URL mit Fragment zurück, falls vorhanden.

Request.type¶: Das URI-Schema.

Request.host¶: Die URI-Autorität, typischerweise ein Host, kann aber auch einen durch einen Doppelpunkt getrennten Port enthalten.

Request.origin_req_host¶: Der ursprüngliche Host für die Anfrage, ohne Port.

Request.selector¶: Der URI-Pfad. Wenn Request einen Proxy verwendet, dann ist selector die vollständige URL, die an den Proxy übergeben wird.

Request.data¶: Der Entitätshauptteil für die Anfrage oder None, falls nicht angegeben.

Geändert in Version 3.4: Das Ändern des Werts von Request.data löscht jetzt den Header "Content-Length", falls er zuvor gesetzt oder berechnet wurde.

Request.unverifiable¶: boolean, gibt an, ob die Anfrage gemäß RFC 2965 nicht verifizierbar ist.

Request.method¶: Die zu verwendende HTTP-Anfragemethode. Standardmäßig ist ihr Wert None, was bedeutet, dass get_method() die normale Berechnung der zu verwendenden Methode durchführt. Ihr Wert kann entweder durch Angabe eines Standardwerts auf Klassenebene in einer Request-Unterklasse oder durch Übergabe eines Werts an den Request-Konstruktor über das Argument method gesetzt werden (wodurch die Standardberechnung in get_method() überschrieben wird).

Hinzugefügt in Version 3.3.

Geändert in Version 3.4: Ein Standardwert kann jetzt in Unterklassen gesetzt werden; zuvor konnte er nur über das Konstruktorargument gesetzt werden.

Request.get_method()¶: Gibt eine Zeichenkette zurück, die die HTTP-Anfragemethode angibt. Wenn Request.method nicht None ist, wird sein Wert zurückgegeben, andernfalls wird 'GET' zurückgegeben, wenn Request.data None ist, oder 'POST', wenn es nicht so ist. Dies ist nur für HTTP-Anfragen sinnvoll.

Geändert in Version 3.3: get_method betrachtet nun den Wert von Request.method.

Request.add_header(key, val)¶: Fügt der Anfrage einen weiteren Header hinzu. Header werden derzeit von allen Handlern außer HTTP-Handlern ignoriert, wo sie zur Liste der an den Server gesendeten Header hinzugefügt werden. Beachten Sie, dass nicht mehr als ein Header mit demselben Namen vorhanden sein kann und spätere Aufrufe frühere Aufrufe überschreiben, falls key kollidiert. Derzeit ist dies kein Verlust an HTTP-Funktionalität, da alle Header, die bei mehrfacher Verwendung eine Bedeutung haben, eine (headerspezifische) Möglichkeit haben, dieselbe Funktionalität mit nur einem Header zu erlangen. Beachten Sie, dass über diese Methode hinzugefügte Header auch zu umgeleiteten Anfragen hinzugefügt werden.

Request.add_unredirected_header(key, header)¶: Fügt einen Header hinzu, der nicht zu einer umgeleiteten Anfrage hinzugefügt wird.

Request.has_header(header)¶: Gibt zurück, ob die Instanz den benannten Header hat (prüft sowohl reguläre als auch nicht umgeleitete).

Request.remove_header(header)¶: Entfernt den benannten Header aus der Anfrageinstanz (sowohl aus regulären als auch aus nicht umgeleiteten Headern).

Hinzugefügt in Version 3.4.

Request.get_full_url()¶

Gibt die im Konstruktor angegebene URL zurück.

Geändert in Version 3.4.

Gibt Request.full_url zurück.

Request.set_proxy(host, type)¶: Bereitet die Anfrage vor, indem sie sich mit einem Proxy-Server verbindet. host und type ersetzen die der Instanz, und der Selector der Instanz ist die ursprüngliche URL, die im Konstruktor angegeben wurde.

Request.get_header(header_name, default=None)¶: Gibt den Wert des angegebenen Headers zurück. Wenn der Header nicht vorhanden ist, wird der Standardwert zurückgegeben.

Request.header_items()¶: Gibt eine Liste von Tupeln (header_name, header_value) der Request-Header zurück.

Geändert in Version 3.4: Die Request-Methoden add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host und is_unverifiable, die seit 3.3 als veraltet markiert waren, wurden entfernt.

OpenerDirector-Objekte¶

OpenerDirector-Instanzen haben die folgenden Methoden

OpenerDirector.add_handler(handler)¶

handler sollte eine Instanz von BaseHandler sein. Die folgenden Methoden werden gesucht und zu den möglichen Ketten hinzugefügt (beachten Sie, dass HTTP-Fehler ein Sonderfall sind). Beachten Sie, dass in den folgenden Fällen protocol durch das tatsächliche zu behandelnde Protokoll ersetzt werden sollte, z. B. wäre http_response() der Protokollantwort-Handler für HTTP. Ebenso sollte type durch den tatsächlichen HTTP-Code ersetzt werden, z. B. würde http_error_404() HTTP 404-Fehler behandeln.

<protocol>_open() — signalisiert, dass der Handler weiß, wie protocol-URLs zu öffnen sind.

Siehe BaseHandler.<protocol>_open() für weitere Informationen.
http_error_<type>() — signalisiert, dass der Handler weiß, wie HTTP-Fehler mit dem HTTP-Fehlercode type zu behandeln sind.

Siehe BaseHandler.http_error_<nnn>() für weitere Informationen.
<protocol>_error() — signalisiert, dass der Handler weiß, wie Fehler von (nicht http) protocol zu behandeln sind.
<protocol>_request() — signalisiert, dass der Handler weiß, wie protocol-Anfragen vorzuverarbeiten sind.

Siehe BaseHandler.<protocol>_request() für weitere Informationen.
<protocol>_response() — signalisiert, dass der Handler weiß, wie protocol-Antworten nachzubearbeiten sind.

Siehe BaseHandler.<protocol>_response() für weitere Informationen.

OpenerDirector.open(url, data=None[, timeout])¶: Öffnet die gegebene url (die ein Request-Objekt oder eine Zeichenkette sein kann), wobei optional die gegebene data übergeben wird. Argumente, Rückgabewerte und ausgelöste Ausnahmen sind dieselben wie bei urlopen() (die einfach die Methode open() auf dem aktuell installierten globalen OpenerDirector aufruft). Das optionale Argument timeout gibt eine Zeitüberschreitung in Sekunden für blockierende Operationen wie den Verbindungsversuch an (falls nicht angegeben, wird die globale Standard-Timeout-Einstellung verwendet). Die Timeout-Funktion funktioniert tatsächlich nur für HTTP-, HTTPS- und FTP-Verbindungen.

OpenerDirector.error(proto, *args)¶

Behandelt einen Fehler des gegebenen Protokolls. Dies ruft die registrierten Fehlerhandler für das gegebene Protokoll mit den gegebenen Argumenten auf (die protokollspezifisch sind). Das HTTP-Protokoll ist ein Sonderfall, der den HTTP-Antwortcode verwendet, um den spezifischen Fehlerhandler zu bestimmen; siehe die Methoden http_error_<type>() der Handler-Klassen.

Rückgabewerte und ausgelöste Ausnahmen sind dieselben wie bei urlopen().

OpenerDirector-Objekte öffnen URLs in drei Schritten

Die Reihenfolge, in der diese Methoden in jedem Schritt aufgerufen werden, wird durch Sortieren der Handlerinstanzen bestimmt.

Jeder Handler mit einer Methode namens <protocol>_request() hat diese Methode aufgerufen, um die Anfrage vorzuverarbeiten.
Handler mit einer Methode namens <protocol>_open() werden aufgerufen, um die Anfrage zu bearbeiten. Dieser Schritt endet, wenn ein Handler entweder einen Wert zurückgibt, der nicht None ist (d. h. eine Antwort), oder eine Ausnahme auslöst (normalerweise URLError). Ausnahmen dürfen propagieren.

Tatsächlich wird der obige Algorithmus zuerst für Methoden namens default_open() versucht. Wenn alle diese Methoden None zurückgeben, wird der Algorithmus für Methoden namens <protocol>_open() wiederholt. Wenn alle diese Methoden None zurückgeben, wird der Algorithmus für Methoden namens unknown_open() wiederholt.

Beachten Sie, dass die Implementierung dieser Methoden Aufrufe der übergeordneten OpenerDirector-Instanzmethoden open() und error() beinhalten können.
Jeder Handler mit einer Methode namens <protocol>_response() hat diese Methode aufgerufen, um die Antwort nachzubearbeiten.

BaseHandler-Objekte¶

BaseHandler-Objekte stellen einige direkt nützliche Methoden sowie andere zur Verfügung, die für abgeleitete Klassen bestimmt sind. Diese sind für die direkte Verwendung gedacht.

BaseHandler.add_parent(director)¶: Fügt einen Director als Eltern hinzu.

BaseHandler.close()¶: Entfernt alle Eltern.

Das folgende Attribut und die folgenden Methoden sollten nur von von BaseHandler abgeleiteten Klassen verwendet werden.

Hinweis

Die Konvention wurde angenommen, dass Unterklassen, die Methoden wie <protocol>_request() oder <protocol>_response() definieren, als *Processor benannt werden; alle anderen werden als *Handler benannt.

BaseHandler.parent¶: Ein gültiger OpenerDirector, der verwendet werden kann, um mit einem anderen Protokoll zu öffnen oder Fehler zu behandeln.

BaseHandler.default_open(req)¶

Diese Methode ist in BaseHandler *nicht* definiert, aber Unterklassen sollten sie definieren, wenn sie alle URLs abfangen wollen.

Diese Methode wird, falls implementiert, vom übergeordneten OpenerDirector aufgerufen. Sie sollte ein dateiähnliches Objekt zurückgeben, wie in der Rückgabe von open() von OpenerDirector beschrieben, oder None. Sie sollte URLError auslösen, es sei denn, es tritt etwas wirklich Außergewöhnliches auf (z. B. sollte MemoryError nicht auf URLError abgebildet werden).

Diese Methode wird vor jeder protokollspezifischen Öffnungsmethode aufgerufen.

BaseHandler.<protocol>_open(req)

Diese Methode ist in BaseHandler *nicht* definiert, aber Unterklassen sollten sie definieren, wenn sie URLs mit dem gegebenen Protokoll behandeln wollen.

Diese Methode wird, falls definiert, vom übergeordneten OpenerDirector aufgerufen. Die Rückgabewerte sollten dieselben sein wie für default_open().

BaseHandler.unknown_open(req)¶

Diese Methode ist in BaseHandler *nicht* definiert, aber Unterklassen sollten sie definieren, wenn sie alle URLs abfangen wollen, für die kein spezifischer registrierter Handler zum Öffnen vorhanden ist.

Diese Methode wird, falls implementiert, vom parent OpenerDirector aufgerufen. Die Rückgabewerte sollten dieselben sein wie für default_open().

BaseHandler.http_error_default(req, fp, code, msg, hdrs)¶

Diese Methode ist in BaseHandler *nicht* definiert, aber Unterklassen sollten sie überschreiben, wenn sie eine Sammelstelle für ansonsten unbehandelte HTTP-Fehler bereitstellen möchten. Sie wird automatisch vom OpenerDirector aufgerufen, der den Fehler erhält, und sollte normalerweise nicht unter anderen Umständen aufgerufen werden.

OpenerDirector ruft diese Methode mit fünf Positionsargumenten auf:

ein Request-Objekt,
ein dateiähnliches Objekt mit dem HTTP-Fehlerinhalt,
den dreistelligen Code des Fehlers als Zeichenkette,
die für den Benutzer sichtbare Erklärung des Codes als Zeichenkette und
die Header des Fehlers als Mapping-Objekt.

Rückgabewerte und ausgelöste Ausnahmen sollten dieselben sein wie bei urlopen().

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn sollte ein dreistelliger HTTP-Fehlercode sein. Diese Methode ist ebenfalls nicht in BaseHandler definiert, wird aber, falls sie existiert, auf einer Instanz einer Unterklasse aufgerufen, wenn ein HTTP-Fehler mit dem Code nnn auftritt.

Unterklassen sollten diese Methode überschreiben, um spezifische HTTP-Fehler zu behandeln.

Argumente, Rückgabewerte und ausgelöste Ausnahmen sollten dieselben sein wie für http_error_default().

BaseHandler.<protocol>_request(req)

Diese Methode ist in BaseHandler *nicht* definiert, aber Unterklassen sollten sie definieren, wenn sie Anfragen des gegebenen Protokolls vorverarbeiten möchten.

Diese Methode wird, falls definiert, vom übergeordneten OpenerDirector aufgerufen. req ist ein Request-Objekt. Der Rückgabewert sollte ein Request-Objekt sein.

BaseHandler.<protocol>_response(req, response)

Diese Methode ist in BaseHandler *nicht* definiert, aber Unterklassen sollten sie definieren, wenn sie Antworten des gegebenen Protokolls nachverarbeiten möchten.

Diese Methode wird, falls definiert, vom übergeordneten OpenerDirector aufgerufen. req ist ein Request-Objekt. response ist ein Objekt, das dieselbe Schnittstelle wie der Rückgabewert von urlopen() implementiert. Der Rückgabewert sollte dieselbe Schnittstelle implementieren wie der Rückgabewert von urlopen().

HTTPRedirectHandler Objekte¶

Hinweis

Einige HTTP-Umleitungen erfordern eine Aktion vom Client-Code dieses Moduls. Wenn dies der Fall ist, wird HTTPError ausgelöst. Einzelheiten zu den genauen Bedeutungen der verschiedenen Umleitungscodes finden Sie in RFC 2616.

Eine HTTPError Ausnahme wird aus Sicherheitsgründen ausgelöst, wenn dem HTTPRedirectHandler eine umgeleitete URL präsentiert wird, die keine HTTP-, HTTPS- oder FTP-URL ist.

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)¶: Gibt ein Request-Objekt oder None als Antwort auf eine Umleitung zurück. Diese Methode wird von den Standardimplementierungen der Methoden http_error_30*() aufgerufen, wenn eine Umleitung vom Server empfangen wird. Wenn eine Umleitung stattfinden soll, geben Sie ein neues Request-Objekt zurück, damit http_error_30*() die Umleitung zu newurl durchführen kann. Andernfalls lösen Sie HTTPError aus, wenn kein anderer Handler diese URL versuchen soll zu behandeln, oder geben Sie None zurück, wenn Sie es nicht können, aber ein anderer Handler dies möglicherweise tun könnte.

Hinweis

Die Standardimplementierung dieser Methode folgt nicht strikt RFC 2616, die besagt, dass 301- und 302-Antworten auf POST-Anfragen nicht automatisch umgeleitet werden dürfen, ohne Bestätigung durch den Benutzer. In der Realität erlauben Browser die automatische Umleitung dieser Antworten, indem sie POST in GET ändern, und die Standardimplementierung reproduziert dieses Verhalten.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)¶: Umleitung zur Location: oder URI: URL. Diese Methode wird vom übergeordneten OpenerDirector aufgerufen, wenn eine HTTP-'moved permanently'-Antwort empfangen wird.

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)¶: Dasselbe wie http_error_301(), aber aufgerufen für die 'found'-Antwort.

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)¶: Dasselbe wie http_error_301(), aber aufgerufen für die 'see other'-Antwort.

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)¶: Dasselbe wie http_error_301(), aber aufgerufen für die 'temporary redirect'-Antwort. Es erlaubt nicht die Änderung der Request-Methode von POST zu GET.

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)¶: Dasselbe wie http_error_301(), aber aufgerufen für die 'permanent redirect'-Antwort. Es erlaubt nicht die Änderung der Request-Methode von POST zu GET.

Hinzugefügt in Version 3.11.

HTTPCookieProcessor Objekte¶

Instanzen von HTTPCookieProcessor haben ein Attribut:

HTTPCookieProcessor.cookiejar¶: Der http.cookiejar.CookieJar, in dem Cookies gespeichert werden.

ProxyHandler Objekte¶

ProxyHandler.<protocol>_open(request): Der ProxyHandler hat eine Methode <protocol>_open() für jedes Protokoll, für das ein Proxy im proxies-Wörterbuch des Konstruktors vorhanden ist. Die Methode modifiziert Anfragen, um über den Proxy geleitet zu werden, indem sie request.set_proxy() aufruft, und ruft den nächsten Handler in der Kette auf, um das Protokoll tatsächlich auszuführen.

HTTPPasswordMgr Objekte¶

Diese Methoden sind auf Objekten von HTTPPasswordMgr und HTTPPasswordMgrWithDefaultRealm verfügbar.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)¶: uri kann entweder eine einzelne URI oder eine Sequenz von URIs sein. realm, user und passwd müssen Zeichenketten sein. Dies bewirkt, dass (user, passwd) als Authentifizierungs-Tokens verwendet werden, wenn eine Authentifizierung für realm und eine Super-URI einer der angegebenen URIs erfolgt.

HTTPPasswordMgr.find_user_password(realm, authuri)¶

Holt Benutzername/Passwort für den gegebenen Realm und die URI, falls vorhanden. Diese Methode gibt (None, None) zurück, wenn kein passender Benutzer/Passwort vorhanden ist.

Bei HTTPPasswordMgrWithDefaultRealm-Objekten wird der Realm None durchsucht, wenn der angegebene realm keinen passenden Benutzer/Passwort hat.

HTTPPasswordMgrWithPriorAuth Objekte¶

Dieser Passwortmanager erweitert HTTPPasswordMgrWithDefaultRealm, um das Nachverfolgen von URIs zu unterstützen, für die Authentifizierungsanmeldedaten immer gesendet werden sollen.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)¶: realm, uri, user, passwd sind wie bei HTTPPasswordMgr.add_password(). is_authenticated setzt den anfänglichen Wert des Flags is_authenticated für die gegebene URI oder Liste von URIs. Wenn is_authenticated als True angegeben wird, wird realm ignoriert.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)¶: Dasselbe wie bei HTTPPasswordMgrWithDefaultRealm-Objekten.

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)¶: Aktualisiert das Flag is_authenticated für die gegebene uri oder Liste von URIs.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)¶: Gibt den aktuellen Status des Flags is_authenticated für die gegebene URI zurück.

AbstractBasicAuthHandler Objekte¶

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶

Behandelt eine Authentifizierungsanfrage, indem ein Benutzer-/Passwortpaar abgerufen und die Anfrage erneut versucht wird. authreq sollte der Name des Headers sein, in dem die Informationen über den Realm in der Anfrage enthalten sind, host gibt die URL und den Pfad an, für den authentifiziert werden soll, req sollte das (fehlgeschlagene) Request-Objekt sein, und headers sollten die Fehler-Header sein.

host ist entweder eine Autorität (z. B. "python.org") oder eine URL, die eine Autoritätskomponente enthält (z. B. "https://pythonlang.de/"). In beiden Fällen darf die Autorität keine Userinfo-Komponente enthalten (daher sind "python.org" und "python.org:80" in Ordnung, "joe:password@python.org" jedoch nicht).

HTTPBasicAuthHandler Objekte¶

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶: Versucht die Anfrage mit Authentifizierungsinformationen erneut, falls verfügbar.

ProxyBasicAuthHandler Objekte¶

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶: Versucht die Anfrage mit Authentifizierungsinformationen erneut, falls verfügbar.

AbstractDigestAuthHandler Objekte¶

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶: authreq sollte der Name des Headers sein, in dem die Informationen über den Realm in der Anfrage enthalten sind, host sollte der zu authentifizierende Host sein, req sollte das (fehlgeschlagene) Request-Objekt sein, und headers sollten die Fehler-Header sein.

HTTPDigestAuthHandler Objekte¶

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶: Versucht die Anfrage mit Authentifizierungsinformationen erneut, falls verfügbar.

ProxyDigestAuthHandler Objekte¶

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶: Versucht die Anfrage mit Authentifizierungsinformationen erneut, falls verfügbar.

HTTPHandler Objekte¶

HTTPHandler.http_open(req)¶: Sendet eine HTTP-Anfrage, die entweder GET oder POST sein kann, abhängig von req.data.

HTTPSHandler Objekte¶

HTTPSHandler.https_open(req)¶: Sendet eine HTTPS-Anfrage, die entweder GET oder POST sein kann, abhängig von req.data.

FileHandler Objekte¶

FileHandler.file_open(req)¶: Öffnet die Datei lokal, wenn kein Hostname vorhanden ist oder der Hostname 'localhost' ist.

Geändert in Version 3.2: Diese Methode ist nur für lokale Hostnamen anwendbar. Wenn ein Remote-Hostname angegeben wird, wird eine URLError ausgelöst.

DataHandler Objekte¶

DataHandler.data_open(req)¶: Liest eine Daten-URL. Diese Art von URL enthält den Inhalt, der in der URL selbst kodiert ist. Die Syntax von Daten-URLs ist in RFC 2397 spezifiziert. Diese Implementierung ignoriert Leerzeichen in base64-kodierten Daten-URLs, sodass die URL in jeder Quelldatei, aus der sie stammt, umgebrochen werden kann. Aber obwohl einige Browser eine fehlende Auffüllung am Ende einer base64-kodierten Daten-URL nicht beanstanden, wird diese Implementierung in diesem Fall eine ValueError auslösen.

FTPHandler Objekte¶

FTPHandler.ftp_open(req)¶: Öffnet die von req angegebene FTP-Datei. Die Anmeldung erfolgt immer mit leerem Benutzernamen und Passwort.

CacheFTPHandler Objekte¶

CacheFTPHandler-Objekte sind FTPHandler-Objekte mit den folgenden zusätzlichen Methoden:

CacheFTPHandler.setTimeout(t)¶: Setzt das Timeout von Verbindungen auf t Sekunden.

CacheFTPHandler.setMaxConns(m)¶: Setzt die maximale Anzahl zwischengespeicherter Verbindungen auf m.

UnknownHandler Objekte¶

UnknownHandler.unknown_open()¶: Löst eine URLError Ausnahme aus.

HTTPErrorProcessor Objekte¶

HTTPErrorProcessor.http_response(request, response)¶

Verarbeitet HTTP-Fehlerantworten.

Bei Fehlercodes 200 wird das Antwortobjekt sofort zurückgegeben.

Bei Nicht-200-Fehlercodes wird die Aufgabe einfach an die Methoden des http_error_<type>()-Handlers weitergeleitet, über OpenerDirector.error(). Schließlich löst HTTPDefaultErrorHandler eine HTTPError aus, wenn kein anderer Handler den Fehler behandelt.

HTTPErrorProcessor.https_response(request, response)¶

Verarbeitet HTTPS-Fehlerantworten.

Das Verhalten ist dasselbe wie bei http_response().

Beispiele¶

Zusätzlich zu den unten aufgeführten Beispielen finden Sie weitere Beispiele in HOWTO Internet-Ressourcen mit dem urllib-Paket abrufen.

Dieses Beispiel ruft die Hauptseite von python.org ab und zeigt die ersten 300 Bytes davon an.

>>> import urllib.request
>>> with urllib.request.urlopen('https://pythonlang.de/') as f:
...     print(f.read(300))
...
b'<!doctype html>\n<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->\n<!--[if IE 7]>      <html class="no-js ie7 lt-ie8 lt-ie9">          <![endif]-->\n<!--[if IE 8]>      <html class="no-js ie8 lt-ie9">

Beachten Sie, dass urlopen ein Bytes-Objekt zurückgibt. Das liegt daran, dass urlopen keine Möglichkeit hat, die Kodierung des Byte-Streams, den es vom HTTP-Server erhält, automatisch zu bestimmen. Im Allgemeinen dekodiert ein Programm das zurückgegebene Bytes-Objekt in eine Zeichenkette, sobald es die geeignete Kodierung bestimmt oder vermutet hat.

Das folgende HTML-Spezifikationsdokument, https://html.spec.whatwg.org/#charset, listet die verschiedenen Möglichkeiten auf, wie ein HTML- oder XML-Dokument seine Kodierungsinformationen angeben könnte.

Weitere Informationen finden Sie im W3C-Dokument: https://www.w3.org/International/questions/qa-html-encoding-declarations.

Da die python.org-Website die Kodierung utf-8 verwendet, wie in ihrem Meta-Tag angegeben, werden wir dieselbe Kodierung zum Dekodieren des Bytes-Objekts verwenden.

>>> with urllib.request.urlopen('https://pythonlang.de/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!doctype html>
<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
<!-

Es ist auch möglich, dasselbe Ergebnis zu erzielen, ohne den Ansatz des Kontextmanagers zu verwenden.

>>> import urllib.request
>>> f = urllib.request.urlopen('https://pythonlang.de/')
>>> try:
...     print(f.read(100).decode('utf-8'))
... finally:
...     f.close()
...
<!doctype html>
<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
<!--

Im folgenden Beispiel senden wir einen Datenstrom an die Standardeingabe eines CGI und lesen die Daten, die es uns zurückgibt. Beachten Sie, dass dieses Beispiel nur funktioniert, wenn die Python-Installation SSL unterstützt.

>>> import urllib.request
>>> req = urllib.request.Request(url='https:///cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"

Der Code für das Beispiel-CGI, das im obigen Beispiel verwendet wird, lautet:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

Hier ist ein Beispiel für eine PUT-Anfrage unter Verwendung von Request.

import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='https://:8080', data=DATA, method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)

Verwendung der Basic HTTP-Authentifizierung

import urllib.request
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
with urllib.request.urlopen('http://www.example.com/login.html') as f:
    print(f.read().decode('utf-8'))

build_opener() stellt viele Handler standardmäßig bereit, darunter einen ProxyHandler. Standardmäßig verwendet ProxyHandler die Umgebungsvariablen mit dem Namen <scheme>_proxy, wobei <scheme> das beteiligte URL-Schema ist. Zum Beispiel wird die Umgebungsvariable http_proxy gelesen, um die URL des HTTP-Proxys zu erhalten.

Dieses Beispiel ersetzt den Standard-ProxyHandler durch einen, der programmatisch bereitgestellte Proxy-URLs verwendet, und fügt Proxy-Autorisierungsunterstützung mit ProxyBasicAuthHandler hinzu.

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
with opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))

Hinzufügen von HTTP-Headern

Verwenden Sie das Argument headers des Konstruktors Request, oder

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'https://pythonlang.de/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
with urllib.request.urlopen(req) as f:
    print(f.read().decode('utf-8'))

OpenerDirector fügt automatisch einen User-Agent-Header zu jedem Request hinzu. Um dies zu ändern

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
with opener.open('http://www.example.com/') as f:
   print(f.read().decode('utf-8'))

Denken Sie auch daran, dass einige Standard-Header (Content-Length, Content-Type und Host) hinzugefügt werden, wenn das Request-Objekt an urlopen() (oder OpenerDirector.open()) übergeben wird.

Hier ist eine Beispielsitzung, die die GET-Methode verwendet, um eine URL mit Parametern abzurufen.

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...

Das folgende Beispiel verwendet stattdessen die POST-Methode. Beachten Sie, dass die von urlencode erzeugten Parameter vor dem Senden an urlopen als Daten in Bytes kodiert werden.

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

Das folgende Beispiel verwendet einen explizit angegebenen HTTP-Proxy und überschreibt damit die Umgebungseinstellungen.

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler(proxies))
>>> with opener.open("https://pythonlang.de") as f:
...     f.read().decode('utf-8')
...

Das folgende Beispiel verwendet überhaupt keine Proxys und überschreibt damit die Umgebungseinstellungen.

>>> import urllib.request
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler({}}))
>>> with opener.open("https://pythonlang.de/") as f:
...     f.read().decode('utf-8')
...

Legacy-Schnittstelle¶

Die folgenden Funktionen und Klassen stammen aus dem Python-2-Modul urllib (im Gegensatz zu urllib2). Sie könnten zu einem späteren Zeitpunkt veraltet sein.

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)¶

Kopiert ein Netzwerkobjekt, das durch eine URL bezeichnet wird, in eine lokale Datei. Wenn die URL auf eine lokale Datei verweist, wird das Objekt nicht kopiert, es sei denn, filename wird angegeben. Gibt ein Tupel (filename, headers) zurück, wobei filename der lokale Dateiname ist, unter dem das Objekt gefunden werden kann, und headers alles ist, was die info()-Methode des von urlopen() zurückgegebenen Objekts zurückgegeben hat (für ein Remote-Objekt). Ausnahmen sind die gleichen wie für urlopen().

Das zweite Argument, falls vorhanden, gibt den Dateispeicherort an, an den kopiert werden soll (wenn es fehlt, wird der Speicherort eine temporäre Datei mit einem generierten Namen sein). Das dritte Argument, falls vorhanden, ist eine aufrufbare Funktion, die einmal beim Aufbau der Netzwerkverbindung und danach nach jedem gelesenen Block aufgerufen wird. Die aufrufbare Funktion erhält drei Argumente: die bisher übertragene Anzahl von Blöcken, die Blockgröße in Bytes und die Gesamtgröße der Datei. Das dritte Argument kann bei älteren FTP-Servern, die keine Dateigröße als Antwort auf eine Abrufanfrage zurückgeben, -1 sein.

Das folgende Beispiel veranschaulicht das gängigste Anwendungsszenario.

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('https://pythonlang.de/')
>>> html = open(local_filename)
>>> html.close()

Wenn die url den http:-Schemenbezeichner verwendet, kann das optionale Argument data angegeben werden, um eine POST-Anfrage zu spezifizieren (normalerweise ist der Anfragetyp GET). Das Argument data muss ein Bytes-Objekt im Standardformat application/x-www-form-urlencoded sein; siehe die Funktion urllib.parse.urlencode().

urlretrieve() löst eine ContentTooShortError aus, wenn sie feststellt, dass die verfügbare Datenmenge geringer war als die erwartete Menge (d.h. die vom Content-Length-Header gemeldete Größe). Dies kann beispielsweise auftreten, wenn der Download unterbrochen wird.

Der Content-Length wird als untere Grenze behandelt: Wenn mehr Daten zu lesen sind, liest urlretrieve mehr Daten, aber wenn weniger Daten verfügbar sind, wird die Ausnahme ausgelöst.

In diesem Fall können Sie die heruntergeladenen Daten immer noch abrufen, sie sind im Attribut content der Ausnahmeinstanz gespeichert.

Wenn kein Content-Length-Header angegeben wurde, kann urlretrieve die Größe der heruntergeladenen Daten nicht überprüfen und gibt sie einfach zurück. In diesem Fall müssen Sie davon ausgehen, dass der Download erfolgreich war.

urllib.request.urlcleanup()¶: Bereinigt temporäre Dateien, die möglicherweise von früheren Aufrufen von urlretrieve() zurückgelassen wurden.

`urllib.request` Einschränkungen¶

Derzeit werden nur die folgenden Protokolle unterstützt: HTTP (Versionen 0.9 und 1.0), FTP, lokale Dateien und Daten-URLs.

Geändert in Version 3.4: Unterstützung für Daten-URLs hinzugefügt.
Die Caching-Funktion von urlretrieve() wurde deaktiviert, bis jemand Zeit findet, eine ordnungsgemäße Verarbeitung von Verfallszeit-Headern zu implementieren.
Es sollte eine Funktion geben, um abzufragen, ob eine bestimmte URL im Cache ist.
Zurückwärtskompatibilität: Wenn eine URL auf eine lokale Datei zu verweisen scheint, die Datei aber nicht geöffnet werden kann, wird die URL mit dem FTP-Protokoll neu interpretiert. Dies kann manchmal zu verwirrenden Fehlermeldungen führen.
Die Funktionen urlopen() und urlretrieve() können beliebig lange Verzögerungen verursachen, während sie auf den Aufbau einer Netzwerkverbindung warten. Das bedeutet, dass es schwierig ist, ohne Threads einen interaktiven Webclient mit diesen Funktionen zu erstellen.
Die von urlopen() oder urlretrieve() zurückgegebenen Daten sind die Rohdaten, die vom Server zurückgegeben werden. Dies können Binärdaten (wie ein Bild), Klartext oder (zum Beispiel) HTML sein. Das HTTP-Protokoll liefert Typinformationen im Antwort-Header, die durch Betrachten des Content-Type-Headers eingesehen werden können. Wenn die zurückgegebenen Daten HTML sind, können Sie das Modul html.parser zum Parsen verwenden.
Der Code, der das FTP-Protokoll behandelt, kann nicht zwischen einer Datei und einem Verzeichnis unterscheiden. Dies kann zu unerwartetem Verhalten führen, wenn versucht wird, eine URL zu lesen, die auf eine nicht zugängliche Datei verweist. Wenn die URL mit einem / endet, wird angenommen, dass sie sich auf ein Verzeichnis bezieht und entsprechend behandelt wird. Wenn jedoch ein Versuch, eine Datei zu lesen, zu einem 550-Fehler führt (was bedeutet, dass die URL nicht gefunden wurde oder nicht zugänglich ist, oft aus Berechtigungsgründen), wird der Pfad als Verzeichnis behandelt, um den Fall zu behandeln, wenn ein Verzeichnis durch eine URL angegeben ist, aber der nachgestellte / weggelassen wurde. Dies kann zu irreführenden Ergebnissen führen, wenn Sie versuchen, eine Datei abzurufen, deren Leseberechtigungen sie unzugänglich machen. Der FTP-Code versucht, sie zu lesen, schlägt mit einem 550-Fehler fehl und führt dann eine Verzeichnisauflistung für die unlesbare Datei durch. Wenn eine feinere Steuerung erforderlich ist, sollten Sie das Modul ftplib in Betracht ziehen.

`urllib.response` — Response-Klassen, die von urllib verwendet werden¶

Das Modul urllib.response definiert Funktionen und Klassen, die eine minimale dateiähnliche Schnittstelle definieren, einschließlich read() und readline(). Die von diesem Modul definierten Funktionen werden intern vom Modul urllib.request verwendet. Das typische Response-Objekt ist eine Instanz von urllib.response.addinfourl.

class urllib.response.addinfourl¶

url¶: URL der abgerufenen Ressource, die häufig verwendet wird, um festzustellen, ob einer Weiterleitung gefolgt wurde.

headers¶: Gibt die Header der Antwort in Form einer EmailMessage-Instanz zurück.

status¶: Hinzugefügt in Version 3.9.

Vom Server zurückgegebener Statuscode.

geturl()¶: Veraltet seit Version 3.9: Veraltet zugunsten von url.

info()¶: Veraltet seit Version 3.9: Veraltet zugunsten von headers.

code¶: Veraltet seit Version 3.9: Veraltet zugunsten von status.

getcode()¶: Veraltet seit Version 3.9: Veraltet zugunsten von status.

`urllib.request` — Erweitert erweiterbare Bibliothek zum Öffnen von URLs¶

Request-Objekte¶

OpenerDirector-Objekte¶

BaseHandler-Objekte¶

HTTPRedirectHandler Objekte¶

HTTPCookieProcessor Objekte¶

ProxyHandler Objekte¶

HTTPPasswordMgr Objekte¶

HTTPPasswordMgrWithPriorAuth Objekte¶

AbstractBasicAuthHandler Objekte¶

HTTPBasicAuthHandler Objekte¶

ProxyBasicAuthHandler Objekte¶

AbstractDigestAuthHandler Objekte¶

HTTPDigestAuthHandler Objekte¶

ProxyDigestAuthHandler Objekte¶

HTTPHandler Objekte¶

HTTPSHandler Objekte¶

FileHandler Objekte¶

DataHandler Objekte¶

FTPHandler Objekte¶

CacheFTPHandler Objekte¶

UnknownHandler Objekte¶

HTTPErrorProcessor Objekte¶

Beispiele¶

Legacy-Schnittstelle¶

`urllib.request` Einschränkungen¶

`urllib.response` — Response-Klassen, die von urllib verwendet werden¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

urllib.request — Erweitert erweiterbare Bibliothek zum Öffnen von URLs¶

Request-Objekte¶

OpenerDirector-Objekte¶

BaseHandler-Objekte¶

HTTPRedirectHandler Objekte¶

HTTPCookieProcessor Objekte¶

ProxyHandler Objekte¶

HTTPPasswordMgr Objekte¶

HTTPPasswordMgrWithPriorAuth Objekte¶

AbstractBasicAuthHandler Objekte¶

HTTPBasicAuthHandler Objekte¶

ProxyBasicAuthHandler Objekte¶

AbstractDigestAuthHandler Objekte¶

HTTPDigestAuthHandler Objekte¶

ProxyDigestAuthHandler Objekte¶

HTTPHandler Objekte¶

HTTPSHandler Objekte¶

FileHandler Objekte¶

DataHandler Objekte¶

FTPHandler Objekte¶

CacheFTPHandler Objekte¶

UnknownHandler Objekte¶

HTTPErrorProcessor Objekte¶

Beispiele¶

Legacy-Schnittstelle¶

urllib.request Einschränkungen¶

urllib.response — Response-Klassen, die von urllib verwendet werden¶

`urllib.request` — Erweitert erweiterbare Bibliothek zum Öffnen von URLs¶

`urllib.request` Einschränkungen¶

`urllib.response` — Response-Klassen, die von urllib verwendet werden¶