<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-cgi.html" />
<link rel=
"prev" href=
"internet.html" />
<link rel=
"parent" href=
"internet.html" />
<link rel=
"next" href=
"browser-controllers.html" />
<meta name='aesop' content='information'
/>
<title>11.1 webbrowser -- Convenient Web-browser controller
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"11. Internet Protocols and"
href=
"internet.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"11. Internet Protocols and"
href=
"internet.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"11.1.1 Browser Controller Objects"
href=
"browser-controllers.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"internet.html">11. Internet Protocols and
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"internet.html">11. Internet Protocols and
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"browser-controllers.html">11.1.1 Browser Controller Objects
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION0013100000000000000000">
11.1 <tt class=
"module">webbrowser
</tt> --
Convenient Web-browser controller
</A>
<A NAME=
"module-webbrowser"></A>
The
<tt class=
"module">webbrowser
</tt> module provides a very high-level interface to
allow displaying Web-based documents to users. The controller objects
are easy to use and are platform-independent. Under most
circumstances, simply calling the
<tt class=
"function">open()
</tt> function from this
module will do the right thing.
Under
<span class=
"Unix">Unix
</span>, 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.
Under
<span class=
"Unix">Unix
</span>, if the environment variable
<a class=
"envvar" id='l2h-
3147' xml:id='l2h-
3147'
>BROWSER
</a> exists, it
is interpreted to override the platform default list of browsers, as a
colon-separated list of browsers to try in order. When the value of
a list part contains the string
<code>%s
</code>, then it is interpreted as
a literal browser command line to be used with the argument URL
substituted for the
<code>%s
</code>; if the part does not contain
<code>%s
</code>, it is simply interpreted as the name of the browser to
For non-
<span class=
"Unix">Unix
</span> platforms, or when X11 browsers are available on
<span class=
"Unix">Unix
</span>, the controlling process will not wait for the user to finish
with the browser, but allow the browser to maintain its own window on
The following exception is defined:
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
3142' xml:id='l2h-
3142'
class=
"exception">Error
</tt></b></dt>
Exception raised when a browser control error occurs.
The following functions are defined:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3143' xml:id='l2h-
3143'
class=
"function">open
</tt></b>(
</nobr></td>
<td><var>url
</var><big>[
</big><var>, new=
0</var><big>]
</big><var></var><big>[
</big><var>, autoraise=
1</var><big>]
</big><var></var>)
</td></tr></table></dt>
Display
<var>url
</var> using the default browser. If
<var>new
</var> is true,
a new browser window is opened if possible. If
<var>autoraise
</var> is
true, the window is raised if possible (note that under many window
managers this will occur regardless of the setting of this variable).
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3144' xml:id='l2h-
3144'
class=
"function">open_new
</tt></b>(
</nobr></td>
<td><var>url
</var>)
</td></tr></table></dt>
Open
<var>url
</var> in a new window of the default browser, if possible,
otherwise, open
<var>url
</var> in the only browser window.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3145' xml:id='l2h-
3145'
class=
"function">get
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>name
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Return a controller object for the browser type
<var>name
</var>. If
<var>name
</var> is empty, return a controller for a default browser
appropriate to the caller's environment.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3146' xml:id='l2h-
3146'
class=
"function">register
</tt></b>(
</nobr></td>
<td><var>name, constructor
</var><big>[
</big><var>, instance
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Register the browser type
<var>name
</var>. Once a browser type is
registered, the
<tt class=
"function">get()
</tt> function can return a controller
for that browser type. If
<var>instance
</var> is not provided, or is
<code>None
</code>,
<var>constructor
</var> will be called without parameters to
create an instance when needed. If
<var>instance
</var> is provided,
<var>constructor
</var> will never be called, and may be
<code>None
</code>.
This entry point is only useful if you plan to either set the
<a class=
"envvar" id='l2h-
3148' xml:id='l2h-
3148'
>BROWSER
</a> variable or call
<tt class=
"function">get
</tt> 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
<tt class=
"function">get()
</tt> function and the
corresponding instantiations for the controller classes, all defined
<div class=
"center"><table class=
"realtable">
<th class=
"left" >Type Name
</th>
<th class=
"left" >Class Name
</th>
<th class=
"center">Notes
</th>
<tr><td class=
"left" valign=
"baseline"><code>'mozilla'
</code></td>
<td class=
"left" ><tt class=
"class">Netscape('mozilla')
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'netscape'
</code></td>
<td class=
"left" ><tt class=
"class">Netscape('netscape')
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'mosaic'
</code></td>
<td class=
"left" ><tt class=
"class">GenericBrowser('mosaic %s
&')
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'kfm'
</code></td>
<td class=
"left" ><tt class=
"class">Konqueror()
</tt></td>
<td class=
"center">(
1)
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'grail'
</code></td>
<td class=
"left" ><tt class=
"class">Grail()
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'links'
</code></td>
<td class=
"left" ><tt class=
"class">GenericBrowser('links %s')
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'lynx'
</code></td>
<td class=
"left" ><tt class=
"class">GenericBrowser('lynx %s')
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'w3m'
</code></td>
<td class=
"left" ><tt class=
"class">GenericBrowser('w3m %s')
</tt></td>
<td class=
"center"></td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'windows-default'
</code></td>
<td class=
"left" ><tt class=
"class">WindowsDefault
</tt></td>
<td class=
"center">(
2)
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'internet-config'
</code></td>
<td class=
"left" ><tt class=
"class">InternetConfig
</tt></td>
<td class=
"center">(
3)
</td></tr></tbody>
<DT><STRONG>(
1)
</STRONG></DT>
<DD>``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
<a class=
"envvar" id='l2h-
3149' xml:id='l2h-
3149'
>KDEDIR
</a> variable is
not sufficient. Note also that the name ``kfm'' is used even when
using the
<b class=
"program">konqueror
</b> command with KDE
2 -- the
implementation selects the best strategy for running Konqueror.
<DT><STRONG>(
2)
</STRONG></DT>
<DD>Only on Windows platforms; requires the common
extension modules
<tt class=
"module">win32api
</tt> and
<tt class=
"module">win32con
</tt>.
<DT><STRONG>(
3)
</STRONG></DT>
<DD>Only on MacOS platforms; requires the standard MacPython
<tt class=
"module">ic
</tt>
module, described in the
<em class=
"citetitle"><a
href=
"../mac/module-ic.html"
Library Modules
</a></em> manual.
<p><br /></p><hr class='online-navigation'
/>
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<LI><A href=
"browser-controllers.html">11.1.1 Browser Controller Objects
</a>
<!--End of Table of Child-Links-->
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"11. Internet Protocols and"
href=
"internet.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"11. Internet Protocols and"
href=
"internet.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"11.1.1 Browser Controller Objects"
href=
"browser-controllers.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"internet.html">11. Internet Protocols and
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"internet.html">11. Internet Protocols and
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"browser-controllers.html">11.1.1 Browser Controller Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.