Debian Codegraph @

Doc/library/webbrowser.rst

raw
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. <[email protected]>
8 .. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
9
10 **Source code:** :source:`Lib/webbrowser.py`
11
12 --------------
13
14 The :mod:`!webbrowser` module provides a high-level interface to allow displaying
15 web-based documents to users. Under most circumstances, simply calling the
16 :func:`.open` function from this module will do the right thing.
17
18 Under Unix, graphical browsers are preferred under X11, but text-mode browsers
19 will be used if graphical browsers are not available or an X11 display isn't
20 available. If text-mode browsers are used, the calling process will block until
21 the user exits the browser.
22
23 If 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
25 defaults. When the value of a list part contains the string ``%s``, then it is
26 interpreted as a literal browser command line to be used with the argument URL
27 substituted for ``%s``; if the value is a single word that refers to one of the
28 already registered browsers this browser is added to the front of the search list;
29 if the part does not contain ``%s``, it is simply interpreted as the name of the
30 browser to launch. [1]_
31
32 .. versionchanged:: 3.14
33
34 The :envvar:`BROWSER` variable can now also be used to reorder the list of
35 platform defaults. This is particularly useful on macOS where the platform
36 defaults do not refer to command-line tools on :envvar:`PATH`.
37
38
39 For non-Unix platforms, or when a remote browser is available on Unix, the
40 controlling process will not wait for the user to finish with the browser, but
41 allow the remote browser to maintain its own windows on the display. If remote
42 browsers are not available on Unix, the controlling process will launch a new
43 browser and wait.
44
45 On iOS, the :envvar:`BROWSER` environment variable, as well as any arguments
46 controlling autoraise, browser preference, and new tab/window creation will be
47 ignored. Web pages will *always* be opened in the user's preferred browser, in
48 a new tab, with the browser being brought to the foreground. The use of the
49 :mod:`!webbrowser` module on iOS requires the :mod:`ctypes` module. If
50 :mod:`ctypes` isn't available, calls to :func:`.open` will fail.
51
52 .. _webbrowser-cli:
53
54 Command-line interface
55 ----------------------
56
57 .. program:: webbrowser
58
59 The script :program:`webbrowser` can be used as a command-line interface for the
60 module. It accepts a URL as the argument. It accepts the following optional
61 parameters:
62
63 .. option:: -n, --new-window
64
65 Opens the URL in a new browser window, if possible.
66
67 .. option:: -t, --new-tab
68
69 Opens the URL in a new browser tab.
70
71 The options are, naturally, mutually exclusive. Usage example:
72
73 .. code-block:: bash
74
75 python -m webbrowser -t "https://www.python.org"
76
77 .. availability:: not WASI, not Android.
78
79 The following exception is defined:
80
81
82 .. exception:: Error
83
84 Exception raised when a browser control error occurs.
85
86 The following functions are defined:
87
88
89 .. function:: open(url, new=0, autoraise=True)
90
91 Display *url* using the default browser. If *new* is 0, the *url* is opened
92 in the same browser window if possible. If *new* is 1, a new browser window
93 is opened if possible. If *new* is 2, a new browser page ("tab") is opened
94 if possible. If *autoraise* is ``True``, the window is raised if possible
95 (note that under many window managers this will occur regardless of the
96 setting of this variable).
97
98 Returns ``True`` if a browser was successfully launched, ``False`` otherwise.
99
100 Note that on some platforms, trying to open a filename using this function,
101 may work and start the operating system's associated program. However, this
102 is neither supported nor portable.
103
104 .. audit-event:: webbrowser.open url webbrowser.open
105
106
107 .. function:: open_new(url)
108
109 Open *url* in a new window of the default browser, if possible, otherwise, open
110 *url* in the only browser window.
111
112 Returns ``True`` if a browser was successfully launched, ``False`` otherwise.
113
114
115 .. function:: open_new_tab(url)
116
117 Open *url* in a new page ("tab") of the default browser, if possible, otherwise
118 equivalent to :func:`open_new`.
119
120 Returns ``True`` if a browser was successfully launched, ``False`` otherwise.
121
122
123 .. function:: get(using=None)
124
125 Return a controller object for the browser type *using*. If *using* is
126 ``None``, return a controller for a default browser appropriate to the
127 caller's environment.
128
129
130 .. function:: register(name, constructor, instance=None, *, preferred=False)
131
132 Register the browser type *name*. Once a browser type is registered, the
133 :func:`get` function can return a controller for that browser type. If
134 *instance* is not provided, or is ``None``, *constructor* will be called without
135 parameters to create an instance when needed. If *instance* is provided,
136 *constructor* will never be called, and may be ``None``.
137
138 Setting *preferred* to ``True`` makes this browser a preferred result for
139 a :func:`get` call with no argument. Otherwise, this entry point is only
140 useful if you plan to either set the :envvar:`BROWSER` variable or call
141 :func:`get` with a nonempty argument matching the name of a handler you
142 declare.
143
144 .. versionchanged:: 3.7
145 *preferred* keyword-only parameter was added.
146
147 A number of browser types are predefined. This table gives the type names that
148 may be passed to the :func:`get` function and the corresponding instantiations
149 for the controller classes, all defined in this module.
150
151 +------------------------+-----------------------------------------+-------+
152 | Type Name | Class Name | Notes |
153 +========================+=========================================+=======+
154 | ``'mozilla'`` | ``Mozilla('mozilla')`` | |
155 +------------------------+-----------------------------------------+-------+
156 | ``'firefox'`` | ``Mozilla('mozilla')`` | |
157 +------------------------+-----------------------------------------+-------+
158 | ``'epiphany'`` | ``Epiphany('epiphany')`` | |
159 +------------------------+-----------------------------------------+-------+
160 | ``'kfmclient'`` | ``Konqueror()`` | \(1) |
161 +------------------------+-----------------------------------------+-------+
162 | ``'konqueror'`` | ``Konqueror()`` | \(1) |
163 +------------------------+-----------------------------------------+-------+
164 | ``'kfm'`` | ``Konqueror()`` | \(1) |
165 +------------------------+-----------------------------------------+-------+
166 | ``'opera'`` | ``Opera()`` | |
167 +------------------------+-----------------------------------------+-------+
168 | ``'links'`` | ``GenericBrowser('links')`` | |
169 +------------------------+-----------------------------------------+-------+
170 | ``'elinks'`` | ``Elinks('elinks')`` | |
171 +------------------------+-----------------------------------------+-------+
172 | ``'lynx'`` | ``GenericBrowser('lynx')`` | |
173 +------------------------+-----------------------------------------+-------+
174 | ``'w3m'`` | ``GenericBrowser('w3m')`` | |
175 +------------------------+-----------------------------------------+-------+
176 | ``'windows-default'`` | ``WindowsDefault`` | \(2) |
177 +------------------------+-----------------------------------------+-------+
178 | ``'macosx'`` | ``MacOSXOSAScript('default')`` | \(3) |
179 +------------------------+-----------------------------------------+-------+
180 | ``'safari'`` | ``MacOSXOSAScript('safari')`` | \(3) |
181 +------------------------+-----------------------------------------+-------+
182 | ``'google-chrome'`` | ``Chrome('google-chrome')`` | |
183 +------------------------+-----------------------------------------+-------+
184 | ``'chrome'`` | ``Chrome('chrome')`` | |
185 +------------------------+-----------------------------------------+-------+
186 | ``'chromium'`` | ``Chromium('chromium')`` | |
187 +------------------------+-----------------------------------------+-------+
188 | ``'chromium-browser'`` | ``Chromium('chromium-browser')`` | |
189 +------------------------+-----------------------------------------+-------+
190 | ``'iosbrowser'`` | ``IOSBrowser`` | \(4) |
191 +------------------------+-----------------------------------------+-------+
192
193 Notes:
194
195 (1)
196 "Konqueror" is the file manager for the KDE desktop environment for Unix, and
197 only makes sense to use if KDE is running. Some way of reliably detecting KDE
198 would be nice; the :envvar:`!KDEDIR` variable is not sufficient. Note also that
199 the name "kfm" is used even when using the :program:`konqueror` command with KDE
200 2 --- the implementation selects the best strategy for running Konqueror.
201
202 (2)
203 Only on Windows platforms.
204
205 (3)
206 Only on macOS.
207
208 (4)
209 Only on iOS.
210
211 .. versionadded:: 3.2
212 A new :class:`!MacOSXOSAScript` class has been added
213 and is used on Mac instead of the previous :class:`!MacOSX` class.
214 This adds support for opening browsers not currently set as the OS default.
215
216 .. versionadded:: 3.3
217 Support for Chrome/Chromium has been added.
218
219 .. versionchanged:: 3.12
220 Support for several obsolete browsers has been removed.
221 Removed browsers include Grail, Mosaic, Netscape, Galeon,
222 Skipstone, Iceape, and Firefox versions 35 and below.
223
224 .. versionchanged:: 3.13
225 Support for iOS has been added.
226
227 Here are some simple examples::
228
229 url = 'https://docs.python.org/'
230
231 # Open URL in a new tab, if a browser window is already open.
232 webbrowser.open_new_tab(url)
233
234 # Open URL in new window, raising the window if possible.
235 webbrowser.open_new(url)
236
237
238 .. _browser-controllers:
239
240 Browser controller objects
241 --------------------------
242
243 Browser controllers provide the :attr:`~controller.name` attribute,
244 and the following three methods which parallel module-level convenience functions:
245
246
247 .. attribute:: controller.name
248
249 System-dependent name for the browser.
250
251
252 .. method:: controller.open(url, new=0, autoraise=True)
253
254 Display *url* using the browser handled by this controller. If *new* is 1, a new
255 browser window is opened if possible. If *new* is 2, a new browser page ("tab")
256 is opened if possible.
257
258
259 .. method:: controller.open_new(url)
260
261 Open *url* in a new window of the browser handled by this controller, if
262 possible, otherwise, open *url* in the only browser window. Alias
263 :func:`open_new`.
264
265
266 .. method:: controller.open_new_tab(url)
267
268 Open *url* in a new page ("tab") of the browser handled by this controller, if
269 possible, otherwise equivalent to :func:`open_new`.
270
271
272 .. rubric:: Footnotes
273
274 .. [1] Executables named here without a full path will be searched in the
275 directories given in the :envvar:`PATH` environment variable.