webbrowser — Convenient web-browser controller方便的web浏览器控制器

Source code: Lib/webbrowser.py

---

The webbrowser module provides a high-level interface to allow displaying web-based documents to users. 该模块提供了一个高级界面，允许向用户显示基于web的文档。Under most circumstances, simply calling the open() function from this module will do the right thing.在大多数情况下，只需从该模块调用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. 在Unix下，X11下首选图形浏览器，但如果图形浏览器不可用或X11显示器不可用，则将使用文本模式浏览器。If text-mode browsers are used, the calling process will block until the user exits the browser.如果使用文本模式浏览器，调用过程将被阻止，直到用户退出浏览器。

If the environment variable BROWSER exists, it is interpreted as the os.pathsep-separated list of browsers to try ahead of the platform defaults. 如果存在环境变量BROWSER，则将其解释为os.pathsep分隔的浏览器列表，以在平台默认值之前进行尝试。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. 当列表部分的值包含字符串%s时，则将其解释为文字浏览器命令行，用于将参数URL替换为%s；如果该部分不包含%s，则只会将其解释为要启动的浏览器的名称。1

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. 对于非Unix平台，或者当Unix上有远程浏览器时，控制过程不会等待用户完成浏览器，而是允许远程浏览器在显示器上维护自己的窗口。If remote browsers are not available on Unix, the controlling process will launch a new browser and wait.如果远程浏览器在Unix上不可用，控制进程将启动新浏览器并等待。

The script webbrowser can be used as a command-line interface for the module. 脚本webbrowser可以用作模块的命令行界面。It accepts a URL as the argument. 它接受URL作为参数。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”). 它接受以下可选参数：-n如果可能，在新的浏览器窗口中打开URL，-t在新的浏览器页面（“选项卡”）中打开URL。The options are, naturally, mutually exclusive. 这些选择自然是相互排斥的。Usage example:使用示例：

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

The following exception is defined:定义了以下例外情况：

exceptionwebbrowser.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. 使用默认浏览器显示url。If new is 0, the url is opened in the same browser window if possible. 如果new为0，则尽可能在同一浏览器窗口中打开url。If new is 1, a new browser window is opened if possible. 如果new为1，则可能会打开一个新的浏览器窗口。If new is 2, a new browser page (“tab”) is opened if possible. 如果new为2，则在可能的情况下打开一个新的浏览器页面（“选项卡”）。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).如果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.然而，这既不受支持，也不可移植。

Raises an auditing event webbrowser.open with argument url.使用参数url引发审核事件webbrowser.open。

webbrowser.open_new(url)

Open url in a new window of the default browser, if possible, otherwise, open url in the only browser window.在默认浏览器的新窗口中打开url，如果可能，否则，在唯一的浏览器窗口中打开url。

webbrowser.open_new_tab(url)

Open url in a new page (“tab”) of the default browser, if possible, otherwise equivalent to open_new().如果可能，在默认浏览器的新页面（“选项卡”）中打开url，否则相当于webbrowser.open。

webbrowser.get(using=None)

Return a controller object for the browser type using. 返回针对浏览器类型using的控制器对象。If using is None, return a controller for a default browser appropriate to the caller’s environment.如果using为None，则返回适用于调用方环境的默认浏览器的控制器。

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

Register the browser type name. 注册浏览器类型name。Once a browser type is registered, the get() function can return a controller for that browser type. 注册浏览器类型后，get()函数可以返回该浏览器类型的控制器。If instance is not provided, or is None, constructor will be called without parameters to create an instance when needed. 如果未提供instance，或者为None，则在需要时将调用constructor而不带参数来创建实例。If instance is provided, constructor will never be called, and may be None.若提供了instance，则永远不会调用constructor，而且可能是None。

Setting preferred to True makes this browser a preferred result for a get() call with no argument. 将preferred设置为True使此浏览器成为无参数get()调用的首选结果。Otherwise, 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()时，此入口点才有用。

Changed in version 3.7:版本3.7中更改： preferred keyword-only parameter was added.仅添加了关键字参数。

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'	MacOSXOSAScript('default')	(3)
'safari'	MacOSXOSAScript('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. “Konqueror”是用于Unix的KDE桌面环境的文件管理器，只有在KDE正在运行时才有意义。Some way of reliably detecting KDE would be nice; the KDEDIR variable is not sufficient. 一些可靠检测KDE的方法会很好；KDEDIR变量不足。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.还要注意，即使在KDE 2中使用konqueror命令时，也会使用名称“kfm”-实现选择运行konqueror的最佳策略。

2. Only on Windows platforms.仅在Windows平台上。

3. Only on macOS platform.仅在macOS平台上。

New in version 3.3.版本3.3中新增。Support for Chrome/Chromium has been added.添加了对铬/铬的支持。

Here are some simple examples:以下是一些简单的示例：

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)

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. 使用此控制器处理的浏览器显示url。If new is 1, a new browser window is opened if possible. 如果new为1，则可能会打开一个新的浏览器窗口。If new is 2, a new browser page (“tab”) is opened if possible.如果new为2，则在可能的情况下打开一个新的浏览器页面（“选项卡”）。

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. 在该控制器处理的浏览器的新窗口中打开url，如果可能，否则，在唯一的浏览器窗口中打开url。Alias open_new().别名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().如果可能，在该控制器处理的浏览器的新页面（“选项卡”）中打开url，否则相当于open_new()。

Footnotes

1

Executables named here without a full path will be searched in the directories given in the PATH environment variable.将在PATH环境变量中给定的目录中搜索在此命名但没有完整路径的可执行文件。