Doc/library/webbrowser.rst

   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
  58    .. versionchanged:: 2.5
  59       *new* can now be 2.
  60
  61
  62 .. function:: open_new(url)
  63
  64    Open *url* in a new window of the default browser, if possible, otherwise, open
  65    *url* in the only browser window.
  66
  67
  68 .. function:: open_new_tab(url)
  69
  70    Open *url* in a new page ("tab") of the default browser, if possible, otherwise
  71    equivalent to :func:`open_new`.
  72
  73    .. versionadded:: 2.5
  74
  75
  76 .. function:: get([name])
  77
  78    Return a controller object for the browser type *name*.  If *name* is empty,
  79    return a controller for a default browser appropriate to the caller's
  80    environment.
  81
  82
  83 .. function:: register(name, constructor[, instance])
  84
  85    Register the browser type *name*.  Once a browser type is registered, the
  86    :func:`get` function can return a controller for that browser type.  If
  87    *instance* is not provided, or is ``None``, *constructor* will be called without
  88    parameters to create an instance when needed.  If *instance* is provided,
  89    *constructor* will never be called, and may be ``None``.
  90
  91    This entry point is only useful if you plan to either set the :envvar:`BROWSER`
  92    variable or call :func:`get` with a nonempty argument matching the name of a
  93    handler you declare.
  94
  95 A number of browser types are predefined.  This table gives the type names that
  96 may be passed to the :func:`get` function and the corresponding instantiations
  97 for the controller classes, all defined in this module.
  98
  99 +-----------------------+-----------------------------------------+-------+
 100 | Type Name             | Class Name                              | Notes |
 101 +=======================+=========================================+=======+
 102 | ``'mozilla'``         | :class:`Mozilla('mozilla')`             |       |
 103 +-----------------------+-----------------------------------------+-------+
 104 | ``'firefox'``         | :class:`Mozilla('mozilla')`             |       |
 105 +-----------------------+-----------------------------------------+-------+
 106 | ``'netscape'``        | :class:`Mozilla('netscape')`            |       |
 107 +-----------------------+-----------------------------------------+-------+
 108 | ``'galeon'``          | :class:`Galeon('galeon')`               |       |
 109 +-----------------------+-----------------------------------------+-------+
 110 | ``'epiphany'``        | :class:`Galeon('epiphany')`             |       |
 111 +-----------------------+-----------------------------------------+-------+
 112 | ``'skipstone'``       | :class:`BackgroundBrowser('skipstone')` |       |
 113 +-----------------------+-----------------------------------------+-------+
 114 | ``'kfmclient'``       | :class:`Konqueror()`                    | \(1)  |
 115 +-----------------------+-----------------------------------------+-------+
 116 | ``'konqueror'``       | :class:`Konqueror()`                    | \(1)  |
 117 +-----------------------+-----------------------------------------+-------+
 118 | ``'kfm'``             | :class:`Konqueror()`                    | \(1)  |
 119 +-----------------------+-----------------------------------------+-------+
 120 | ``'mosaic'``          | :class:`BackgroundBrowser('mosaic')`    |       |
 121 +-----------------------+-----------------------------------------+-------+
 122 | ``'opera'``           | :class:`Opera()`                        |       |
 123 +-----------------------+-----------------------------------------+-------+
 124 | ``'grail'``           | :class:`Grail()`                        |       |
 125 +-----------------------+-----------------------------------------+-------+
 126 | ``'links'``           | :class:`GenericBrowser('links')`        |       |
 127 +-----------------------+-----------------------------------------+-------+
 128 | ``'elinks'``          | :class:`Elinks('elinks')`               |       |
 129 +-----------------------+-----------------------------------------+-------+
 130 | ``'lynx'``            | :class:`GenericBrowser('lynx')`         |       |
 131 +-----------------------+-----------------------------------------+-------+
 132 | ``'w3m'``             | :class:`GenericBrowser('w3m')`          |       |
 133 +-----------------------+-----------------------------------------+-------+
 134 | ``'windows-default'`` | :class:`WindowsDefault`                 | \(2)  |
 135 +-----------------------+-----------------------------------------+-------+
 136 | ``'internet-config'`` | :class:`InternetConfig`                 | \(3)  |
 137 +-----------------------+-----------------------------------------+-------+
 138 | ``'macosx'``          | :class:`MacOSX('default')`              | \(4)  |
 139 +-----------------------+-----------------------------------------+-------+
 140
 141 Notes:
 142
 143 (1)
 144    "Konqueror" is the file manager for the KDE desktop environment for Unix, and
 145    only makes sense to use if KDE is running.  Some way of reliably detecting KDE
 146    would be nice; the :envvar:`KDEDIR` variable is not sufficient.  Note also that
 147    the name "kfm" is used even when using the :program:`konqueror` command with KDE
 148    2 --- the implementation selects the best strategy for running Konqueror.
 149
 150 (2)
 151    Only on Windows platforms.
 152
 153 (3)
 154    Only on MacOS platforms; requires the standard MacPython :mod:`ic` module.
 155
 156 (4)
 157    Only on MacOS X platform.
 158
 159 Here are some simple examples::
 160
 161    url = 'http://www.python.org'
 162
 163    # Open URL in a new tab, if a browser window is already open.
 164    webbrowser.open_new_tab(url + '/doc')
 165
 166    # Open URL in new window, raising the window if possible.
 167    webbrowser.open_new(url)
 168
 169
 170 .. _browser-controllers:
 171
 172 Browser Controller Objects
 173 --------------------------
 174
 175 Browser controllers provide two methods which parallel two of the module-level
 176 convenience functions:
 177
 178
 179 .. method:: controller.open(url[, new[, autoraise=1]])
 180
 181    Display *url* using the browser handled by this controller. If *new* is 1, a new
 182    browser window is opened if possible. If *new* is 2, a new browser page ("tab")
 183    is opened if possible.
 184
 185
 186 .. method:: controller.open_new(url)
 187
 188    Open *url* in a new window of the browser handled by this controller, if
 189    possible, otherwise, open *url* in the only browser window.  Alias
 190    :func:`open_new`.
 191
 192
 193 .. method:: controller.open_new_tab(url)
 194
 195    Open *url* in a new page ("tab") of the browser handled by this controller, if
 196    possible, otherwise equivalent to :func:`open_new`.
 197
 198    .. versionadded:: 2.5
 199