# `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.

Si existe la variable de entorno `BROWSER`, esta es interpretada como la lista de navegadores a probar antes de los predeterminados de la plataforma, separados por `os.pathsep`. Cuando el valor de una parte de la lista contiene la cadena `%s`, este es interpretado como una línea de comando literal de un navegador a usar con el argumento URL substituido por `%s`; si la parte no contiene `%s`, esta se interpreta simplemente como el nombre del navegador a lanzar. [1]

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á.

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 Emscripten, not WASI.

Este módulo no funciona o no está disponible en las plataformas WebAssembly `wasm32-emscripten` y `wasm32-wasi`. Consulte Plataformas WebAssembly para obtener más información.

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

Notas:

1. «Konqueror» es el manejador de archivos para el entorno de escritorio KDE para Unix y sólo tiene sentido usarlo si KDE está en ejecución. Alguna forma de detectar de manera confiable KDE sería genial; la variable `KDEDIR` no es suficiente. Ten en cuenta también que el nombre «kfm» es usado incluso utilizando el comando konqueror con KDE 2 — la implementación selecciona la mejor estrategia para ejecutar Konqueror.

2. Sólo en plataformas Windows.

3. Solo en la plataforma macOS.

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.

Deprecated since version 3.11, will be removed in version 3.13: `MacOSX` es obsoleto, utilice `MacOSXOSAScript` en su lugar.

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

Los controladores de navegador proveen aquellos métodos que son paralelos a tres de las funciones de conveniencia a nivel del módulo:

webbrowser.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

[1]

Los ejecutables nombrados aquí sin una ruta completa serán buscados en los directorios dados en la variable de entorno `PATH`.