webbrowser — Bequeme Steuerung von Webbrowsern

Quellcode: Lib/webbrowser.py

Das Modul webbrowser bietet eine Schnittstelle auf hoher Ebene, um Nutzern webbasierte Dokumente anzuzeigen. In den meisten Fällen genügt ein Aufruf der Funktion open() aus diesem Modul und es geschieht das Richtige.

Unter Unix werden auf X11 grafische Browser bevorzugt. Textbasierte Browser kommen zum Einsatz, wenn kein grafischer Browser oder kein X11-Display zur Verfügung steht. Bei textbasierten Browsern blockiert der aufrufende Prozess, bis der Nutzer den Browser beendet.

Gibt es die Umgebungsvariable BROWSER, wird sie als eine durch os.pathsep getrennte Liste von Browsern gedeutet, die vor den Voreinstellungen der Plattform versucht werden. Enthält der Wert eines Listenteils die Zeichenkette %s, wird er als wörtliche Befehlszeile des Browsers gedeutet, in der %s durch die URL aus dem Argument ersetzt wird. Ist der Wert ein einzelnes Wort, das auf einen bereits registrierten Browser verweist, wird dieser Browser an den Anfang der Suchliste gesetzt. Enthält der Teil kein %s, wird er einfach als Name des zu startenden Browsers gedeutet. [1]

Geändert in Version 3.14: Die Variable BROWSER lässt sich jetzt auch dazu verwenden, die Liste der Plattform-Voreinstellungen umzusortieren. Das ist besonders unter macOS nützlich, wo die Voreinstellungen der Plattform nicht auf Befehlszeilenwerkzeuge in PATH verweisen.

Auf Plattformen außerhalb von Unix, und unter Unix, wenn ein entfernter Browser zur Verfügung steht, wartet der steuernde Prozess nicht darauf, dass der Nutzer den Browser beendet, sondern überlässt dem entfernten Browser seine eigenen Fenster auf dem Display. Stehen unter Unix keine entfernten Browser zur Verfügung, startet der steuernde Prozess einen neuen Browser und wartet.

Unter iOS werden die Umgebungsvariable BROWSER sowie alle Argumente ignoriert, die das Nach-vorn-Holen, die Browserauswahl und das Anlegen neuer Tabs oder Fenster steuern. Webseiten werden immer im bevorzugten Browser des Nutzers in einem neuen Tab geöffnet, wobei der Browser in den Vordergrund geholt wird. Die Verwendung des Moduls webbrowser unter iOS setzt das Modul ctypes voraus. Steht ctypes nicht zur Verfügung, schlagen Aufrufe von open() fehl.

Befehlszeilenschnittstelle

Das Skript webbrowser lässt sich als Befehlszeilenschnittstelle für das Modul verwenden. Es nimmt eine URL als Argument und versteht die folgenden optionalen Parameter:

-n, --new-window

Öffnet die URL nach Möglichkeit in einem neuen Browserfenster.

-t, --new-tab

Öffnet die URL in einem neuen Browser-Tab.

Die Optionen schließen sich naturgemäß gegenseitig aus. Anwendungsbeispiel:

python -m webbrowser -t "https://www.python.org"

Verfügbarkeit: not WASI, not Android.

Die folgende Ausnahme ist definiert:

exception webbrowser.Error

Ausnahme, die bei einem Fehler in der Browsersteuerung ausgelöst wird.

Die folgenden Funktionen sind definiert:

webbrowser.open(url, new=0, autoraise=True)

Zeigt url im voreingestellten Browser an. Ist new 0, wird url nach Möglichkeit im selben Browserfenster geöffnet. Ist new 1, wird nach Möglichkeit ein neues Browserfenster geöffnet. Ist new 2, wird nach Möglichkeit eine neue Browserseite („Tab“) geöffnet. Ist autoraise True, wird das Fenster nach Möglichkeit nach vorn geholt. Beachte, dass das unter vielen Fenstermanagern unabhängig von dieser Einstellung geschieht.

Gibt True zurück, wenn ein Browser erfolgreich gestartet wurde, sonst False.

Beachte, dass sich auf manchen Plattformen mit dieser Funktion auch ein Dateiname öffnen lässt und das vom Betriebssystem zugeordnete Programm startet. Unterstützt oder portabel ist das jedoch nicht.

Löst ein Auditing-Ereignis webbrowser.open mit dem Argument url aus.

webbrowser.open_new(url)

Öffnet url nach Möglichkeit in einem neuen Fenster des voreingestellten Browsers, andernfalls im einzigen Browserfenster.

Gibt True zurück, wenn ein Browser erfolgreich gestartet wurde, sonst False.

webbrowser.open_new_tab(url)

Öffnet url nach Möglichkeit in einer neuen Seite („Tab“) des voreingestellten Browsers, andernfalls gleichbedeutend mit open_new().

Gibt True zurück, wenn ein Browser erfolgreich gestartet wurde, sonst False.

webbrowser.get(using=None)

Gibt ein Steuerungsobjekt für den Browsertyp using zurück. Ist using None, wird ein Steuerungsobjekt für einen voreingestellten Browser zurückgegeben, der zur Umgebung des Aufrufers passt.

webbrowser.register(name, constructor, instance=None, *, preferred=False)

Registriert den Browsertyp name. Ist ein Browsertyp registriert, kann die Funktion get() ein Steuerungsobjekt für diesen Browsertyp zurückgeben. Wird instance nicht angegeben oder ist es None, wird constructor bei Bedarf ohne Parameter aufgerufen, um eine Instanz zu erzeugen. Wird instance angegeben, wird constructor nie aufgerufen und darf None sein.

Setzt du preferred auf True, wird dieser Browser bei einem get()-Aufruf ohne Argument bevorzugt zurückgegeben. Andernfalls ist dieser Einstiegspunkt nur dann sinnvoll, wenn du entweder die Variable BROWSER setzen oder get() mit einem nicht leeren Argument aufrufen willst, das dem Namen eines von dir angemeldeten Handlers entspricht.

Geändert in Version 3.7: Der Parameter preferred, der nur als Schlüsselwort übergeben werden kann, wurde hinzugefügt.

Eine Reihe von Browsertypen ist vordefiniert. Diese Tabelle nennt die Typnamen, die an die Funktion get() übergeben werden können, und die zugehörigen Instanzierungen der Steuerungsklassen, die alle in diesem Modul definiert sind.

Typname

Klassenname

Hinweise

'mozilla'

Mozilla('mozilla')

'firefox'

Mozilla('mozilla')

'epiphany'

Epiphany('epiphany')

'kfmclient'

Konqueror()

(1)

'konqueror'

Konqueror()

(1)

'kfm'

Konqueror()

(1)

'opera'

Opera()

'links'

GenericBrowser('links')

'elinks'

Elinks('elinks')

'lynx'

GenericBrowser('lynx')

'w3m'

GenericBrowser('w3m')

'windows-default'

WindowsDefault

(2)

'macos'

MacOS('default')

(3)

'safari'

MacOS('safari')

(3)

'chrome'

MacOS('google chrome')

(3)

'firefox'

MacOS('firefox')

(3)

'google-chrome'

Chrome('google-chrome')

'chromium'

Chromium('chromium')

'chromium-browser'

Chromium('chromium-browser')

'iosbrowser'

IOSBrowser

(4)

Hinweise:

  1. „Konqueror“ ist der Dateimanager der KDE-Arbeitsumgebung für Unix, und seine Verwendung ist nur sinnvoll, wenn KDE läuft. Eine Möglichkeit, KDE zuverlässig zu erkennen, wäre wünschenswert, denn die Variable KDEDIR genügt dafür nicht. Beachte außerdem, dass der Name „kfm“ auch dann verwendet wird, wenn der Befehl konqueror mit KDE 2 zum Einsatz kommt — die Implementierung wählt selbst die beste Vorgehensweise, um Konqueror zu starten.

  2. Nur auf Windows-Plattformen.

  3. Nur unter macOS.

  4. Nur unter iOS.

Added in version 3.2: Eine neue Klasse MacOSXOSAScript wurde hinzugefügt und wird auf dem Mac anstelle der bisherigen Klasse MacOSX verwendet. Damit lassen sich auch Browser öffnen, die derzeit nicht als Voreinstellung des Betriebssystems eingetragen sind.

Added in version 3.3: Unterstützung für Chrome und Chromium wurde hinzugefügt.

Geändert in Version 3.12: Die Unterstützung für mehrere veraltete Browser wurde entfernt. Dazu gehören Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape und Firefox in den Versionen 35 und darunter.

Geändert in Version 3.13: Unterstützung für iOS wurde hinzugefügt.

Added in version 3.15: MacOS wurde als Ersatz für MacOSXOSAScript hinzugefügt und öffnet Browser über /usr/bin/open statt über osascript.

Veraltet seit Version 3.15, wird in Version 3.17 entfernt: MacOSXOSAScript ist veraltet, verwende stattdessen MacOS. /usr/bin/open statt osascript zu verwenden, verbessert Sicherheit und Bedienbarkeit: osascript kann auf verwalteten Systemen gesperrt sein, weil es sich als allgemeiner Skriptinterpreter missbrauchen lässt.

Hier ein paar einfache Beispiele:

url = 'https://docs.python.org/'

# URL in einem neuen Tab öffnen, wenn schon ein Browserfenster offen ist.
webbrowser.open_new_tab(url)

# URL in neuem Fenster öffnen und es nach Möglichkeit nach vorn holen.
webbrowser.open_new(url)

Objekte zur Browsersteuerung

Objekte zur Browsersteuerung stellen das Attribut name sowie die folgenden drei Methoden bereit, die den Hilfsfunktionen auf Modulebene entsprechen:

controller.name

Systemabhängiger Name des Browsers.

controller.open(url, new=0, autoraise=True)

Zeigt url im Browser an, den dieses Steuerungsobjekt bedient. Ist new 1, wird nach Möglichkeit ein neues Browserfenster geöffnet. Ist new 2, wird nach Möglichkeit eine neue Browserseite („Tab“) geöffnet.

controller.open_new(url)

Öffnet url nach Möglichkeit in einem neuen Fenster des Browsers, den dieses Steuerungsobjekt bedient, andernfalls im einzigen Browserfenster. Alias open_new().

controller.open_new_tab(url)

Öffnet url nach Möglichkeit in einer neuen Seite („Tab“) des Browsers, den dieses Steuerungsobjekt bedient, andernfalls gleichbedeutend mit open_new().

Fußnoten