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.
python · ncoghlan · Feb 25, 2017 · Feb 12, 2017 · Feb 12, 2017 · Feb 24, 2017
commit 30a06fdb13a193b01c8b53353cdd325800ef25af
diff --git a/Doc/library/webbrowser.rst b/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

diff --git a/Lib/webbrowser.py b/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