1:mod:`webbrowser` --- Convenient Web-browser controller
2=======================================================
3
4.. module:: webbrowser
5   :synopsis: Easy-to-use controller for Web browsers.
6
7.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
8.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9
10**Source code:** :source:`Lib/webbrowser.py`
11
12--------------
13
14The :mod:`webbrowser` module provides a high-level interface to allow displaying
15Web-based documents to users. Under most circumstances, simply calling the
16:func:`.open` function from this module will do the right thing.
17
18Under Unix, graphical browsers are preferred under X11, but text-mode browsers
19will be used if graphical browsers are not available or an X11 display isn't
20available.  If text-mode browsers are used, the calling process will block until
21the user exits the browser.
22
23If the environment variable :envvar:`BROWSER` exists, it is interpreted as the
24:data:`os.pathsep`-separated list of browsers to try ahead of the platform
25defaults.  When the value of a list part contains the string ``%s``, then it is
26interpreted as a literal browser command line to be used with the argument URL
27substituted for ``%s``; if the part does not contain ``%s``, it is simply
28interpreted as the name of the browser to launch. [1]_
29
30For non-Unix platforms, or when a remote browser is available on Unix, the
31controlling process will not wait for the user to finish with the browser, but
32allow the remote browser to maintain its own windows on the display.  If remote
33browsers are not available on Unix, the controlling process will launch a new
34browser and wait.
35
36The script :program:`webbrowser` can be used as a command-line interface for the
37module. It accepts a URL as the argument. It accepts the following optional
38parameters: ``-n`` opens the URL in a new browser window, if possible;
39``-t`` opens the URL in a new browser page ("tab"). The options are,
40naturally, mutually exclusive.  Usage example::
41
42   python -m webbrowser -t "http://www.python.org"
43
44The following exception is defined:
45
46
47.. exception:: Error
48
49   Exception raised when a browser control error occurs.
50
51The following functions are defined:
52
53
54.. function:: open(url, new=0, autoraise=True)
55
56   Display *url* using the default browser. If *new* is 0, the *url* is opened
57   in the same browser window if possible.  If *new* is 1, a new browser window
58   is opened if possible.  If *new* is 2, a new browser page ("tab") is opened
59   if possible.  If *autoraise* is ``True``, the window is raised if possible
60   (note that under many window managers this will occur regardless of the
61   setting of this variable).
62
63   Note that on some platforms, trying to open a filename using this function,
64   may work and start the operating system's associated program.  However, this
65   is neither supported nor portable.
66
67   .. audit-event:: webbrowser.open url webbrowser.open
68
69
70.. function:: open_new(url)
71
72   Open *url* in a new window of the default browser, if possible, otherwise, open
73   *url* in the only browser window.
74
75.. function:: open_new_tab(url)
76
77   Open *url* in a new page ("tab") of the default browser, if possible, otherwise
78   equivalent to :func:`open_new`.
79
80
81.. function:: get(using=None)
82
83   Return a controller object for the browser type *using*.  If *using* is
84   ``None``, return a controller for a default browser appropriate to the
85   caller's environment.
86
87
88.. function:: register(name, constructor, instance=None, *, preferred=False)
89
90   Register the browser type *name*.  Once a browser type is registered, the
91   :func:`get` function can return a controller for that browser type.  If
92   *instance* is not provided, or is ``None``, *constructor* will be called without
93   parameters to create an instance when needed.  If *instance* is provided,
94   *constructor* will never be called, and may be ``None``.
95
96   Setting *preferred* to ``True`` makes this browser a preferred result for
97   a :func:`get` call with no argument.  Otherwise, this entry point is only
98   useful if you plan to either set the :envvar:`BROWSER` variable or call
99   :func:`get` with a nonempty argument matching the name of a handler you
100   declare.
101
102   .. versionchanged:: 3.7
103      *preferred* keyword-only parameter was added.
104
105A number of browser types are predefined.  This table gives the type names that
106may be passed to the :func:`get` function and the corresponding instantiations
107for the controller classes, all defined in this module.
108
109+------------------------+-----------------------------------------+-------+
110| Type Name              | Class Name                              | Notes |
111+========================+=========================================+=======+
112| ``'mozilla'``          | :class:`Mozilla('mozilla')`             |       |
113+------------------------+-----------------------------------------+-------+
114| ``'firefox'``          | :class:`Mozilla('mozilla')`             |       |
115+------------------------+-----------------------------------------+-------+
116| ``'netscape'``         | :class:`Mozilla('netscape')`            |       |
117+------------------------+-----------------------------------------+-------+
118| ``'galeon'``           | :class:`Galeon('galeon')`               |       |
119+------------------------+-----------------------------------------+-------+
120| ``'epiphany'``         | :class:`Galeon('epiphany')`             |       |
121+------------------------+-----------------------------------------+-------+
122| ``'skipstone'``        | :class:`BackgroundBrowser('skipstone')` |       |
123+------------------------+-----------------------------------------+-------+
124| ``'kfmclient'``        | :class:`Konqueror()`                    | \(1)  |
125+------------------------+-----------------------------------------+-------+
126| ``'konqueror'``        | :class:`Konqueror()`                    | \(1)  |
127+------------------------+-----------------------------------------+-------+
128| ``'kfm'``              | :class:`Konqueror()`                    | \(1)  |
129+------------------------+-----------------------------------------+-------+
130| ``'mosaic'``           | :class:`BackgroundBrowser('mosaic')`    |       |
131+------------------------+-----------------------------------------+-------+
132| ``'opera'``            | :class:`Opera()`                        |       |
133+------------------------+-----------------------------------------+-------+
134| ``'grail'``            | :class:`Grail()`                        |       |
135+------------------------+-----------------------------------------+-------+
136| ``'links'``            | :class:`GenericBrowser('links')`        |       |
137+------------------------+-----------------------------------------+-------+
138| ``'elinks'``           | :class:`Elinks('elinks')`               |       |
139+------------------------+-----------------------------------------+-------+
140| ``'lynx'``             | :class:`GenericBrowser('lynx')`         |       |
141+------------------------+-----------------------------------------+-------+
142| ``'w3m'``              | :class:`GenericBrowser('w3m')`          |       |
143+------------------------+-----------------------------------------+-------+
144| ``'windows-default'``  | :class:`WindowsDefault`                 | \(2)  |
145+------------------------+-----------------------------------------+-------+
146| ``'macosx'``           | :class:`MacOSX('default')`              | \(3)  |
147+------------------------+-----------------------------------------+-------+
148| ``'safari'``           | :class:`MacOSX('safari')`               | \(3)  |
149+------------------------+-----------------------------------------+-------+
150| ``'google-chrome'``    | :class:`Chrome('google-chrome')`        |       |
151+------------------------+-----------------------------------------+-------+
152| ``'chrome'``           | :class:`Chrome('chrome')`               |       |
153+------------------------+-----------------------------------------+-------+
154| ``'chromium'``         | :class:`Chromium('chromium')`           |       |
155+------------------------+-----------------------------------------+-------+
156| ``'chromium-browser'`` | :class:`Chromium('chromium-browser')`   |       |
157+------------------------+-----------------------------------------+-------+
158
159Notes:
160
161(1)
162   "Konqueror" is the file manager for the KDE desktop environment for Unix, and
163   only makes sense to use if KDE is running.  Some way of reliably detecting KDE
164   would be nice; the :envvar:`KDEDIR` variable is not sufficient.  Note also that
165   the name "kfm" is used even when using the :program:`konqueror` command with KDE
166   2 --- the implementation selects the best strategy for running Konqueror.
167
168(2)
169   Only on Windows platforms.
170
171(3)
172   Only on Mac OS X platform.
173
174.. versionadded:: 3.3
175   Support for Chrome/Chromium has been added.
176
177Here are some simple examples::
178
179   url = 'http://docs.python.org/'
180
181   # Open URL in a new tab, if a browser window is already open.
182   webbrowser.open_new_tab(url)
183
184   # Open URL in new window, raising the window if possible.
185   webbrowser.open_new(url)
186
187
188.. _browser-controllers:
189
190Browser Controller Objects
191--------------------------
192
193Browser controllers provide these methods which parallel three of the
194module-level convenience functions:
195
196
197.. method:: controller.open(url, new=0, autoraise=True)
198
199   Display *url* using the browser handled by this controller. If *new* is 1, a new
200   browser window is opened if possible. If *new* is 2, a new browser page ("tab")
201   is opened if possible.
202
203
204.. method:: controller.open_new(url)
205
206   Open *url* in a new window of the browser handled by this controller, if
207   possible, otherwise, open *url* in the only browser window.  Alias
208   :func:`open_new`.
209
210
211.. method:: controller.open_new_tab(url)
212
213   Open *url* in a new page ("tab") of the browser handled by this controller, if
214   possible, otherwise equivalent to :func:`open_new`.
215
216
217.. rubric:: Footnotes
218
219.. [1] Executables named here without a full path will be searched in the
220       directories given in the :envvar:`PATH` environment variable.
221