# `webbrowser` — Convenient web-browser controller

Código-fonte: Lib/webbrowser.py

O módulo `webbrowser` fornece uma interface de alto nível para permitir a exibição de documentos baseados na web para os usuários. Na maioria das circunstâncias, simplesmente chamar a função `open()` deste módulo fará a coisa certa.

No Unix, navegadores gráficos são preferidos no X11, mas navegadores em modo texto serão usados se navegadores gráficos não estiverem disponíveis ou um display X11 não estiver disponível. Se navegadores em modo texto forem usados, o processo de chamada será bloqueado até que o usuário saia do navegador.

Se a variável de ambiente `BROWSER` existir, ela será interpretada como a lista separada por `os.pathsep` de navegadores a serem tentados antes dos padrões da plataforma. Quando o valor de uma parte da lista contém a string `%s`, então ela é interpretada como uma linha de comando literal do navegador a ser usada com o argumento URL substituído por `%s`; se a parte não contiver `%s`, ela será simplesmente interpretada como o nome do navegador a ser iniciado. [1]

Para plataformas não-Unix, ou quando um navegador remoto estiver disponível no Unix, o processo de controle não esperará que o usuário termine de usar o navegador, mas permitirá que o navegador remoto mantenha suas próprias janelas na tela. Se os navegadores remotos não estiverem disponíveis no Unix, o processo de controle iniciará um novo navegador e aguardará.

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` opens the URL in a new browser window, if possible; `-t` opens the URL in a new browser page (“tab”). The options are, naturally, mutually exclusive. Usage example:

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

Disponibilidade: não Emscripten, não WASI.

Este módulo não funciona ou não está disponível em plataformas WebAssembly `wasm32-emscripten` e `wasm32-wasi`. Veja Plataformas WebAssembly para mais informações.

A seguinte exceção é definida:

exception webbrowser.Error

  Exceção levantada quando ocorre um erro de controle do navegador.

As seguintes funções estão definidas:

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

  Exibe url usando o navegador padrão. Se new for 0, o url será aberto na mesma janela do navegador, se possível. Se new for 1, uma nova janela do navegador será aberta, se possível. Se new for 2, uma nova página do navegador (“aba” ou “guia”) será aberta, se possível. Se autoraise for `True`, a janela será levantada, se possível (observe que, em muitos gerenciadores de janelas, isso ocorrerá independentemente da configuração dessa variável).

  Note que em algumas plataformas, tentar abrir um nome de arquivo usando esta função pode funcionar e iniciar o programa associado do sistema operacional. No entanto, isso não é suportado nem portátil.

  Levanta um evento de auditoria `webbrowser.open` com o argumento `url`.

webbrowser.open_new(url)

  Abre url em uma nova janela do navegador padrão, se possível; caso contrário, abre url na única janela do navegador.

webbrowser.open_new_tab(url)

  Abre url em uma nova página (“aba” ou “guia”) do navegador padrão, se possível, caso contrário, equivalente a `open_new()`.

webbrowser.get(using=None)

  Retorna um objeto controlador para o tipo de navegador using. Se using for `None`, retorna um controlador para um navegador padrão apropriado para o ambiente do chamador.

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

  Registra o tipo de navegador name. Uma vez que um tipo de navegador é registrado, a função `get()` pode retornar um controlador para esse tipo de navegador. Se instance não for fornecido, ou for `None`, constructor será chamado sem parâmetros para criar uma instância quando necessário. Se instance for fornecido, constructor nunca será chamado, e pode ser `None`.

  Definir preferred como `True` torna este navegador um resultado preferencial para uma chamada `get()` sem argumento. Caso contrário, este ponto de entrada só é útil se você planeja definir a variável `BROWSER` ou chamar `get()` com um argumento não vazio que corresponda ao nome de um manipulador que você declarar.

  Alterado na versão 3.7: Parâmetro somente-nomeado preferred foi adicionado.

Vários tipos de navegadores são predefinidos. Esta tabela fornece os nomes de tipos que podem ser passados para a função `get()` e as instanciações correspondentes para as classes do controlador, todas definidas neste módulo.

Nome do tipo | Nome da classe | Notas
--- | --- | ---
`'mozilla'` | `Mozilla('mozilla')` |
`'firefox'` | `Mozilla('mozilla')` |
`'netscape'` | `Mozilla('netscape')` |
`'galeon'` | `Galeon('galeon')` |
`'epiphany'` | `Galeon('epiphany')` |
`'skipstone'` | `BackgroundBrowser('skipstone')` |
`'kfmclient'` | `Konqueror()` | (1)
`'konqueror'` | `Konqueror()` | (1)
`'kfm'` | `Konqueror()` | (1)
`'mosaic'` | `BackgroundBrowser('mosaic')` |
`'opera'` | `Opera()` |
`'grail'` | `Grail()` |
`'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” 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. Somente em plataformas Windows.

3. Only on macOS platform.

Novo na versão 3.3: Foi adicionado suporte para Chrome/Chromium.

Descontinuado desde a versão 3.11, será removido na versão 3.13: `MacOSX` is deprecated, use `MacOSXOSAScript` instead.

Aqui estão alguns exemplos 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

Os controladores de navegador fornecem esses métodos que são paralelos a três das funções de conveniência em nível de módulo:

webbrowser.name

  Nome dependente do sistema para o navegador.

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

  Exibe url usando o navegador manipulado por este controlador. Se new for 1, uma nova janela do navegador será aberta, se possível. Se new for 2, uma nova página do navegador (“aba” ou “guia”) será aberta, se possível.

controller.open_new(url)

  Abre url em uma nova janela do navegador manipulado por este controlador, se possível, caso contrário, abra url na única janela do navegador. Apelido para `open_new()`.

controller.open_new_tab(url)

  Abre url em uma nova página (“aba” ou “guia”) do navegador manipulado por este controlador, se possível, caso contrário, equivalente a `open_new()`.

Notas de rodapé

[1]

Executáveis nomeados aqui sem um caminho completo serão pesquisados nos diretórios fornecidos na variável de ambiente `PATH`.