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