mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 00:48:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Patch #754022: Greatly enhanced webbrowser.py.

Browse source
This commit is contained in:
Georg Brandl 2005-10-03 14:16:44 +00:00
parent 76390de83c
commit e8f244305e
3 changed files with 383 additions and 187 deletions
Download patch file Download diff file Expand all files Collapse all files

75
Doc/lib/libwebbrowser.tex
View file

@ -6,9 +6,8 @@
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
The \module{webbrowser} 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
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.
@ -17,19 +16,26 @@ 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 \UNIX, if the environment variable \envvar{BROWSER} exists, it
If the environment variable \envvar{BROWSER} 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
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 the \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 X11 browsers are available on
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 browser to maintain its own window on
the display.
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:
@ -40,15 +46,24 @@ The following exception is defined:
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 true,
a new browser window is opened if possible. If \var{autoraise} is
Display \var{url} using the default browser. If \var{new} is 0, the
\var{url} is opened in the same browser window. 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).
\end{funcdesc}
\begin{funcdesc}{open_new}{url}
\begin{funcdesc}{open_new_win}{url}
Open \var{url} in a new window of the default browser, if possible,
otherwise, open \var{url} in the only browser window.
otherwise, open \var{url} in the only browser window. Alias
\function{open_new}.
\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_win}.
\end{funcdesc}
\begin{funcdesc}{get}{\optional{name}}
@ -67,7 +82,7 @@ The following functions are defined:
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.
argument matching the name of a handler you declare.
\end{funcdesc}
A number of browser types are predefined. This table gives the type
@ -76,16 +91,24 @@ 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{Netscape('mozilla')}}{}
\lineiii{'netscape'}{\class{Netscape('netscape')}}{}
\lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{}
\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{GenericBrowser('skipstone \%s \&')}}{}
\lineiii{'konqueror'}{\class{Konqueror()}}{(1)}
\lineiii{'kfm'}{\class{Konqueror()}}{(1)}
\lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{}
\lineiii{'opera'}{\class{Opera()}}{}
\lineiii{'grail'}{\class{Grail()}}{}
\lineiii{'links'}{\class{GenericBrowser('links \%s')}}{}
\lineiii{'elinks'}{\class{Elinks('elinks')}}{}
\lineiii{'lynx'}{\class{GenericBrowser('lynx \%s')}}{}
\lineiii{'w3m'}{\class{GenericBrowser('w3m \%s')}}{}
\lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
\lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
\lineiii{'macosx'}{\class{MacOSX('default')}}{(4)}
\end{tableiii}
\noindent
@ -101,13 +124,15 @@ using the \program{konqueror} command with KDE 2 --- the
implementation selects the best strategy for running Konqueror.
\item[(2)]
Only on Windows platforms; requires the common
extension modules \module{win32api} and \module{win32con}.
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}
@ -117,12 +142,18 @@ Browser controllers provide two methods which parallel two of the
module-level convenience functions:
\begin{funcdesc}{open}{url\optional{, new}}
Display \var{url} using the browser handled by this controller. If
\var{new} is true, a new browser window is opened if possible.
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{funcdesc}
\begin{funcdesc}{open_new}{url}
\begin{funcdesc}{open_new_win}{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.
browser window. Alias \function{open_new}.
\end{funcdesc}
\begin{funcdesc}{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_win}.
\end{funcdesc}