mirror of https://github.com/python/cpython
224 lines
9.9 KiB
ReStructuredText
224 lines
9.9 KiB
ReStructuredText
: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>
|
|
|
|
**Source code:** :source:`Lib/webbrowser.py`
|
|
|
|
--------------
|
|
|
|
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 as the
|
|
:data:`os.pathsep`-separated list of browsers to try ahead of the platform
|
|
defaults. 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. [1]_
|
|
|
|
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 a URL as the argument. It accepts the following optional
|
|
parameters: ``-n`` opens the URL in a new browser window, if possible;
|
|
``-t`` opens the URL in a new browser page ("tab"). The options are,
|
|
naturally, mutually exclusive. Usage example::
|
|
|
|
python -m webbrowser -t "https://www.python.org"
|
|
|
|
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=True)
|
|
|
|
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).
|
|
|
|
Note that on some platforms, trying to open a filename using this function,
|
|
may work and start the operating system's associated program. However, this
|
|
is neither supported nor portable.
|
|
|
|
.. audit-event:: webbrowser.open url webbrowser.open
|
|
|
|
|
|
.. 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`.
|
|
|
|
|
|
.. function:: get(using=None)
|
|
|
|
Return a controller object for the browser type *using*. If *using* is
|
|
``None``, return a controller for a default browser appropriate to the
|
|
caller's environment.
|
|
|
|
|
|
.. function:: register(name, constructor, instance=None, *, preferred=False)
|
|
|
|
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``.
|
|
|
|
Setting *preferred* to ``True`` makes this browser a preferred result for
|
|
a :func:`get` call with no argument. Otherwise, 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.
|
|
|
|
.. versionchanged:: 3.7
|
|
*preferred* keyword-only parameter was added.
|
|
|
|
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) |
|
|
+------------------------+-----------------------------------------+-------+
|
|
| ``'macosx'`` | :class:`MacOSXOSAScript('default')` | \(3) |
|
|
+------------------------+-----------------------------------------+-------+
|
|
| ``'safari'`` | :class:`MacOSXOSAScript('safari')` | \(3) |
|
|
+------------------------+-----------------------------------------+-------+
|
|
| ``'google-chrome'`` | :class:`Chrome('google-chrome')` | |
|
|
+------------------------+-----------------------------------------+-------+
|
|
| ``'chrome'`` | :class:`Chrome('chrome')` | |
|
|
+------------------------+-----------------------------------------+-------+
|
|
| ``'chromium'`` | :class:`Chromium('chromium')` | |
|
|
+------------------------+-----------------------------------------+-------+
|
|
| ``'chromium-browser'`` | :class:`Chromium('chromium-browser')` | |
|
|
+------------------------+-----------------------------------------+-------+
|
|
|
|
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 macOS platform.
|
|
|
|
.. versionadded:: 3.3
|
|
Support for Chrome/Chromium has been added.
|
|
|
|
.. deprecated-removed:: 3.11 3.13
|
|
:class:`MacOSX` is deprecated, use :class:`MacOSXOSAScript` instead.
|
|
|
|
Here are some simple examples::
|
|
|
|
url = 'https://docs.python.org/'
|
|
|
|
# Open URL in a new tab, if a browser window is already open.
|
|
webbrowser.open_new_tab(url)
|
|
|
|
# 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 three of the
|
|
module-level convenience functions:
|
|
|
|
|
|
.. method:: controller.open(url, new=0, autoraise=True)
|
|
|
|
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`.
|
|
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [1] Executables named here without a full path will be searched in the
|
|
directories given in the :envvar:`PATH` environment variable.
|