174 lines
7.0 KiB
TeX
174 lines
7.0 KiB
TeX
\section{\module{webbrowser} ---
|
|
Convenient Web-browser controller}
|
|
|
|
\declaremodule{standard}{webbrowser}
|
|
\modulesynopsis{Easy-to-use controller for Web browsers.}
|
|
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
The \module{webbrowser} module provides a high-level interface to
|
|
allow displaying Web-based documents to users. Under most
|
|
circumstances, simply calling the \function{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 \code{\%s}, then it is
|
|
interpreted as a literal browser command line to be used with the argument URL
|
|
substituted for \code{\%s}; if the part does not contain
|
|
\code{\%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: \programopt{-n} opens the URL in a new browser window,
|
|
if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The
|
|
options are, naturally, mutually exclusive.
|
|
|
|
The following exception is defined:
|
|
|
|
\begin{excdesc}{Error}
|
|
Exception raised when a browser control error occurs.
|
|
\end{excdesc}
|
|
|
|
The following functions are defined:
|
|
|
|
\begin{funcdesc}{open}{url\optional{, new=0\optional{, autoraise=1}}}
|
|
Display \var{url} using the default browser. If \var{new} is 0, the
|
|
\var{url} is opened in the same browser window if possible. If \var{new} is 1,
|
|
a new browser window is opened if possible. If \var{new} is 2,
|
|
a new browser page ("tab") is opened if possible. If \var{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[\var{new} can now be 2]{2.5}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{open_new}{url}
|
|
Open \var{url} in a new window of the default browser, if possible,
|
|
otherwise, open \var{url} in the only browser window.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{open_new_tab}{url}
|
|
Open \var{url} in a new page ("tab") of the default browser, if possible,
|
|
otherwise equivalent to \function{open_new}.
|
|
\versionadded{2.5}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get}{\optional{name}}
|
|
Return a controller object for the browser type \var{name}. If
|
|
\var{name} is empty, return a controller for a default browser
|
|
appropriate to the caller's environment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{register}{name, constructor\optional{, instance}}
|
|
Register the browser type \var{name}. Once a browser type is
|
|
registered, the \function{get()} function can return a controller
|
|
for that browser type. If \var{instance} is not provided, or is
|
|
\code{None}, \var{constructor} will be called without parameters to
|
|
create an instance when needed. If \var{instance} is provided,
|
|
\var{constructor} will never be called, and may be \code{None}.
|
|
|
|
This entry point is only useful if you plan to either set the
|
|
\envvar{BROWSER} variable or call \function{get} with a nonempty
|
|
argument matching the name of a handler you declare.
|
|
\end{funcdesc}
|
|
|
|
A number of browser types are predefined. This table gives the type
|
|
names that may be passed to the \function{get()} function and the
|
|
corresponding instantiations for the controller classes, all defined
|
|
in this module.
|
|
|
|
\begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
|
|
\lineiii{'mozilla'}{\class{Mozilla('mozilla')}}{}
|
|
\lineiii{'firefox'}{\class{Mozilla('mozilla')}}{}
|
|
\lineiii{'netscape'}{\class{Mozilla('netscape')}}{}
|
|
\lineiii{'galeon'}{\class{Galeon('galeon')}}{}
|
|
\lineiii{'epiphany'}{\class{Galeon('epiphany')}}{}
|
|
\lineiii{'skipstone'}{\class{BackgroundBrowser('skipstone')}}{}
|
|
\lineiii{'kfmclient'}{\class{Konqueror()}}{(1)}
|
|
\lineiii{'konqueror'}{\class{Konqueror()}}{(1)}
|
|
\lineiii{'kfm'}{\class{Konqueror()}}{(1)}
|
|
\lineiii{'mosaic'}{\class{BackgroundBrowser('mosaic')}}{}
|
|
\lineiii{'opera'}{\class{Opera()}}{}
|
|
\lineiii{'grail'}{\class{Grail()}}{}
|
|
\lineiii{'links'}{\class{GenericBrowser('links')}}{}
|
|
\lineiii{'elinks'}{\class{Elinks('elinks')}}{}
|
|
\lineiii{'lynx'}{\class{GenericBrowser('lynx')}}{}
|
|
\lineiii{'w3m'}{\class{GenericBrowser('w3m')}}{}
|
|
\lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
|
|
\lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
|
|
\lineiii{'macosx'}{\class{MacOSX('default')}}{(4)}
|
|
\end{tableiii}
|
|
|
|
\noindent
|
|
Notes:
|
|
|
|
\begin{description}
|
|
\item[(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.
|
|
|
|
\item[(2)]
|
|
Only on Windows platforms.
|
|
|
|
\item[(3)]
|
|
Only on MacOS platforms; requires the standard MacPython \module{ic}
|
|
module, described in the \citetitle[../mac/module-ic.html]{Macintosh
|
|
Library Modules} manual.
|
|
|
|
\item[(4)]
|
|
Only on MacOS X platform.
|
|
\end{description}
|
|
|
|
Here are some simple examples:
|
|
|
|
\begin{verbatim}
|
|
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)
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Browser Controller Objects \label{browser-controllers}}
|
|
|
|
Browser controllers provide two methods which parallel two of the
|
|
module-level convenience functions:
|
|
|
|
\begin{methoddesc}[controller]{open}{url\optional{, new\optional{, autoraise=1}}}
|
|
Display \var{url} using the browser handled by this controller.
|
|
If \var{new} is 1, a new browser window is opened if possible.
|
|
If \var{new} is 2, a new browser page ("tab") is opened if possible.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[controller]{open_new}{url}
|
|
Open \var{url} in a new window of the browser handled by this
|
|
controller, if possible, otherwise, open \var{url} in the only
|
|
browser window. Alias \function{open_new}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[controller]{open_new_tab}{url}
|
|
Open \var{url} in a new page ("tab") of the browser handled by this
|
|
controller, if possible, otherwise equivalent to \function{open_new}.
|
|
\versionadded{2.5}
|
|
\end{methoddesc}
|