webbrowser.register: Add 'preferred' argument

Replace the existing undocumented tri-state 'try_order' parameter with
the boolean keyword-only 'preferred' parameter. Setting it to True
places the browser at the front of the list, preferring it as the return
to a subsequent get() call.

'preferred' is added to the documentation.

Author: davesteele

Doc/library/webbrowser.rst

@@ -83,17 +83,19 @@ The following functions are defined:
    caller's environment.
 
 
-.. function:: register(name, constructor, instance=None)
+.. function:: register(name, constructor, instance=None, *, preferred=False)
 
    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.
+   Setting *preferred* to ``True`` makes this browser a preferred result for
+   a :func:`get` call with no argument. Otherwise, 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

Lib/webbrowser.py

@@ -16,13 +16,13 @@ class Error(Exception):
 _browsers = {}          # Dictionary of available browser controllers
 _tryorder = []          # Preference order of available browsers
 
-def register(name, klass, instance=None, update_tryorder=1):
-    """Register a browser connector and, optionally, connection."""
+def register(name, klass, instance=None, *, preferred=False):
+    """Register a browser connector."""
     _browsers[name.lower()] = [klass, instance]
-    if update_tryorder > 0:
-        _tryorder.append(name)
-    elif update_tryorder < 0:
+    if preferred:
         _tryorder.insert(0, name)
+    else:
+        _tryorder.append(name)
 
 def get(using=None):
     """Return a browser launcher instance appropriate for the environment."""
@@ -610,10 +610,10 @@ def open(self, url, new=0, autoraise=True):
 
     # Don't clear _tryorder or _browsers since OS X can use above Unix support
     # (but we prefer using the OS X specific stuff)
-    register("safari", None, MacOSXOSAScript('safari'), -1)
-    register("firefox", None, MacOSXOSAScript('firefox'), -1)
-    register("chrome", None, MacOSXOSAScript('chrome'), -1)
-    register("MacOSX", None, MacOSXOSAScript('default'), -1)
+    register("safari", None, MacOSXOSAScript('safari'), preferred=True)
+    register("firefox", None, MacOSXOSAScript('firefox'), preferred=True)
+    register("chrome", None, MacOSXOSAScript('chrome'), preferred=True)
+    register("MacOSX", None, MacOSXOSAScript('default'), preferred=True)
 
 
 # OK, now that we know what the default preference orders for each
@@ -628,7 +628,7 @@ def open(self, url, new=0, autoraise=True):
         if cmdline != '':
             cmd = _synthesize(cmdline, -1)
             if cmd[1] is None:
-                register(cmdline, None, GenericBrowser(cmdline), -1)
+                register(cmdline, None, GenericBrowser(cmdline), preferred=True)
     cmdline = None # to make del work if _userchoices was empty
     del cmdline
     del _userchoices