webbrowser — Convenient web-browser controller

Código fuente: Lib/webbrowser.py

El módulo webbrowser proporciona una interfaz de alto nivel que permite mostrar documentos basados en web a los usuarios. En la mayoría de circunstancias, simplemente llamar a la función open() desde este módulo hará lo correcto.

En Unix, son privilegiados los navegadores gráficos bajo X11, pero serán usados navegadores en modo texto si los navegadores gráficos no están disponibles o un display X11 no está disponible. Si se usan navegadores en modo texto, el proceso invocador será bloqueado hasta que el usuario salga del navegador.

If the environment variable BROWSER exists, it is interpreted as the os.pathsep-separated list of browsers to try ahead of the platform defaults. When the value of a list part contains the string %s, then it is interpreted as a literal browser command line to be used with the argument URL substituted for %s; if the value is a single word that refers to one of the already registered browsers this browser is added to the front of the search list; if the part does not contain %s, it is simply interpreted as the name of the browser to launch. [1]

Distinto en la versión 3.14: The BROWSER variable can now also be used to reorder the list of platform defaults. This is particularly useful on macOS where the platform defaults do not refer to command-line tools on PATH.

En plataformas no Unix o cuando está disponible un navegador remoto en Unix, el proceso de control no esperará a que el usuario finalice el navegador, sino que permitirá al navegador remoto mantener su propia ventana en la pantalla. Si no están disponibles navegadores remotos en Unix, el proceso de control lanzará un nuevo navegador y esperará.

On iOS, the BROWSER environment variable, as well as any arguments controlling autoraise, browser preference, and new tab/window creation will be ignored. Web pages will always be opened in the user’s preferred browser, in a new tab, with the browser being brought to the foreground. The use of the webbrowser module on iOS requires the ctypes module. If ctypes isn’t available, calls to open() will fail.

The script webbrowser can be used as a command-line interface for the module. It accepts a URL as the argument. It accepts the following optional parameters:

-n, --new-window

Opens the URL in a new browser window, if possible.

-t, --new-tab

Opens the URL in a new browser tab.

The options are, naturally, mutually exclusive. Usage example:

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

Availability: not WASI, not Android.

La siguiente excepción es definida:

exception webbrowser.Error

Excepción generada cuando ocurre un error de control de navegador.

Las siguientes funciones son definidas:

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

Muestra url usando el navegador por defecto. Si new es 0, se abre la url en la misma ventana del navegador si es posible. Si new es 1, se abre una nueva ventana del navegador si es posible. Si new es 2, se abre una nueva página del navegador («pestaña») si es posible. Si autoraise es True, la ventana es lanzada si es posible (ten en cuenta que bajo muchos gestores de ventana esto ocurrirá independientemente de la configuración de esta variable).

Returns True if a browser was successfully launched, False otherwise.

Ten en cuenta que en algunas plataformas, tratar de abrir un nombre de archivo usando esta función puede funcionar e iniciar el programa asociado del sistema operativo. Sin embargo, esto no es soportado ni portable.

Lanza un evento de auditoría webbrowser.open con el argumento url.

webbrowser.open_new(url)

Abre url en una nueva ventana del navegador por defecto, si es posible, si no, abre url en la única ventana del navegador.

Returns True if a browser was successfully launched, False otherwise.

webbrowser.open_new_tab(url)

Abre url en una nueva página («pestaña») del navegador por defecto, si es posible, si no equivale a open_new().

Returns True if a browser was successfully launched, False otherwise.

webbrowser.get(using=None)

Retorna un objeto de controlador para el tipo de navegador using. Si using es None, retorna un controlador de un navegador por defecto apropiado para el entorno del invocador.

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

Registra el tipo de navegador name. Una vez que el tipo de navegador es registrado, la función get() puede retornar un controlador para ese tipo de navegador. Si no se provee instance o es None, constructor será invocado sin parámetros al crear una instancia cuando sea necesario. Si se provee instance, constructor no será nunca invocado y puede ser None.

Definir preferred a True hace de este navegador un resultado preferido para una invocación get() sin argumento. De otra manera, este punto de entrada sólo es útil si planeas definir la variable BROWSER o invocar get() con un argumento no vacío correspondiendo con el nombre de un manejador que declaras.

Distinto en la versión 3.7: fue añadido el parámetro sólo de palabra clave preferred.

Un número de tipos de navegador son predefinidos. Esta tabla muestra los nombres de los tipos que se pueden pasar a la función get() y las instanciaciones correspondientes para las clases de los controladores, todas definidas en este módulo.

Nombre de tipo

Nombre de clase

Notas

'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)

'macosx'

MacOSXOSAScript('default')

(3)

'safari'

MacOSXOSAScript('safari')

(3)

'google-chrome'

Chrome('google-chrome')

'chrome'

Chrome('chrome')

'chromium'

Chromium('chromium')

'chromium-browser'

Chromium('chromium-browser')

'iosbrowser'

IOSBrowser

(4)

Notas:

  1. «Konqueror» is the file manager for the KDE desktop environment for Unix, and only makes sense to use if KDE is running. Some way of reliably detecting KDE would be nice; the KDEDIR variable is not sufficient. Note also that the name «kfm» is used even when using the konqueror command with KDE 2 — the implementation selects the best strategy for running Konqueror.

  2. Sólo en plataformas Windows.

  3. Only on macOS.

  4. Only on iOS.

Added in version 3.2: A new MacOSXOSAScript class has been added and is used on Mac instead of the previous MacOSX class. This adds support for opening browsers not currently set as the OS default.

Added in version 3.3: Ha sido añadido soporte para Chrome/Chromium.

Distinto en la versión 3.12: Se ha eliminado el soporte para varios navegadores obsoletos. Los navegadores eliminados son Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape y Firefox versión 35 e inferiores.

Distinto en la versión 3.13: Support for iOS has been added.

Aquí están algunos ejemplos simples:

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

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)

Objetos controladores de navegador

Browser controllers provide the name attribute, and the following three methods which parallel module-level convenience functions:

controller.name

Nombre dependiente del sistema para el navegador.

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

Despliega url usando el navegador manejado por este controlador. Si new es 1, se abre una nueva ventana del navegador si es posible. Si new es 2, se abre una nueva página del navegador («pestaña») si es posible.

controller.open_new(url)

Abre url en una nueva ventana del navegador manejado por este controlador, si es posible, si no, abre url en la única ventana del navegador. Alias open_new().

controller.open_new_tab(url)

Abre url en una nueva página («pestaña») del navegador manejado por este controlador, si es posible, si no equivale a open_new().

Notas al pie