| |
| :mod:`webbrowser` --- Convenient Web-browser controller |
| ======================================================= |
| |
| .. module:: webbrowser |
| :synopsis: Easy-to-use controller for Web browsers. |
| .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| |
| |
| The :mod:`webbrowser` module provides a high-level interface to allow displaying |
| Web-based documents to users. Under most circumstances, simply calling the |
| :func:`open` function from this module will do the right thing. |
| |
| Under Unix, graphical browsers are preferred under X11, but text-mode browsers |
| will be used if graphical browsers are not available or an X11 display isn't |
| available. If text-mode browsers are used, the calling process will block until |
| the user exits the browser. |
| |
| If the environment variable :envvar:`BROWSER` exists, it is interpreted to |
| override the platform default list of browsers, as a os.pathsep-separated list |
| of browsers to try in order. When the value of a list part contains the string |
| ``%s``, then it is interpreted as a literal browser command line to be used |
| with the argument URL substituted for ``%s``; if the part does not contain |
| ``%s``, it is simply interpreted as the name of the browser to launch. |
| |
| For non-Unix platforms, or when a remote browser is available on Unix, the |
| controlling process will not wait for the user to finish with the browser, but |
| allow the remote browser to maintain its own windows on the display. If remote |
| browsers are not available on Unix, the controlling process will launch a new |
| browser and wait. |
| |
| The script :program:`webbrowser` can be used as a command-line interface for the |
| module. It accepts an URL as the argument. It accepts the following optional |
| parameters: :option:`-n` opens the URL in a new browser window, if possible; |
| :option:`-t` opens the URL in a new browser page ("tab"). The options are, |
| naturally, mutually exclusive. |
| |
| The following exception is defined: |
| |
| |
| .. exception:: Error |
| |
| Exception raised when a browser control error occurs. |
| |
| The following functions are defined: |
| |
| |
| .. function:: open(url[, new=0[, autoraise=1]]) |
| |
| Display *url* using the default browser. If *new* is 0, the *url* is opened in |
| the same browser window if possible. If *new* is 1, a new browser window is |
| opened if possible. If *new* is 2, a new browser page ("tab") is opened if |
| possible. If *autoraise* is true, the window is raised if possible (note that |
| under many window managers this will occur regardless of the setting of this |
| variable). |
| |
| .. versionchanged:: 2.5 |
| *new* can now be 2. |
| |
| |
| .. function:: open_new(url) |
| |
| Open *url* in a new window of the default browser, if possible, otherwise, open |
| *url* in the only browser window. |
| |
| |
| .. function:: open_new_tab(url) |
| |
| Open *url* in a new page ("tab") of the default browser, if possible, otherwise |
| equivalent to :func:`open_new`. |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. function:: get([name]) |
| |
| Return a controller object for the browser type *name*. If *name* is empty, |
| return a controller for a default browser appropriate to the caller's |
| environment. |
| |
| |
| .. function:: register(name, constructor[, instance]) |
| |
| Register the browser type *name*. Once a browser type is registered, the |
| :func:`get` function can return a controller for that browser type. If |
| *instance* is not provided, or is ``None``, *constructor* will be called without |
| parameters to create an instance when needed. If *instance* is provided, |
| *constructor* will never be called, and may be ``None``. |
| |
| This entry point is only useful if you plan to either set the :envvar:`BROWSER` |
| variable or call :func:`get` with a nonempty argument matching the name of a |
| handler you declare. |
| |
| A number of browser types are predefined. This table gives the type names that |
| may be passed to the :func:`get` function and the corresponding instantiations |
| for the controller classes, all defined in this module. |
| |
| +-----------------------+-----------------------------------------+-------+ |
| | Type Name | Class Name | Notes | |
| +=======================+=========================================+=======+ |
| | ``'mozilla'`` | :class:`Mozilla('mozilla')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'firefox'`` | :class:`Mozilla('mozilla')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'netscape'`` | :class:`Mozilla('netscape')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'galeon'`` | :class:`Galeon('galeon')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'epiphany'`` | :class:`Galeon('epiphany')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'skipstone'`` | :class:`BackgroundBrowser('skipstone')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'kfmclient'`` | :class:`Konqueror()` | \(1) | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'konqueror'`` | :class:`Konqueror()` | \(1) | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'kfm'`` | :class:`Konqueror()` | \(1) | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'mosaic'`` | :class:`BackgroundBrowser('mosaic')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'opera'`` | :class:`Opera()` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'grail'`` | :class:`Grail()` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'links'`` | :class:`GenericBrowser('links')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'elinks'`` | :class:`Elinks('elinks')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'lynx'`` | :class:`GenericBrowser('lynx')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'w3m'`` | :class:`GenericBrowser('w3m')` | | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'windows-default'`` | :class:`WindowsDefault` | \(2) | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'internet-config'`` | :class:`InternetConfig` | \(3) | |
| +-----------------------+-----------------------------------------+-------+ |
| | ``'macosx'`` | :class:`MacOSX('default')` | \(4) | |
| +-----------------------+-----------------------------------------+-------+ |
| |
| Notes: |
| |
| (1) |
| "Konqueror" is the file manager for the KDE desktop environment for Unix, and |
| only makes sense to use if KDE is running. Some way of reliably detecting KDE |
| would be nice; the :envvar:`KDEDIR` variable is not sufficient. Note also that |
| the name "kfm" is used even when using the :program:`konqueror` command with KDE |
| 2 --- the implementation selects the best strategy for running Konqueror. |
| |
| (2) |
| Only on Windows platforms. |
| |
| (3) |
| Only on Mac OS platforms; requires the standard MacPython :mod:`ic` module. |
| |
| (4) |
| Only on Mac OS X platform. |
| |
| Here are some simple examples:: |
| |
| url = 'http://www.python.org' |
| |
| # Open URL in a new tab, if a browser window is already open. |
| webbrowser.open_new_tab(url + '/doc') |
| |
| # Open URL in new window, raising the window if possible. |
| webbrowser.open_new(url) |
| |
| |
| .. _browser-controllers: |
| |
| Browser Controller Objects |
| -------------------------- |
| |
| Browser controllers provide these methods which parallel two of the module-level |
| convenience functions: |
| |
| |
| .. method:: controller.open(url[, new[, autoraise=1]]) |
| |
| Display *url* using the browser handled by this controller. If *new* is 1, a new |
| browser window is opened if possible. If *new* is 2, a new browser page ("tab") |
| is opened if possible. |
| |
| |
| .. method:: controller.open_new(url) |
| |
| Open *url* in a new window of the browser handled by this controller, if |
| possible, otherwise, open *url* in the only browser window. Alias |
| :func:`open_new`. |
| |
| |
| .. method:: controller.open_new_tab(url) |
| |
| Open *url* in a new page ("tab") of the browser handled by this controller, if |
| possible, otherwise equivalent to :func:`open_new`. |
| |
| .. versionadded:: 2.5 |
| |