Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`webbrowser` --- Convenient Web-browser controller |
| 2 | ======================================================= |
| 3 | |
| 4 | .. module:: webbrowser |
| 5 | :synopsis: Easy-to-use controller for Web browsers. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| 8 | .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| 9 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 10 | **Source code:** :source:`Lib/webbrowser.py` |
| 11 | |
| 12 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 16 | :func:`.open` function from this module will do the right thing. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Senthil Kumaran | aad7cc9 | 2014-04-16 23:43:34 -0400 | [diff] [blame] | 23 | If the environment variable :envvar:`BROWSER` exists, it is interpreted as the |
Donald Stufft | 8b852f1 | 2014-05-20 12:58:38 -0400 | [diff] [blame] | 24 | :data:`os.pathsep`-separated list of browsers to try ahead of the platform |
Senthil Kumaran | aad7cc9 | 2014-04-16 23:43:34 -0400 | [diff] [blame] | 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]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | The script :program:`webbrowser` can be used as a command-line interface for the |
Martin Panter | 6245cb3 | 2016-04-15 02:14:19 +0000 | [diff] [blame] | 37 | module. It accepts a URL as the argument. It accepts the following optional |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 38 | parameters: ``-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, |
Sandro Tosi | c7b0e21 | 2012-08-12 17:34:00 +0200 | [diff] [blame] | 40 | naturally, mutually exclusive. Usage example:: |
| 41 | |
| 42 | python -m webbrowser -t "http://www.python.org" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
| 44 | The following exception is defined: |
| 45 | |
| 46 | |
| 47 | .. exception:: Error |
| 48 | |
| 49 | Exception raised when a browser control error occurs. |
| 50 | |
| 51 | The following functions are defined: |
| 52 | |
| 53 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 54 | .. function:: open(url, new=0, autoraise=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
Alexandre Vassalotti | 6d3dfc3 | 2009-07-29 19:54:39 +0000 | [diff] [blame] | 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). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 79 | .. function:: get(using=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | |
David Steele | e3ce695 | 2017-02-24 23:47:38 -0500 | [diff] [blame] | 86 | .. function:: register(name, constructor, instance=None, *, preferred=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
David Steele | e3ce695 | 2017-02-24 23:47:38 -0500 | [diff] [blame] | 94 | Setting *preferred* to ``True`` makes this browser a preferred result for |
Berker Peksag | 370f7a9 | 2017-02-27 19:13:41 +0300 | [diff] [blame] | 95 | a :func:`get` call with no argument. Otherwise, this entry point is only |
David Steele | e3ce695 | 2017-02-24 23:47:38 -0500 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
Berker Peksag | 370f7a9 | 2017-02-27 19:13:41 +0300 | [diff] [blame] | 100 | .. versionchanged:: 3.7 |
| 101 | *preferred* keyword-only parameter was added. |
| 102 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | A number of browser types are predefined. This table gives the type names that |
| 104 | may be passed to the :func:`get` function and the corresponding instantiations |
| 105 | for the controller classes, all defined in this module. |
| 106 | |
Senthil Kumaran | c909599 | 2011-12-21 22:31:36 +0800 | [diff] [blame] | 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 | +------------------------+-----------------------------------------+-------+ |
Ned Deily | 05fac02 | 2012-04-18 12:55:57 -0700 | [diff] [blame] | 144 | | ``'macosx'`` | :class:`MacOSX('default')` | \(3) | |
Senthil Kumaran | c909599 | 2011-12-21 22:31:36 +0800 | [diff] [blame] | 145 | +------------------------+-----------------------------------------+-------+ |
Ned Deily | 05fac02 | 2012-04-18 12:55:57 -0700 | [diff] [blame] | 146 | | ``'safari'`` | :class:`MacOSX('safari')` | \(3) | |
Sandro Tosi | dc60f94 | 2012-03-31 17:44:33 +0200 | [diff] [blame] | 147 | +------------------------+-----------------------------------------+-------+ |
Senthil Kumaran | c909599 | 2011-12-21 22:31:36 +0800 | [diff] [blame] | 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 | +------------------------+-----------------------------------------+-------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
| 157 | Notes: |
| 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) |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 170 | Only on Mac OS X platform. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | |
Ezio Melotti | 25d1bdc | 2012-01-18 02:32:07 +0200 | [diff] [blame] | 172 | .. versionadded:: 3.3 |
| 173 | Support for Chrome/Chromium has been added. |
| 174 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | Here are some simple examples:: |
| 176 | |
Ezio Melotti | 25d1bdc | 2012-01-18 02:32:07 +0200 | [diff] [blame] | 177 | url = 'http://docs.python.org/' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 179 | # Open URL in a new tab, if a browser window is already open. |
Ezio Melotti | 25d1bdc | 2012-01-18 02:32:07 +0200 | [diff] [blame] | 180 | webbrowser.open_new_tab(url) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 181 | |
| 182 | # Open URL in new window, raising the window if possible. |
| 183 | webbrowser.open_new(url) |
| 184 | |
| 185 | |
| 186 | .. _browser-controllers: |
| 187 | |
| 188 | Browser Controller Objects |
| 189 | -------------------------- |
| 190 | |
Benjamin Peterson | 5879d41 | 2009-03-30 14:51:56 +0000 | [diff] [blame] | 191 | Browser controllers provide these methods which parallel three of the |
| 192 | module-level convenience functions: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 193 | |
| 194 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 195 | .. method:: controller.open(url, new=0, autoraise=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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`. |
Georg Brandl | 8a1e4c4 | 2009-05-25 21:13:36 +0000 | [diff] [blame] | 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. |