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