URL-Encoding in Python (Der komplette Leitfaden zu urllib.parse)

URL-Encoding mit quote()

Die Funktion urllib.parse.quote() ist Pythons wichtigstes Werkzeug für die Percent-Kodierung von Zeichenketten. Sie wandelt Zeichen, die in URLs nicht sicher verwendet werden können, in ihre percent-kodierten Entsprechungen um. Standardmäßig betrachtet sie Schrägstriche (/) als sichere Zeichen, aber dieses Verhalten lässt sich anpassen.

from urllib.parse import quote

# Einfache Kodierung
print(quote('hello world'))
# Ausgabe: hello%20world

# Kodierung von Sonderzeichen
print(quote('price=10&qty=2'))
# Ausgabe: price%3D10%26qty%3D2

# Standardmäßig wird / nicht kodiert
print(quote('path/to/file'))
# Ausgabe: path/to/file

# Um auch Schrägstriche zu kodieren, safe='' setzen
print(quote('path/to/file', safe=''))
# Ausgabe: path%2Fto%2Ffile

# Kodierung von Unicode-Zeichen
print(quote('cafe'))
# Ausgabe: caf%C3%A9

# Zusätzliche sichere Zeichen angeben
print(quote('key=value&foo=bar', safe='=&'))
# Ausgabe: key=value&foo=bar

Der Parameter safe ist der Schlüssel, um zu steuern, was kodiert wird. Standardmäßig gilt safe='/'. Wenn Sie alles außer alphanumerischen Zeichen und _.-~ kodieren möchten, setzen Sie safe=''. Das entspricht dem encodeURIComponent() von JavaScript.

Es gibt außerdem quote_plus(), das wie quote() funktioniert, Leerzeichen jedoch als + statt als %20 kodiert. Dies ist das Format, das bei HTML-Formulardaten (application/x-www-form-urlencoded) verwendet wird.

from urllib.parse import quote_plus

print(quote_plus('hello world'))
# Ausgabe: hello+world

print(quote_plus('key=value&name=John Doe'))
# Ausgabe: key%3Dvalue%26name%3DJohn+Doe

URL-Decoding mit unquote()

Die Funktion urllib.parse.unquote() kehrt die Percent-Kodierung um und wandelt %XX-Sequenzen zurück in ihre ursprünglichen Zeichen. Es gibt außerdem unquote_plus(), das zusätzlich +-Zeichen in Leerzeichen umwandelt.

from urllib.parse import unquote, unquote_plus

# Einfache Dekodierung
print(unquote('hello%20world'))
# Ausgabe: hello world

print(unquote('caf%C3%A9'))
# Ausgabe: cafe (mit Akzent)

# unquote wandelt + NICHT in ein Leerzeichen um
print(unquote('hello+world'))
# Ausgabe: hello+world

# unquote_plus wandelt + in ein Leerzeichen um
print(unquote_plus('hello+world'))
# Ausgabe: hello world

# Dekodierung einer vollständigen URL
url = 'https://example.com/search?q=C%2B%2B%20programming'
print(unquote(url))
# Ausgabe: https://example.com/search?q=C++ programming

Verwenden Sie beim Dekodieren von Formulardaten immer unquote_plus(), da HTML-Formulare Leerzeichen als + kodieren. Nutzen Sie unquote() für das allgemeine URL-Decoding, bei dem Leerzeichen als %20 kodiert sind.

Query-Strings kodieren mit urlencode()

Die Funktion urllib.parse.urlencode() nimmt ein Dictionary oder eine Liste von Tupeln entgegen und wandelt sie in einen korrekt formatierten Query-String um. Dies ist die bequemste Möglichkeit, in Python Query-Strings zu erstellen.

from urllib.parse import urlencode

# Dictionary in Query-String
params = {
    'q': 'python programming',
    'page': 1,
    'lang': 'en'
}
print(urlencode(params))
# Ausgabe: q=python+programming&page=1&lang=en

# Liste von Tupeln (bewahrt die Reihenfolge, erlaubt doppelte Schlüssel)
params = [
    ('tag', 'python'),
    ('tag', 'web'),
    ('sort', 'date')
]
print(urlencode(params))
# Ausgabe: tag=python&tag=web&sort=date

# doseq=True für Listenwerte verwenden
params = {
    'tag': ['python', 'web', 'api'],
    'sort': 'date'
}
print(urlencode(params, doseq=True))
# Ausgabe: tag=python&tag=web&tag=api&sort=date

# quote_via nutzen, um die Kodierung von Leerzeichen zu steuern
from urllib.parse import quote
params = {'q': 'hello world'}
print(urlencode(params, quote_via=quote))
# Ausgabe: q=hello%20world  (verwendet %20 statt +)

Standardmäßig verwendet urlencode() intern quote_plus(), wodurch Leerzeichen zu + werden. Wenn Sie für Leerzeichen %20 benötigen, übergeben Sie wie oben gezeigt quote_via=quote.

Query-Strings parsen mit parse_qs()

Die Funktion urllib.parse.parse_qs() parst einen Query-String zurück in ein Dictionary. Jeder Wert im Dictionary ist eine Liste, da Query-Parameter mehrere Werte haben können. Es gibt außerdem parse_qsl(), das eine Liste von Tupeln zurückgibt.

from urllib.parse import parse_qs, parse_qsl

# Einen Query-String in ein Dictionary parsen
qs = 'q=python+programming&page=1&lang=en'
result = parse_qs(qs)
print(result)
# Ausgabe: {'q': ['python programming'], 'page': ['1'], 'lang': ['en']}

# Hinweis: Werte sind immer Listen
print(result['q'][0])  # 'python programming'

# Mehrere Werte fuer denselben Schluessel behandeln
qs = 'tag=python&tag=web&tag=api'
result = parse_qs(qs)
print(result)
# Ausgabe: {'tag': ['python', 'web', 'api']}

# parse_qsl gibt eine Liste von Tupeln zurueck
result = parse_qsl(qs)
print(result)
# Ausgabe: [('tag', 'python'), ('tag', 'web'), ('tag', 'api')]

# Leere Werte beibehalten (standardmaessig werden sie weggelassen)
qs = 'name=John&email=&age=30'
print(parse_qs(qs, keep_blank_values=True))
# Ausgabe: {'name': ['John'], 'email': [''], 'age': ['30']}

Vollständige URLs kodieren mit urlparse

Beim Arbeiten mit vollständigen URLs ermöglichen Pythons Funktionen urlparse() und urlunparse(), URLs sicher zu zerlegen und wieder zusammenzusetzen. Das ist besonders nützlich, wenn Sie bestimmte Teile einer URL ändern müssen, ohne ihre Struktur zu zerstören.

from urllib.parse import urlparse, urlunparse, urlencode, quote

# Eine URL in ihre Bestandteile zerlegen
url = 'https://example.com/search?q=hello&page=1#results'
parsed = urlparse(url)
print(parsed.scheme)    # 'https'
print(parsed.netloc)    # 'example.com'
print(parsed.path)      # '/search'
print(parsed.query)     # 'q=hello&page=1'
print(parsed.fragment)  # 'results'

# Eine URL aus ihren Bestandteilen zusammensetzen
from urllib.parse import ParseResult
new_url = urlunparse(ParseResult(
    scheme='https',
    netloc='api.example.com',
    path='/v2/search',
    params='',
    query=urlencode({'q': 'python & java', 'limit': 10}),
    fragment=''
))
print(new_url)
# Ausgabe: https://api.example.com/v2/search?q=python+%26+java&limit=10

# Ein Pfadsegment mit Sonderzeichen sicher hinzufuegen
base = 'https://example.com/files/'
filename = 'my report (final).pdf'
safe_url = base + quote(filename, safe='')
print(safe_url)
# Ausgabe: https://example.com/files/my%20report%20%28final%29.pdf

Für modernen Python-Code sollten Sie die Bibliothek requests in Betracht ziehen, die das URL-Encoding automatisch übernimmt, wenn Sie Parameter als Dictionary übergeben. Auch die Bibliothek httpx bietet ähnliche Funktionen zur automatischen Kodierung.

import requests

# requests uebernimmt die Kodierung automatisch
response = requests.get(
    'https://api.example.com/search',
    params={
        'q': 'python & java',
        'page': 1,
        'sort': 'relevance'
    }
)
print(response.url)
# https://api.example.com/search?q=python+%26+java&page=1&sort=relevance