| 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. |