bpo-24241: Improve preferred webbrowser handling (#85)

- Add 'preferred' argument to webbrowser.register
- Use xdg-settings to specify preferred X browser

The first change replaces the existing undocumented tri-state
'try_order' parameter with the documented 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.

The second change adds a private `_os_preferred_browser` setting
and then uses that to make the default browser reported by
`xdg-settings` first in the try list when running under X (or
another environment that sets the `DISPLAY` variable).
This avoids the problem where the first entry in the tryorder
queue otherwise defaults to xdg-open, which doesn't support
the "new window" option.

1 files changed, 6 insertions, 4 deletions

diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index 85d3636..ee501e8 100644
--- a/Doc/library/webbrowser.rst
+++ b/Doc/library/webbrowser.rst
@@ -83,7 +83,7 @@ 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
@@ -91,9 +91,11 @@ The following functions are defined:
    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