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
68.. function:: open_new(url)
69
70   Open *url* in a new window of the default browser, if possible, otherwise, open
71   *url* in the only browser window.
72
73.. function:: open_new_tab(url)
74
75   Open *url* in a new page ("tab") of the default browser, if possible, otherwise
76   equivalent to :func:`open_new`.
77
78
79.. function:: get(using=None)
80
81   Return a controller object for the browser type *using*.  If *using* is
82   ``None``, return a controller for a default browser appropriate to the
83   caller's environment.
84
85
86.. function:: register(name, constructor, instance=None, *, preferred=False)
87
88   Register the browser type *name*.  Once a browser type is registered, the
89   :func:`get` function can return a controller for that browser type.  If
90   *instance* is not provided, or is ``None``, *constructor* will be called without
91   parameters to create an instance when needed.  If *instance* is provided,
92   *constructor* will never be called, and may be ``None``.
93
94   Setting *preferred* to ``True`` makes this browser a preferred result for
95   a :func:`get` call with no argument.  Otherwise, this entry point is only
96   useful if you plan to either set the :envvar:`BROWSER` variable or call
97   :func:`get` with a nonempty argument matching the name of a handler you
98   declare.
99
100   .. versionchanged:: 3.7
101      *preferred* keyword-only parameter was added.
102
103A number of browser types are predefined.  This table gives the type names that
104may be passed to the :func:`get` function and the corresponding instantiations
105for the controller classes, all defined in this module.
106
107+------------------------+-----------------------------------------+-------+
108| Type Name              | Class Name                              | Notes |
109+========================+=========================================+=======+
110| ``'mozilla'``          | :class:`Mozilla('mozilla')`             |       |
111+------------------------+-----------------------------------------+-------+
112| ``'firefox'``          | :class:`Mozilla('mozilla')`             |       |
113+------------------------+-----------------------------------------+-------+
114| ``'netscape'``         | :class:`Mozilla('netscape')`            |       |
115+------------------------+-----------------------------------------+-------+
116| ``'galeon'``           | :class:`Galeon('galeon')`               |       |
117+------------------------+-----------------------------------------+-------+
118| ``'epiphany'``         | :class:`Galeon('epiphany')`             |       |
119+------------------------+-----------------------------------------+-------+
120| ``'skipstone'``        | :class:`BackgroundBrowser('skipstone')` |       |
121+------------------------+-----------------------------------------+-------+
122| ``'kfmclient'``        | :class:`Konqueror()`                    | \(1)  |
123+------------------------+-----------------------------------------+-------+
124| ``'konqueror'``        | :class:`Konqueror()`                    | \(1)  |
125+------------------------+-----------------------------------------+-------+
126| ``'kfm'``              | :class:`Konqueror()`                    | \(1)  |
127+------------------------+-----------------------------------------+-------+
128| ``'mosaic'``           | :class:`BackgroundBrowser('mosaic')`    |       |
129+------------------------+-----------------------------------------+-------+
130| ``'opera'``            | :class:`Opera()`                        |       |
131+------------------------+-----------------------------------------+-------+
132| ``'grail'``            | :class:`Grail()`                        |       |
133+------------------------+-----------------------------------------+-------+
134| ``'links'``            | :class:`GenericBrowser('links')`        |       |
135+------------------------+-----------------------------------------+-------+
136| ``'elinks'``           | :class:`Elinks('elinks')`               |       |
137+------------------------+-----------------------------------------+-------+
138| ``'lynx'``             | :class:`GenericBrowser('lynx')`         |       |
139+------------------------+-----------------------------------------+-------+
140| ``'w3m'``              | :class:`GenericBrowser('w3m')`          |       |
141+------------------------+-----------------------------------------+-------+
142| ``'windows-default'``  | :class:`WindowsDefault`                 | \(2)  |
143+------------------------+-----------------------------------------+-------+
144| ``'macosx'``           | :class:`MacOSX('default')`              | \(3)  |
145+------------------------+-----------------------------------------+-------+
146| ``'safari'``           | :class:`MacOSX('safari')`               | \(3)  |
147+------------------------+-----------------------------------------+-------+
148| ``'google-chrome'``    | :class:`Chrome('google-chrome')`        |       |
149+------------------------+-----------------------------------------+-------+
150| ``'chrome'``           | :class:`Chrome('chrome')`               |       |
151+------------------------+-----------------------------------------+-------+
152| ``'chromium'``         | :class:`Chromium('chromium')`           |       |
153+------------------------+-----------------------------------------+-------+
154| ``'chromium-browser'`` | :class:`Chromium('chromium-browser')`   |       |
155+------------------------+-----------------------------------------+-------+
156
157Notes:
158
159(1)
160   "Konqueror" is the file manager for the KDE desktop environment for Unix, and
161   only makes sense to use if KDE is running.  Some way of reliably detecting KDE
162   would be nice; the :envvar:`KDEDIR` variable is not sufficient.  Note also that
163   the name "kfm" is used even when using the :program:`konqueror` command with KDE
164   2 --- the implementation selects the best strategy for running Konqueror.
165
166(2)
167   Only on Windows platforms.
168
169(3)
170   Only on Mac OS X platform.
171
172.. versionadded:: 3.3
173   Support for Chrome/Chromium has been added.
174
175Here are some simple examples::
176
177   url = 'http://docs.python.org/'
178
179   # Open URL in a new tab, if a browser window is already open.
180   webbrowser.open_new_tab(url)
181
182   # Open URL in new window, raising the window if possible.
183   webbrowser.open_new(url)
184
185
186.. _browser-controllers:
187
188Browser Controller Objects
189--------------------------
190
191Browser controllers provide these methods which parallel three of the
192module-level convenience functions:
193
194
195.. method:: controller.open(url, new=0, autoraise=True)
196
197   Display *url* using the browser handled by this controller. If *new* is 1, a new
198   browser window is opened if possible. If *new* is 2, a new browser page ("tab")
199   is opened if possible.
200
201
202.. method:: controller.open_new(url)
203
204   Open *url* in a new window of the browser handled by this controller, if
205   possible, otherwise, open *url* in the only browser window.  Alias
206   :func:`open_new`.
207
208
209.. method:: controller.open_new_tab(url)
210
211   Open *url* in a new page ("tab") of the browser handled by this controller, if
212   possible, otherwise equivalent to :func:`open_new`.
213
214
215.. rubric:: Footnotes
216
217.. [1] Executables named here without a full path will be searched in the
218       directories given in the :envvar:`PATH` environment variable.
219