BEZEICHNUNG

begs – HTTP für Menschen, die nicht mehr weiterwissen – fleht Server an, bis sie antworten

ÜBERSICHT

import begs

begs.get(url, bitte=True)
begs.post(url, json=daten, nachdruck=3)
begs.grovel(url)
begs.bribe(url, betrag=5)
begs.fax(url)

BESCHREIBUNG

begs ist eine HTTP-Bibliothek für Python nach einem einfachen Grundsatz: Wer freundlich fragt, bekommt eher eine Antwort. Wer verzweifelt fragt, bekommt wenigstens Mitleid.

Antwortet ein Server mit einem Fehler, gibt begs nicht auf. Es wiederholt die Anfrage – jedes Mal etwas höflicher, jedes Mal etwas verzweifelter. Fachleute nennen das exponential begging: Die Wartezeit zwischen den Versuchen verdoppelt sich, die Zahl der Ausrufezeichen ebenfalls.

Jede Antwort hat neben status_code, text und json() das Attribut stimmung. Es verrät, wie widerwillig der Server geantwortet hat. Mögliche Werte: "gern", "na gut", "ausnahmsweise" und "nur weil du's bist".

FUNKTIONEN

begs.get(url, bitte=False)

Holt eine Ressource. Ohne bitte=True antwortet begs mit 428 Precondition Required. Die fehlende Vorbedingung sind Manieren.

begs.post(url, json=None, nachdruck=1)

Sendet Daten. Ab nachdruck=5 schreibt begs zusätzlich eine E-Mail an den Administrator, ab nachdruck=10 an dessen Mutter.

begs.grovel(url)

Der letzte Ausweg. Sendet die Anfrage auf Knien: mit allen bekannten User-Agents gleichzeitig und einem handschriftlichen Entschuldigungsschreiben als eingescanntes PDF im Body.

begs.bribe(url, betrag=5)

Legt der Anfrage den Header X-Trinkgeld bei. Funktioniert bei überraschend vielen Unternehmens-APIs.

begs.fax(url)

Für Server deutscher Behörden. Sendet die Anfrage per Fax und liefert die Antwort binnen sechs bis acht Wochen auf dem Postweg. Ein frankierter Rückumschlag liegt bei.

begs.Session()

Merkt sich Cookies, Header und jede Zurückweisung. Ab der hundertsten Abfuhr steht session.beziehungsstatus auf "es ist kompliziert".

STATUSCODES

begs kennt alle offiziellen HTTP-Statuscodes und einige, die längst hätten eingeführt werden sollen:

BEISPIELE

Nach einer Gehaltserhöhung fragen:

>>> r = begs.get("https://api.example.com/gehalt/erhoehung")
>>> r.status_code
428
>>> r = begs.get("https://api.example.com/gehalt/erhoehung", bitte=True)
>>> r.json()
{'erhoehung': 0, 'nachricht': 'Wir melden uns.'}
>>> r.stimmung
'na gut'

Was bei Wiederholungsversuchen tatsächlich gesendet wird:

$ BEGS_DEBUG=1 python skript.py
begs: Versuch 1  GET /api/daten   Accept: application/json
begs: Versuch 2  GET /api/daten   X-Bitte: bitte
begs: Versuch 3  GET /api/daten   X-Bitte: bitte bitte
begs: Versuch 4  GET /api/daten   X-Bitte: BITTE!!
begs: Versuch 5  GET /api/daten   X-Bitte: ich hab doch auch Familie
begs: Versuch 6  GET /api/daten   X-Bitte: ok sorry, war nicht so gemeint
begs: Antwort 503 – Server ist im Urlaub. Abwesenheitsnotiz liegt im Body.

Einen Bauantrag stellen:

>>> r = begs.fax("https://bauamt.example.de/antrag/gartenhaus")
>>> r.status_code
202
>>> r.voraussichtlich
datetime.date(2027, 3, 14)
>>> r.text
'Ihr Antrag ist unvollständig. Bitte reichen Sie Formular B-17a nach (nur per Fax).'

AUSNAHMEN

begs.Abfuhr

Der Server hat mit 4xx geantwortet. Nehmen Sie es nicht persönlich. Der Server tut es auch nicht.

begs.Gelesen

Zeitüberschreitung. Der Server hat Ihre Anfrage gelesen. Zwei blaue Haken.

begs.Kontaktverbot

429 Too Many Requests. Sie haben zu oft gefragt. Der Server hat eine einstweilige Verfügung erwirkt.

FEHLER

begs funktioniert nicht bei Servern ohne Gefühle. Nach aktuellem Kenntnisstand betrifft das alle. Der Fehler ist als „wontfix“ markiert, mit der Begründung „bitte nicht“.

SIEHE AUCH

left-bad(3), maybealloc(3), wingit(W), demands(3) – für Leute, die nicht fragen