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