cpython/Doc/library/webbrowser.rst

200 lines
8.6 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
: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.
2007-08-15 11:28:01 -03:00
(4)
Only on Mac OS X platform.
2007-08-15 11:28:01 -03:00
Here are some simple examples::
url = 'http://www.python.org'
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68133 | antoine.pitrou | 2009-01-01 16:38:03 +0100 (Thu, 01 Jan 2009) | 1 line fill in actual issue number in tests ........ r68134 | hirokazu.yamamoto | 2009-01-01 16:45:39 +0100 (Thu, 01 Jan 2009) | 2 lines Issue #4797: IOError.filename was not set when _fileio.FileIO failed to open file with `str' filename on Windows. ........ r68141 | benjamin.peterson | 2009-01-01 17:43:12 +0100 (Thu, 01 Jan 2009) | 1 line fix highlighting ........ r68142 | benjamin.peterson | 2009-01-01 18:29:49 +0100 (Thu, 01 Jan 2009) | 2 lines welcome to 2009, Python! ........ r68145 | amaury.forgeotdarc | 2009-01-02 01:03:54 +0100 (Fri, 02 Jan 2009) | 5 lines #4801 _collections module fails to build on cygwin. _PyObject_GC_TRACK is the macro version of PyObject_GC_Track, and according to documentation it should not be used for extension modules. ........ r68146 | ronald.oussoren | 2009-01-02 11:44:46 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue4472: "configure --enable-shared doesn't work on OSX" ........ r68148 | ronald.oussoren | 2009-01-02 11:48:31 +0100 (Fri, 02 Jan 2009) | 2 lines Forgot to add a NEWS item in my previous checkin ........ r68149 | ronald.oussoren | 2009-01-02 11:50:48 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue4780 ........ r68159 | ronald.oussoren | 2009-01-02 15:48:17 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue 1627952 ........ r68160 | ronald.oussoren | 2009-01-02 15:52:09 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue r1737832 ........ r68161 | ronald.oussoren | 2009-01-02 16:00:05 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 1149804 ........ r68162 | ronald.oussoren | 2009-01-02 16:06:00 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 4472 is incompatible with Cygwin, this patch should fix that. ........ r68166 | benjamin.peterson | 2009-01-02 19:26:23 +0100 (Fri, 02 Jan 2009) | 1 line document PyMemberDef ........ r68171 | georg.brandl | 2009-01-02 21:25:14 +0100 (Fri, 02 Jan 2009) | 3 lines #4811: fix markup glitches (mostly remains of the conversion), found by Gabriel Genellina. ........ r68172 | martin.v.loewis | 2009-01-02 21:32:55 +0100 (Fri, 02 Jan 2009) | 2 lines Issue #4075: Use OutputDebugStringW in Py_FatalError. ........ r68173 | martin.v.loewis | 2009-01-02 21:40:14 +0100 (Fri, 02 Jan 2009) | 2 lines Issue #4051: Prevent conflict of UNICODE macros in cPickle. ........ r68174 | benjamin.peterson | 2009-01-02 21:47:27 +0100 (Fri, 02 Jan 2009) | 1 line fix compilation on non-Windows platforms ........ r68179 | raymond.hettinger | 2009-01-02 22:26:45 +0100 (Fri, 02 Jan 2009) | 1 line Issue #4615. Document how to use itertools for de-duping. ........ r68195 | georg.brandl | 2009-01-03 14:45:15 +0100 (Sat, 03 Jan 2009) | 2 lines Remove useless string literal. ........ r68196 | georg.brandl | 2009-01-03 15:29:53 +0100 (Sat, 03 Jan 2009) | 2 lines Fix indentation. ........ r68210 | georg.brandl | 2009-01-03 20:10:12 +0100 (Sat, 03 Jan 2009) | 2 lines Set eol-style correctly for mp_distributing.py. ........ r68214 | georg.brandl | 2009-01-03 20:44:48 +0100 (Sat, 03 Jan 2009) | 2 lines Make indentation consistent. ........ r68215 | georg.brandl | 2009-01-03 21:15:14 +0100 (Sat, 03 Jan 2009) | 2 lines Fix role name. ........ r68217 | georg.brandl | 2009-01-03 21:30:15 +0100 (Sat, 03 Jan 2009) | 2 lines Add rstlint, a little tool to find subtle markup problems and inconsistencies in the Doc sources. ........ r68218 | georg.brandl | 2009-01-03 21:38:59 +0100 (Sat, 03 Jan 2009) | 2 lines Recognize usage of the default role. ........ r68219 | georg.brandl | 2009-01-03 21:47:01 +0100 (Sat, 03 Jan 2009) | 2 lines Fix uses of the default role. ........ r68220 | georg.brandl | 2009-01-03 21:55:06 +0100 (Sat, 03 Jan 2009) | 2 lines Remove trailing whitespace. ........ r68221 | georg.brandl | 2009-01-03 22:04:55 +0100 (Sat, 03 Jan 2009) | 2 lines Remove tabs from the documentation. ........ r68222 | georg.brandl | 2009-01-03 22:11:58 +0100 (Sat, 03 Jan 2009) | 2 lines Disable the line length checker by default. ........
2009-01-03 17:55:17 -04:00
# Open URL in a new tab, if a browser window is already open.
2007-08-15 11:28:01 -03:00
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
--------------------------
Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67952 | georg.brandl | 2008-12-27 18:42:40 +0100 (Sat, 27 Dec 2008) | 2 lines #4752: actually use custom handler in example. ........ r67953 | georg.brandl | 2008-12-27 19:20:04 +0100 (Sat, 27 Dec 2008) | 3 lines Patch #4739 by David Laban: add symbols to pydoc help topics, so that ``help('@')`` works as expected. ........ r67955 | georg.brandl | 2008-12-27 19:27:53 +0100 (Sat, 27 Dec 2008) | 3 lines Follow-up to r67746 in order to restore backwards-compatibility for those who (monkey-)patch TextWrapper.wordsep_re with a custom RE. ........ r67957 | georg.brandl | 2008-12-27 19:49:19 +0100 (Sat, 27 Dec 2008) | 2 lines #4754: improve winsound documentation. ........ r67958 | georg.brandl | 2008-12-27 20:02:59 +0100 (Sat, 27 Dec 2008) | 2 lines #4682: 'b' is actually unsigned char. ........ r67960 | georg.brandl | 2008-12-27 20:04:44 +0100 (Sat, 27 Dec 2008) | 2 lines #4695: fix backslashery. ........ r67961 | georg.brandl | 2008-12-27 20:06:04 +0100 (Sat, 27 Dec 2008) | 2 lines Use :samp: role. ........ r67963 | georg.brandl | 2008-12-27 20:11:15 +0100 (Sat, 27 Dec 2008) | 2 lines #4671: document that pydoc imports modules. ........ r67965 | antoine.pitrou | 2008-12-27 21:34:52 +0100 (Sat, 27 Dec 2008) | 3 lines Issue #4677: add two list comprehension tests to pybench. ........ r67967 | benjamin.peterson | 2008-12-27 23:18:58 +0100 (Sat, 27 Dec 2008) | 1 line fix markup ........ r67970 | alexandre.vassalotti | 2008-12-28 02:52:58 +0100 (Sun, 28 Dec 2008) | 2 lines Fix name mangling of PyUnicode_ClearFreeList. ........ r67971 | alexandre.vassalotti | 2008-12-28 03:10:35 +0100 (Sun, 28 Dec 2008) | 2 lines Sort UCS-2/UCS-4 name mangling list. ........ r67973 | alexandre.vassalotti | 2008-12-28 03:58:22 +0100 (Sun, 28 Dec 2008) | 2 lines Document Py_VaBuildValue. ........ r67982 | benjamin.peterson | 2008-12-28 16:37:31 +0100 (Sun, 28 Dec 2008) | 1 line fix WORD_BIGEDIAN declaration in Universal builds; fixes #4060 and #4728 ........ r67988 | ronald.oussoren | 2008-12-28 20:40:56 +0100 (Sun, 28 Dec 2008) | 1 line Issue4064: architecture string for universal builds on OSX ........ r67990 | ronald.oussoren | 2008-12-28 20:50:40 +0100 (Sun, 28 Dec 2008) | 3 lines Update the fix for issue4064 to deal correctly with all three variants of universal builds that are presented by the configure script. ........ r67995 | benjamin.peterson | 2008-12-28 22:16:07 +0100 (Sun, 28 Dec 2008) | 1 line #4763 PyErr_ExceptionMatches won't blow up with NULL arguments ........ r68014 | benjamin.peterson | 2008-12-29 18:47:42 +0100 (Mon, 29 Dec 2008) | 1 line #4764 set IOError.filename when trying to open a directory on POSIX platforms ........ r68016 | benjamin.peterson | 2008-12-29 18:56:58 +0100 (Mon, 29 Dec 2008) | 1 line #4764 in io.open, set IOError.filename when trying to open a directory on POSIX platforms ........ r68030 | benjamin.peterson | 2008-12-29 22:38:14 +0100 (Mon, 29 Dec 2008) | 1 line fix French ........ r68057 | vinay.sajip | 2008-12-30 08:01:25 +0100 (Tue, 30 Dec 2008) | 1 line Minor documentation change relating to NullHandler. ........ r68061 | georg.brandl | 2008-12-30 11:15:49 +0100 (Tue, 30 Dec 2008) | 2 lines #4778: attributes can't be called. ........ r68112 | benjamin.peterson | 2009-01-01 00:48:39 +0100 (Thu, 01 Jan 2009) | 1 line #4795 inspect.isgeneratorfunction() should return False instead of None ........ r68115 | benjamin.peterson | 2009-01-01 05:04:41 +0100 (Thu, 01 Jan 2009) | 1 line simplfy code ........ r68116 | georg.brandl | 2009-01-01 12:46:51 +0100 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 12:53:55 +0100 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 13:00:19 +0100 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68120 | georg.brandl | 2009-01-01 13:15:31 +0100 (Thu, 01 Jan 2009) | 4 lines #4228: Pack negative values the same way as 2.4 in struct's L format. ........ r68121 | georg.brandl | 2009-01-01 13:43:33 +0100 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 13:52:29 +0100 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 13:53:19 +0100 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 14:02:09 +0100 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 14:05:13 +0100 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 14:14:49 +0100 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........ r68128 | antoine.pitrou | 2009-01-01 15:11:22 +0100 (Thu, 01 Jan 2009) | 3 lines Issue #3680: Reference cycles created through a dict, set or deque iterator did not get collected. ........
2009-01-01 11:46:10 -04:00
Browser controllers provide these methods which parallel two of the module-level
2007-08-15 11:28:01 -03:00
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