diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 8546d6e..f3083dd 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -6,13 +6,13 @@ Fortgeschrittene Nutzung Dieses Dokument behandelt einige der fortgeschrittenen Features von Requests. -Sesssion-Objekte +Session-Objekte ---------------- Das Session-Objekt erlaubt das Persistieren einiger Parameter über einzelne Anfragen hinweg. Es persistiert auch Cookies für die Dauer aller Anfragen einer Session-Instanz. -Ein Session-Objekt besitzt alle Methoden der Haupt-API von Requests (get,put, post, delete, head, options). +Ein Session-Objekt besitzt alle Methoden der Haupt-API von Requests (get, put, post, delete, head, options). Lassen Sie und mit Cookies über mehrere Anfragen hinweg arbeiten:: @@ -38,7 +38,7 @@ Dies geschieht durch die Angaben von Eigenschaften eines Session-Objekts:: Alle Dictionaries, die Sie einer Anfragemethode übergeben, werden mit den Werten der Session zusammengeführt, bevor sie gesendet werden. Falls an beiden Stellen Angaben gemacht werden, überschreiben die Parameter auf -Methodenebene die des Session-Objekts. +Methodenebene die des Session-Objektes. .. admonition:: Einen Wert aus einem Dictionary-Parameter entfernen @@ -59,7 +59,7 @@ geschickt wird, um eine Anfrage auszuführen oder eine Ressource zu lesen. Zweitens wird, sobald Requests eine Antwort vom Server erhält, ein ``Response`` Objekt erzeugt. Dieses ``Response`` Objekt enthält alle vom Server gelieferten Informationen sowie das ursprünglich erzeugte ``Request`` Objekt. -Hier ist eine einfaxche Anfrage, um einige sehr wichtige Daten aus der Wikipedia +Hier ist eine einfache Anfrage, um einige sehr wichtige Daten aus der Wikipedia zu lesen:: >>> r = requests.get('http://en.wikipedia.org/wiki/Monty_Python') @@ -78,7 +78,7 @@ tun Sie folgendes:: MISS from cp1010.eqiad.wmnet:80'} Wollen Sie dagegen wissen, welche Header wir ursprünglich an den Server gesendet haben, -greifen wir eindach auf die Anfrage und darin auf die Header von ``request`` zu:: +greifen wir einfach auf die Anfrage und darin auf die Header von ``request`` zu:: >>> r.request.headers {'Accept-Encoding': 'identity, deflate, compress, gzip', @@ -88,7 +88,7 @@ greifen wir eindach auf die Anfrage und darin auf die Header von ``request`` zu: Prepared Requests ----------------- -Wann immer SIe ein :class:`Response ` Objekt von einem +Wann immer Sie ein :class:`Response ` Objekt von einem API-Aufruf oder einem Session-Aufruf zurück erhalten, handelt es sich bei der ``request`` Eigenschaft tatsächlich um die ``PreparedRequest`` Eigenschaft, die benutzt wurde. In einigen Fällen möchten Sie vielleicht zusätzliche Bearbeitungen @@ -118,7 +118,7 @@ Der einfache Weg dazu ist folgender:: print(resp.status_code) Nachdem Sie nichts Besonderes mit dem ``Request`` Objekt gemacht haben, bereiten -Sie das sofort durch den Aufruf von prepare() vor und veändern das ``PreparedRequest`` Objekt. +Sie das sofort durch den Aufruf von prepare() vor und verändern das ``PreparedRequest`` Objekt. Dieses senden Sie dann mit den anderen Parametern, die Sie auch an ``requests.*`` oder an ``Session.*`` gesendet hätten. @@ -173,7 +173,7 @@ bis Sie auf die :class:`Response.content` Eigenschaft zugreifen. Benutzen Sie da r = requests.get(tarball_url, stream=True) Zu diesem Zeitpunkt wurden nur die Header der Antwort herunter geladen und die Verbindung -bleibt offen. Damit wird und erlaubt, das Lesen des Antwortsinhalts optional zu gestalten:: +bleibt offen. Damit wird uns erlaubt, das Lesen des Antwortsinhalts optional zu gestalten:: if int(r.headers['content-length']) < TOO_LONG: content = r.content @@ -227,7 +227,7 @@ geben Sie einfach einen Generator (oder einen Iterator ohne Länge) für die Dat Event Hooks ----------- -Reqeusts hat ein System für Event Hooks, das Sie benutzen können, um sich in +Requests hat ein System für Event Hooks, das Sie benutzen können, um sich in den Anfrageprozess einzuhängen oder Ereignisse zu signalisieren. Verfügbare Hooks: @@ -251,7 +251,7 @@ Diese ``callback_function`` erhält ein Datenpaket als erstes Argument. Falls während der Ausführung des Callbacks ein Fehler passiert, erhalten Sie eine Warnung. Wenn die Callback-Funktion einen Wert zurück liefert, wird angenommen, dass dieser die -Datenersetzen soll, die übergeben wurden. Wenn die Funktion nichts zurück liefert, wird +Daten ersetzen soll, die übergeben wurden. Wenn die Funktion nichts zurück liefert, wird auch nichts verändert. Lassen Sie uns einige Argumente der Anfrage-Methode zur Laufzeit ausgeben:: @@ -264,13 +264,13 @@ Lassen Sie uns einige Argumente der Anfrage-Methode zur Laufzeit ausgeben:: Benutzerdefinierte Authentifizierung ------------------------------------ -Reqeusts erlaubt es Ihnen, Ihren eigenen Authentifizierungsmechanismus anzugeben. +Requests erlaubt es Ihnen, Ihren eigenen Authentifizierungsmechanismus anzugeben. Jedes Callable, das als das ``auth`` Argument einer Anfrage übergeben wird, hat die Möglichkeit, die Anfrage vor der Weiterleitung zu modifizieren. Implementierungen für eine Authentifizierung sind Unterklassen von ``requests.auth.AuthBase`` -und einfach zu definieren. Reqeusts bietet zwei Implementierungen üblicher Authentifizierungs-Schemata +und einfach zu definieren. Requests bietet zwei Implementierungen üblicher Authentifizierungs-Schemata in ``requests.auth``: ``HTTPBasicAuth`` and ``HTTPDigestAuth``. Nehmen wir an, dass wir einen Webservice haben, der nur dann reagiert, wenn der ``X-Pizza`` Header @@ -356,7 +356,7 @@ Standardkonformität Es ist die Absicht des Requests-Projektes, alle relevanten Spezifikationen und RFCs zu beachten, wo diese Konformität keine Schwierigkeiten für die Benutzer bedeutet. -Dieser Fokus auf die Beachtung der Standards kann zu verhalten führen, dass für +Dieser Fokus auf die Beachtung der Standards kann zu Verhalten führen, dass für nicht mit diesen Standards und RFCs vertrauten Benutzern auf den ersten Blick ungewöhnlich aussieht. @@ -365,14 +365,14 @@ Zeichenkodierung ^^^^^^^^^^^^^^^^ Wenn Sie eine Antwort vom Server erhalten, versucht Requests das für die -Dekodierung der Antwortdaten nötige Encoding zu erschließen, wenn Sie die +Dekodierung der Antwortdaten nötige Encoding zu ermitteln, wenn Sie die ``Response.text`` Methode aufrufen. Requests prüft zuerst, ob in den HTTP Headern eine Zeichenkodierung angegeben ist. Falls kein Encoding im Header vorhanden ist, benutzt Requests `charade `_ für einen -Versuch, das Encoding zu erschließen. +Versuch, das Encoding zu ermitteln. Der einzige Fall, bei dem Requests nicht versuchen wird, die Zeichenkodierung -zu erraten, ist der, dass keine explizite Angabe des Encodings im Header vorhanden +zu ermitteln, ist der, dass keine explizite Angabe des Encodings im Header vorhanden ist **und** dass der ``Content-Type`` Header den Inhalt ``text`` besitzt. In diesem Fall gibt der `RFC 2616 `_ an, dass der Standardzeichensatz ``ISO-8859-1`` sein muss. Requests folgt in diesem @@ -394,7 +394,7 @@ idempotente Methode, die eine Ressource von einer angegebenen URL liest. Daher sollten Sie dieses Verb benutzen, wenn Sie Daten von einer URL im Web lesen wollen. Ein Beispiel wäre der Versuch, Informationen über einen bestimmten Commit in GitHub zu erhalten. Nehmen wir an, wir wollten den -Commit `à050faf`` aus dem Requests-Repository liesen. Dies erreichen +Commit `à050faf`` aus dem Requests-Repository lesen. Dies erreichen Sie mit dem folgenden Code:: >>> import requests @@ -436,7 +436,7 @@ um zu sehen, welche HTTP Methoden von der gerade benutzten URL unterstützt werd He! Was? Das ist nicht hilfreich! Wie sich heraus stellt, implementiert GitHub, wie viele andere Dienste, die im WEB eine API anbieten, die OPTIONS-Methode nicht wirklich. -Das ist etwas ärgerlich, denm jetzt müssen wir doch die langweilige Dokumentation lesen. +Das ist etwas ärgerlich, denn jetzt müssen wir doch die langweilige Dokumentation lesen. Würde GitHub OPTIONS korrekt implementiert haben, dann könnte man mit diesem Verb alle erlaubten HTTP Methoden für die URL zurück erhalten, wie zum Beispiel so:: @@ -448,7 +448,7 @@ Nachdem wir die Dokumentation gelesen haben, sehen wir, dass die einzige andere Methode, die für Commits erlaubt wird, ein POST ist. Dies erzeugt einen neuen Commit. Da wir für unsere Beispiele bisher das Requests-Repository benutzt haben, wäre es vielleicht besser, nicht einfach wilde Änderungen per POST abzusenden. Lassen Sie -und daher etwas mit dem Ticket-Feature von GitHub spielen. +und daher etwas mit dem Ticket-Feature von GitHub versuchen. Diese Dokumentation wurde als Antwort auf Ticket #482 hinzugefügt. Da wir deshalb davon ausgehen können, dass es dieses Ticket gibt, werden wir es in den Beispielen @@ -465,7 +465,7 @@ benutzen. Starten wir damit, dass wir das Ticket lesen. >>> print issue[u'comments'] 3 -Cool, wir haben drei Kommentare zu Ticket #482. Sehen wir und den letzten an. +Cool, wir haben drei Kommentare zu Ticket #482. Sehen wir uns den letzten an. :: @@ -497,7 +497,7 @@ indem wir mit einem POST einen Kommentar hinzufügen. Dann machen wir das auch. >>> r.status_code 404 -Oha, das ist merkwürdig! Wahrscheinlich müssen wir und anmelden. Das wir bestimmt schwierig, nicht? +Oha, das ist merkwürdig! Wahrscheinlich müssen wir uns anmelden. Das wird bestimmt schwierig, nicht? Falsch. Requests macht es uns sehr einfach, verschiedene Formen der Authentifizierung zu benutzen, unter anderem die sehr verbreitete *Basic Authentication*. @@ -514,7 +514,7 @@ benutzen, unter anderem die sehr verbreitete *Basic Authentication*. Perfekt. Oh nein, doch nicht! Bevor wir die Dokumentation schreiben, muss zuerst die Katze gefüttert werden, das dauert eine Weile. Könnten wir doch nur den Kommentar bearbeiten! -Glücklicherweise erlaubt uns die GitHub API ein anderes HTTP verb zu benutzen: PATCH. +Glücklicherweise erlaubt uns die GitHub API ein anderes HTTP Verb zu benutzen: PATCH. Verwenden wir also PATCH, um den Kommentar zu ändern. :: @@ -529,8 +529,8 @@ Verwenden wir also PATCH, um den Kommentar zu ändern. Exzellent. Jetzt quälen wir diesen Kenneth etwas und bringen ihn ins Schwitzen, weil wir ihm nicht sagen, dass wir an der Dokumentation arbeiten. Dazu löschen wir diesen Kommentar wieder. -GitHub lässt und Kommentare durch das sehr passend benannte Verb DELETE löschen. Gut, werden -wir den Kommentar los ... +GitHub lässt uns Kommentare durch das sehr passend benannte Verb DELETE löschen. Gut, werden +wir den Kommentar wieder los ... :: @@ -554,14 +554,14 @@ ich, anstatt die komplette Seite zu laden, nur über das Verb HEAD die Header le 'x-ratelimit-limit': '5000' ... -Sehr gut. Zeit, noch mehr Python Code zu schreiben, der die GitHub APU auf alle erdenklichen -Arten missbraucht; und das noch 4995 mal in der nächsten Stunde. +Sehr gut. Zeit, noch mehr Python Code zu schreiben, der die GitHub API auf alle erdenklichen +Arten missbraucht; und das noch 4.995 mal in der nächsten Stunde. Link Header ----------- -Viele HTTP APIs benutzen sogenannte Links Header. Diese machen APIs leichter verstehbar und auch +Viele HTTP APIs benutzen sogenannte Link Header. Diese machen APIs leichter verstehbar und auch leichter zu erforschen. GitHub beispielsweise benutzt solche Link Header für die `Pagination `_,