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