Lib/webbrowser.py

   1 """Interfaces for launching and remotely controlling Web browsers."""
   2
   3 import os
   4 import sys
   5
   6 __all__ = ["Error", "open", "get", "register"]
   7
   8 class Error(Exception):
   9     pass
  10
  11 _browsers = {}          # Dictionary of available browser controllers
  12 _tryorder = []          # Preference order of available browsers
  13
  14 def register(name, klass, instance=None):
  15     """Register a browser connector and, optionally, connection."""
  16     _browsers[name.lower()] = [klass, instance]
  17
  18 def get(using=None):
  19     """Return a browser launcher instance appropriate for the environment."""
  20     if using:
  21         alternatives = [using]
  22     else:
  23         alternatives = _tryorder
  24     for browser in alternatives:
  25         if browser.find('%s') > -1:
  26             # User gave us a command line, don't mess with it.
  27             return GenericBrowser(browser)
  28         else:
  29             # User gave us a browser name.
  30             try:
  31                 command = _browsers[browser.lower()]
  32             except KeyError:
  33                 command = _synthesize(browser)
  34             if command[1] is None:
  35                 return command[0]()
  36             else:
  37                 return command[1]
  38     raise Error("could not locate runnable browser")
  39
  40 # Please note: the following definition hides a builtin function.
  41
  42 def open(url, new=0, autoraise=1):
  43     get().open(url, new, autoraise)
  44
  45 def open_new(url):      # Marked deprecated.  May be removed in 2.1.
  46     get().open(url, 1)
  47
  48
  49 def _synthesize(browser):
  50     """Attempt to synthesize a controller base on existing controllers.
  51
  52     This is useful to create a controller when a user specifies a path to
  53     an entry in the BROWSER environment variable -- we can copy a general
  54     controller to operate using a specific installation of the desired
  55     browser in this way.
  56
  57     If we can't create a controller in this way, or if there is no
  58     executable for the requested browser, return [None, None].
  59
  60     """
  61     if not os.path.exists(browser):
  62         return [None, None]
  63     name = os.path.basename(browser)
  64     try:
  65         command = _browsers[name.lower()]
  66     except KeyError:
  67         return [None, None]
  68     # now attempt to clone to fit the new name:
  69     controller = command[1]
  70     if controller and name.lower() == controller.basename:
  71         import copy
  72         controller = copy.copy(controller)
  73         controller.name = browser
  74         controller.basename = os.path.basename(browser)
  75         register(browser, None, controller)
  76         return [None, controller]
  77     ret
  78
  79 #
  80 # Everything after this point initializes _browsers and _tryorder,
  81 # then disappears.  Some class definitions and instances remain
  82 # live through these globals, but only the minimum set needed to
  83 # support the user's platform.
  84 #
  85
  86 #
  87 # Platform support for Unix
  88 #
  89
  90 # This is the right test because all these Unix browsers require either
  91 # a console terminal of an X display to run.  Note that we cannot split
  92 # the TERM and DISPLAY cases, because we might be running Python from inside
  93 # an xterm.
  94 if os.environ.get("TERM") or os.environ.get("DISPLAY"):
  95     PROCESS_CREATION_DELAY = 4
  96     _tryorder = ("mozilla","netscape","kfm","grail","links","lynx","w3m")
  97
  98     def _iscommand(cmd):
  99         """Return true if cmd can be found on the executable search path."""
 100         path = os.environ.get("PATH")
 101         if not path:
 102             return 0
 103         for d in path.split(os.pathsep):
 104             exe = os.path.join(d, cmd)
 105             if os.path.isfile(exe):
 106                 return 1
 107         return 0
 108
 109     class GenericBrowser:
 110         def __init__(self, cmd):
 111             self.name, self.args = cmd.split(None, 1)
 112             self.basename = os.path.basename(self.name)
 113
 114         def open(self, url, new=0, autoraise=1):
 115             command = "%s %s" % (self.name, self.args)
 116             os.system(command % url)
 117
 118         def open_new(self, url):        # Deprecated.  May be removed in 2.1.
 119             self.open(url)
 120
 121     # Easy cases first -- register console browsers if we have them.
 122     if os.environ.get("TERM"):
 123         # The Links browser <http://artax.karlin.mff.cuni.cz/~mikulas/links/>
 124         if _iscommand("links"):
 125             register("links", None, GenericBrowser("links %s"))
 126         # The Lynx browser <http://lynx.browser.org/>
 127         if _iscommand("lynx"):
 128             register("lynx", None, GenericBrowser("lynx %s"))
 129         # The w3m browser <http://ei5nazha.yz.yamagata-u.ac.jp/~aito/w3m/eng/>
 130         if _iscommand("w3m"):
 131             register("w3m", None, GenericBrowser("w3m %s"))
 132
 133     # X browsers have more in the way of options
 134     if os.environ.get("DISPLAY"):
 135         # First, the Netscape series
 136         if _iscommand("netscape") or _iscommand("mozilla"):
 137             class Netscape:
 138                 "Launcher class for Netscape browsers."
 139                 def __init__(self, name):
 140                     self.name = name
 141                     self.basename = os.path.basename(name)
 142
 143                 def _remote(self, action, autoraise):
 144                     raise_opt = ("-noraise", "-raise")[autoraise]
 145                     cmd = "%s %s -remote '%s' >/dev/null 2>&1" % (self.name,
 146                                                                   raise_opt,
 147                                                                   action)
 148                     rc = os.system(cmd)
 149                     if rc:
 150                         import time
 151                         os.system("%s &" % self.name)
 152                         time.sleep(PROCESS_CREATION_DELAY)
 153                         rc = os.system(cmd)
 154                     return not rc
 155
 156                 def open(self, url, new=0, autoraise=1):
 157                     if new:
 158                         self._remote("openURL(%s, new-window)"%url, autoraise)
 159                     else:
 160                         self._remote("openURL(%s)" % url, autoraise)
 161
 162                 # Deprecated.  May be removed in 2.1.
 163                 def open_new(self, url):
 164                     self.open(url, 1)
 165
 166             if _iscommand("mozilla"):
 167                 register("mozilla", None, Netscape("mozilla"))
 168             if _iscommand("netscape"):
 169                 register("netscape", None, Netscape("netscape"))
 170
 171         # Next, Mosaic -- old but still in use.
 172         if _iscommand("mosaic"):
 173             register("mosaic", None, GenericBrowser("mosaic %s >/dev/null &"))
 174
 175         # Konqueror/kfm, the KDE browser.
 176         if _iscommand("kfm") or _iscommand("konqueror"):
 177             class Konqueror:
 178                 """Controller for the KDE File Manager (kfm, or Konqueror).
 179
 180                 See http://developer.kde.org/documentation/other/kfmclient.html
 181                 for more information on the Konqueror remote-control interface.
 182
 183                 """
 184                 def __init__(self):
 185                     if _iscommand("konqueror"):
 186                         self.name = self.basename = "konqueror"
 187                     else:
 188                         self.name = self.basename = "kfm"
 189
 190                 def _remote(self, action):
 191                     cmd = "kfmclient %s >/dev/null 2>&1" % action
 192                     rc = os.system(cmd)
 193                     if rc:
 194                         import time
 195                         if self.basename == "konqueror":
 196                             os.system(self.name + " --silent &")
 197                         else:
 198                             os.system(self.name + " -d &")
 199                         time.sleep(PROCESS_CREATION_DELAY)
 200                         rc = os.system(cmd)
 201                     return not rc
 202
 203                 def open(self, url, new=1, autoraise=1):
 204                     # XXX Currently I know no way to prevent KFM from
 205                     # opening a new win.
 206                     self._remote("openURL %s" % url)
 207
 208                 # Deprecated.  May be removed in 2.1.
 209                 open_new = open
 210
 211             register("kfm", Konqueror, Konqueror())
 212
 213         # Grail, the Python browser.
 214         if _iscommand("grail"):
 215             class Grail:
 216                 # There should be a way to maintain a connection to
 217                 # Grail, but the Grail remote control protocol doesn't
 218                 # really allow that at this point.  It probably neverwill!
 219                 def _find_grail_rc(self):
 220                     import glob
 221                     import pwd
 222                     import socket
 223                     import tempfile
 224                     tempdir = os.path.join(tempfile.gettempdir(),
 225                                            ".grail-unix")
 226                     user = pwd.getpwuid(_os.getuid())[0]
 227                     filename = os.path.join(tempdir, user + "-*")
 228                     maybes = glob.glob(filename)
 229                     if not maybes:
 230                         return None
 231                     s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
 232                     for fn in maybes:
 233                         # need to PING each one until we find one that's live
 234                         try:
 235                             s.connect(fn)
 236                         except socket.error:
 237                             # no good; attempt to clean it out, but don't fail:
 238                             try:
 239                                 os.unlink(fn)
 240                             except IOError:
 241                                 pass
 242                         else:
 243                             return s
 244
 245                 def _remote(self, action):
 246                     s = self._find_grail_rc()
 247                     if not s:
 248                         return 0
 249                     s.send(action)
 250                     s.close()
 251                     return 1
 252
 253                 def open(self, url, new=0, autoraise=1):
 254                     if new:
 255                         self._remote("LOADNEW " + url)
 256                     else:
 257                         self._remote("LOAD " + url)
 258
 259                 # Deprecated.  May be removed in 2.1.
 260                 def open_new(self, url):
 261                     self.open(url, 1)
 262
 263             register("grail", Grail, None)
 264
 265 #
 266 # Platform support for Windows
 267 #
 268
 269 if sys.platform[:3] == "win":
 270     _tryorder = ("netscape", "windows-default")
 271
 272     class WindowsDefault:
 273         def open(self, url, new=0, autoraise=1):
 274             os.startfile(url)
 275
 276         def open_new(self, url):        # Deprecated.  May be removed in 2.1.
 277             self.open(url)
 278
 279     register("windows-default", WindowsDefault)
 280
 281 #
 282 # Platform support for MacOS
 283 #
 284
 285 try:
 286     import ic
 287 except ImportError:
 288     pass
 289 else:
 290     class InternetConfig:
 291         def open(self, url, new=0, autoraise=1):
 292             ic.launchurl(url)
 293
 294         def open_new(self, url):        # Deprecated.  May be removed in 2.1.
 295             self.open(url)
 296
 297     # internet-config is the only supported controller on MacOS,
 298     # so don't mess with the default!
 299     _tryorder = ("internet-config")
 300     register("internet-config", InternetConfig)
 301
 302 # OK, now that we know what the default preference orders for each
 303 # platform are, allow user to override them with the BROWSER variable.
 304 #
 305 if os.environ.has_key("BROWSER"):
 306     # It's the user's responsibility to register handlers for any unknown
 307     # browser referenced by this value, before calling open().
 308     _tryorder = os.environ["BROWSER"].split(":")
 309 else:
 310     # Optimization: filter out alternatives that aren't available, so we can
 311     # avoid has_key() tests at runtime.  (This may also allow some unused
 312     # classes and class-instance storage to be garbage-collected.)
 313     _tryorder = filter(lambda x: _browsers.has_key(x.lower())
 314                        or x.find("%s") > -1, _tryorder)
 315
 316 # end