1 :mod:`webbrowser` --- Convenient Web-browser controller 2 ======================================================= 3 4 .. module:: webbrowser 5 :synopsis: Easy-to-use controller for Web browsers. 6 .. moduleauthor:: Fred L. Drake, Jr. <fdrake (a] acm.org> 7 .. sectionauthor:: Fred L. Drake, Jr. <fdrake (a] acm.org> 8 9 **Source code:** :source:`Lib/webbrowser.py` 10 11 -------------- 12 13 The :mod:`webbrowser` module provides a high-level interface to allow displaying 14 Web-based documents to users. Under most circumstances, simply calling the 15 :func:`.open` function from this module will do the right thing. 16 17 Under Unix, graphical browsers are preferred under X11, but text-mode browsers 18 will be used if graphical browsers are not available or an X11 display isn't 19 available. If text-mode browsers are used, the calling process will block until 20 the user exits the browser. 21 22 If the environment variable :envvar:`BROWSER` exists, it is interpreted to 23 override the platform default list of browsers, as an :data:`os.pathsep`-separated 24 list of browsers to try in order. When the value of a list part contains the 25 string ``%s``, then it is interpreted as a literal browser command line to be 26 used with the argument URL substituted for ``%s``; if the part does not contain 27 ``%s``, it is simply interpreted as the name of the browser to launch. [1]_ 28 29 For non-Unix platforms, or when a remote browser is available on Unix, the 30 controlling process will not wait for the user to finish with the browser, but 31 allow the remote browser to maintain its own windows on the display. If remote 32 browsers are not available on Unix, the controlling process will launch a new 33 browser and wait. 34 35 The script :program:`webbrowser` can be used as a command-line interface for the 36 module. It accepts a URL as the argument. It accepts the following optional 37 parameters: ``-n`` opens the URL in a new browser window, if possible; 38 ``-t`` opens the URL in a new browser page ("tab"). The options are, 39 naturally, mutually exclusive. Usage example:: 40 41 python -m webbrowser -t "http://www.python.org" 42 43 The following exception is defined: 44 45 46 .. exception:: Error 47 48 Exception raised when a browser control error occurs. 49 50 The following functions are defined: 51 52 53 .. function:: open(url, new=0, autoraise=True) 54 55 Display *url* using the default browser. If *new* is 0, the *url* is opened 56 in the same browser window if possible. If *new* is 1, a new browser window 57 is opened if possible. If *new* is 2, a new browser page ("tab") is opened 58 if possible. If *autoraise* is ``True``, the window is raised if possible 59 (note that under many window managers this will occur regardless of the 60 setting of this variable). 61 62 Note that on some platforms, trying to open a filename using this function, 63 may work and start the operating system's associated program. However, this 64 is neither supported nor portable. 65 66 .. versionchanged:: 2.5 67 *new* can now be 2. 68 69 70 .. function:: open_new(url) 71 72 Open *url* in a new window of the default browser, if possible, otherwise, open 73 *url* in the only browser window. 74 75 .. function:: open_new_tab(url) 76 77 Open *url* in a new page ("tab") of the default browser, if possible, otherwise 78 equivalent to :func:`open_new`. 79 80 .. versionadded:: 2.5 81 82 83 .. function:: get([name]) 84 85 Return a controller object for the browser type *name*. If *name* is empty, 86 return a controller for a default browser appropriate to the caller's 87 environment. 88 89 90 .. function:: register(name, constructor[, instance]) 91 92 Register the browser type *name*. Once a browser type is registered, the 93 :func:`get` function can return a controller for that browser type. If 94 *instance* is not provided, or is ``None``, *constructor* will be called without 95 parameters to create an instance when needed. If *instance* is provided, 96 *constructor* will never be called, and may be ``None``. 97 98 This entry point is only useful if you plan to either set the :envvar:`BROWSER` 99 variable or call :func:`get` with a nonempty argument matching the name of a 100 handler you declare. 101 102 A number of browser types are predefined. This table gives the type names that 103 may be passed to the :func:`get` function and the corresponding instantiations 104 for the controller classes, all defined in this module. 105 106 +-----------------------+-----------------------------------------+-------+ 107 | Type Name | Class Name | Notes | 108 +=======================+=========================================+=======+ 109 | ``'mozilla'`` | :class:`Mozilla('mozilla')` | | 110 +-----------------------+-----------------------------------------+-------+ 111 | ``'firefox'`` | :class:`Mozilla('mozilla')` | | 112 +-----------------------+-----------------------------------------+-------+ 113 | ``'netscape'`` | :class:`Mozilla('netscape')` | | 114 +-----------------------+-----------------------------------------+-------+ 115 | ``'galeon'`` | :class:`Galeon('galeon')` | | 116 +-----------------------+-----------------------------------------+-------+ 117 | ``'epiphany'`` | :class:`Galeon('epiphany')` | | 118 +-----------------------+-----------------------------------------+-------+ 119 | ``'skipstone'`` | :class:`BackgroundBrowser('skipstone')` | | 120 +-----------------------+-----------------------------------------+-------+ 121 | ``'kfmclient'`` | :class:`Konqueror()` | \(1) | 122 +-----------------------+-----------------------------------------+-------+ 123 | ``'konqueror'`` | :class:`Konqueror()` | \(1) | 124 +-----------------------+-----------------------------------------+-------+ 125 | ``'kfm'`` | :class:`Konqueror()` | \(1) | 126 +-----------------------+-----------------------------------------+-------+ 127 | ``'mosaic'`` | :class:`BackgroundBrowser('mosaic')` | | 128 +-----------------------+-----------------------------------------+-------+ 129 | ``'opera'`` | :class:`Opera()` | | 130 +-----------------------+-----------------------------------------+-------+ 131 | ``'grail'`` | :class:`Grail()` | | 132 +-----------------------+-----------------------------------------+-------+ 133 | ``'links'`` | :class:`GenericBrowser('links')` | | 134 +-----------------------+-----------------------------------------+-------+ 135 | ``'elinks'`` | :class:`Elinks('elinks')` | | 136 +-----------------------+-----------------------------------------+-------+ 137 | ``'lynx'`` | :class:`GenericBrowser('lynx')` | | 138 +-----------------------+-----------------------------------------+-------+ 139 | ``'w3m'`` | :class:`GenericBrowser('w3m')` | | 140 +-----------------------+-----------------------------------------+-------+ 141 | ``'windows-default'`` | :class:`WindowsDefault` | \(2) | 142 +-----------------------+-----------------------------------------+-------+ 143 | ``'macosx'`` | :class:`MacOSX('default')` | \(3) | 144 +-----------------------+-----------------------------------------+-------+ 145 | ``'safari'`` | :class:`MacOSX('safari')` | \(3) | 146 +-----------------------+-----------------------------------------+-------+ 147 | ``'google-chrome'`` | :class:`Chrome('google-chrome')` | \(4) | 148 +-----------------------+-----------------------------------------+-------+ 149 | ``'chrome'`` | :class:`Chrome('chrome')` | \(4) | 150 +-----------------------+-----------------------------------------+-------+ 151 | ``'chromium'`` | :class:`Chromium('chromium')` | \(4) | 152 +-----------------------+-----------------------------------------+-------+ 153 | ``'chromium-browser'``| :class:`Chromium('chromium-browser')` | \(4) | 154 +-----------------------+-----------------------------------------+-------+ 155 156 Notes: 157 158 (1) 159 "Konqueror" is the file manager for the KDE desktop environment for Unix, and 160 only makes sense to use if KDE is running. Some way of reliably detecting KDE 161 would be nice; the :envvar:`KDEDIR` variable is not sufficient. Note also that 162 the name "kfm" is used even when using the :program:`konqueror` command with KDE 163 2 --- the implementation selects the best strategy for running Konqueror. 164 165 (2) 166 Only on Windows platforms. 167 168 (3) 169 Only on Mac OS X platform. 170 171 (4) 172 Support for Chrome/Chromium has been added in version 2.7.5. 173 174 Here are some simple examples:: 175 176 url = 'http://www.python.org/' 177 178 # Open URL in a new tab, if a browser window is already open. 179 webbrowser.open_new_tab(url + 'doc/') 180 181 # Open URL in new window, raising the window if possible. 182 webbrowser.open_new(url) 183 184 185 .. _browser-controllers: 186 187 Browser Controller Objects 188 -------------------------- 189 190 Browser controllers provide these methods which parallel three of the 191 module-level convenience functions: 192 193 194 .. method:: controller.open(url, new=0, autoraise=True) 195 196 Display *url* using the browser handled by this controller. If *new* is 1, a new 197 browser window is opened if possible. If *new* is 2, a new browser page ("tab") 198 is opened if possible. 199 200 201 .. method:: controller.open_new(url) 202 203 Open *url* in a new window of the browser handled by this controller, if 204 possible, otherwise, open *url* in the only browser window. Alias 205 :func:`open_new`. 206 207 208 .. method:: controller.open_new_tab(url) 209 210 Open *url* in a new page ("tab") of the browser handled by this controller, if 211 possible, otherwise equivalent to :func:`open_new`. 212 213 .. versionadded:: 2.5 214 215 216 .. rubric:: Footnotes 217 218 .. [1] Executables named here without a full path will be searched in the 219 directories given in the :envvar:`PATH` environment variable. 220
