Python标准库3.4.3-webbrowser-21.1

21.1. webbrowser — Convenient Web-browser controller

Source code: Lib/webbrowser.py  翻译：Z.F.

---

The webbrowser module provides a high-level interface to allow displaying Web-based documents to users. Under most circumstances, simply calling the open() function from this module will do the right thing.

 webbrowser模块提供一个高阶的接口来为用户显示基于web的文档，在大多数情况下，简单的调用open()函数就可以正常的工作。

Under Unix, graphical browsers are preferred under X11, but text-mode browsers will be used if graphical browsers are not available or an X11 display isn’t available. If text-mode browsers are used, the calling process will block until the user exits the browser.

 在Unix环境中，图形化的浏览器有更高的优先级在X11环境中，如果图形化的浏览器不可用，或者X11图形显示不可用，则使用文本模式的浏览器。如果使用文本模式的浏览器，则调用进程是阻塞的，直到用户退出。

If the environment variable BROWSER exists, it is interpreted as the os.pathsep-separated list of browsers to try ahead of the 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 part does not contain %s, it is simply interpreted as the name of the browser to launch. [1]

如果有环境变量 BROWSER，它被解释为os.pathsep分割的浏览器列表，并处于系统默认值之前，当列表的值之中含有字符串%s时，它将被解释为一个字面的浏览器命令，并使用url参数代替%s,如果不包含%s,则简单的解释为要使用的浏览器的名字。

For non-Unix platforms, or when a remote browser is available on Unix, the controlling process will not wait for the user to finish with the browser, but allow the remote browser to maintain its own windows on the display. If remote browsers are not available on Unix, the controlling process will launch a new browser and wait。

对于非Unix平台，或者一个UNIX下可用的远程浏览器 ，管理进程将不等待用户的浏览器结束，但是允许远程的浏览器保持她自己的窗口显示。如果远程浏览器在Unix系统不可用，管理进程将载入一个新的浏览器并等待。

The script webbrowser can be used as a command-line interface for the module. It accepts an 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:

webbrowser可以作为该模块一个命令行接口来使用，它接受一个URL作为参数，-n  在一个新窗口中打开url,如果有可能，-t将在一个新的标签页打开该url,2个选项是互斥的。 例如：

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

The following exception is defined:

exception webbrowser.Error

Exception raised when a browser control error occurs.

The following functions are defined:

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

Display url using the default browser. If new is 0, the url is opened in the same browser window if possible. If new is 1, a new browser window is opened if possible. If new is 2, a new browser page (“tab”) is opened if possible. If autoraise is True, the window is raised if possible (note that under many window managers this will occur regardless of the setting of this variable).

使用默认的浏览器显示这个URL,如果参数new是0，url将在同一个浏览器窗口中被打开，如果new是1，将打开一个新的浏览器窗口来加载该url,如果new是2，则在一个新的标签页中打开。 如果autoraise被设置为true,则窗口将被自动激活。（请注意：有许多窗口管理器将直接忽略该变量的设置）

Note that on some platforms, trying to open a filename using this function, may work and start the operating system’s associated program. However, this is neither supported nor portable.

在一些平台下，如果试图通过该函数来打开一个文件名，将启动操作系统默认的程序来打开。 但是，这种方法是不被支持和不易于移植的。

webbrowser.open_new(url)

Open url in a new window of the default browser, if possible, otherwise, open url in the only browser window.

新开一个默认浏览器窗口，打开ur，l否则，仅仅是在一个浏览器窗口中打开url.

webbrowser.open_new_tab(url)

Open url in a new page (“tab”) of the default browser, if possible, otherwise equivalent to open_new().

webbrowser.get(using=None)

Return a controller object for the browser type using. If using is None, return a controller for a default browser appropriate to the caller’s environment.

返回一个特定浏览器类型的控制对象。如果使用None, 返回一个合乎调用者环境的默认的浏览器对象。

webbrowser.register(name, constructor, instance=None)

Register the browser type name. Once a browser type is registered, the get() function can return a controller for that browser type. If instance is not provided, or is None, constructor will be called without parameters to create an instance when needed. If instance is provided, constructor will never be called, and may be None.

注册浏览器类型名。当一个浏览器类型被注册，  get()函数将返回一个该浏览器类型的控制器。如果instance参数没有被提供，或者是None,constructor将在需要的时候被无参数调用来创建一个实例。如果instance被提供了，则constructor将永不会被调用，或者被设置为None。

This entry point is only useful if you plan to either set the BROWSER variable or call get() with a nonempty argument matching the name of a handler you declare.

这个入口函数仅仅在你设置 BROWSER 变量 或者用非空的你自己声明的处理函数做参数，调用 get()时有用。

A number of browser types are predefined. This table gives the type names that may be passed to the get() function and the corresponding instantiations for the controller classes, all defined in this module.

若干浏览器类型已经被预先定义。下面这个表给出了可以传递给 get()函数的类型名字和相应实例的类名。所有的这些，都在此模块中定义过了。

Type Name	Class Name	Notes
'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'	MacOSX('default')	(3)
'safari'	MacOSX('safari')	(3)
'google-chrome'	Chrome('google-chrome')
'chrome'	Chrome('chrome')
'chromium'	Chromium('chromium')
'chromium-browser'	Chromium('chromium-browser')

Notes:

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. Only on Windows platforms.
3. Only on Mac OS X platform.

New in version 3.3: Support for Chrome/Chromium has been added.

Here are some simple examples:

url = 'http://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)

21.1.1. Browser Controller Objects

Browser controllers provide these methods which parallel three of the module-level convenience functions:

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

Display url using the browser handled by this controller. If new is 1, a new browser window is opened if possible. If new is 2, a new browser page (“tab”) is opened if possible.

controller.open_new(url)

Open url in a new window of the browser handled by this controller, if possible, otherwise, open url in the only browser window. Alias open_new().

controller.open_new_tab(url)

Open url in a new page (“tab”) of the browser handled by this controller, if possible, otherwise equivalent to open_new().

Footnotes

[1]	Executables named here without a full path will be searched in the directories given in the PATH environment variable.