webbrowser: launch default browser more often on linux

especially for file:// URLs

- add support for `gtk-launch` and `gio launch` if default browser is found via `xdg-settings`
- add support for `exo-open --target WebBrowser`
- explicitly prevent xdg-open and other non-browser-specific openers from launching `file://` URLs

Author: minrk

Doc/library/webbrowser.rst

@@ -74,9 +74,11 @@ The following functions are defined:
 
    Returns ``True`` if a browser was successfully launched, ``False`` otherwise.
 
-   Note that on some platforms, trying to open a filename using this function,
+   Note that on some platforms, trying to open a filename (``'./path.html'``) using this function,
    may work and start the operating system's associated program.  However, this
    is neither supported nor portable.
+   ``'file://...'`` URLs, on the other hand, should work and consistently
+   launch a browser.
 
    .. audit-event:: webbrowser.open url webbrowser.open
 
@@ -201,6 +203,14 @@ Notes:
 .. versionchanged:: 3.13
    Support for iOS has been added.
 
+.. versionadded:: next
+   Support for launching the XDG default browser via ``gtk-launch`` or ``gio launch`` on POSIX systems,
+   and ``exo-open`` in XFCE environments.
+
+.. versionchanged:: next
+   ``file://`` URLs should now open more reliably in browsers on all platforms,
+   instead of opening the default application associated with the file type.
+
 Here are some simple examples::
 
    url = 'https://docs.python.org/'

Lib/test/test_webbrowser.py

@@ -65,6 +65,25 @@ def test_open(self):
                    options=[],
                    arguments=[URL])
 
+    def test_supports_file(self):
+        self._test('open',
+                   args=["file:///tmp/file"],
+                   options=[],
+                   arguments=["file:///tmp/file"])
+
+    def test_not_supports_file(self):
+        popen = PopenMock()
+        support.patch(self, subprocess, 'Popen', popen)
+        browser = self.browser_class("open")
+        browser._supports_file = False
+        assert not browser.open("file:///some/file")
+        assert subprocess.Popen.call_count == 0
+        url = "https://some-url"
+        browser.open(url)
+        assert subprocess.Popen.call_count == 1
+        popen_args = subprocess.Popen.call_args[0][0]
+        self.assertEqual(popen_args, ["open", url])
+
 
 class BackgroundBrowserCommandTest(CommandTestMixin, unittest.TestCase):
 
@@ -75,6 +94,25 @@ def test_open(self):
                    options=[],
                    arguments=[URL])
 
+    def test_supports_file(self):
+        self._test('open',
+                   args=["file:///tmp/file"],
+                   options=[],
+                   arguments=["file:///tmp/file"])
+
+    def test_not_supports_file(self):
+        popen = PopenMock()
+        support.patch(self, subprocess, 'Popen', popen)
+        browser = self.browser_class("open")
+        browser._supports_file = False
+        assert not browser.open("file:///some/file")
+        assert subprocess.Popen.call_count == 0
+        url = "https://some-url"
+        browser.open(url)
+        assert subprocess.Popen.call_count == 1
+        popen_args = subprocess.Popen.call_args[0][0]
+        self.assertEqual(popen_args, ["open", url])
+
 
 class ChromeCommandTest(CommandTestMixin, unittest.TestCase):
 

Lib/webbrowser.py

@@ -168,7 +168,7 @@ class GenericBrowser(BaseBrowser):
     """Class for all browsers started with a command
        and without remote functionality."""
 
-    def __init__(self, name):
+    def __init__(self, name, /, _supports_file=True):
         if isinstance(name, str):
             self.name = name
             self.args = ["%s"]
@@ -177,9 +177,20 @@ def __init__(self, name):
             self.name = name[0]
             self.args = name[1:]
         self.basename = os.path.basename(self.name)
+        # whether it supports file:// URLs
+        # set to False for generic openers like xdg-open,
+        # which do not launch webbrowsers reliably
+        self._supports_file = _supports_file
 
     def open(self, url, new=0, autoraise=True):
         sys.audit("webbrowser.open", url)
+
+        if not self._supports_file:
+            # skip me for `file://` URLs for generic openers (e.g. xdg-open)
+            proto, _sep, _rest = url.partition(":")
+            if _sep and proto.lower() == "file":
+                return False
+
         cmdline = [self.name] + [arg.replace("%s", url)
                                  for arg in self.args]
         try:
@@ -197,6 +208,12 @@ class BackgroundBrowser(GenericBrowser):
        background."""
 
     def open(self, url, new=0, autoraise=True):
+        if not self._supports_file:
+            # skip me for `file://` URLs for generic openers (e.g. xdg-open)
+            proto, _sep, _rest = url.partition(":")
+            if _sep and proto.lower() == "file":
+                return False
+
         cmdline = [self.name] + [arg.replace("%s", url)
                                  for arg in self.args]
         sys.audit("webbrowser.open", url)
@@ -415,34 +432,87 @@ class Edge(UnixBrowser):
 # Platform support for Unix
 #
 
+
+def _locate_xdg_desktop(name: str) -> str | None:
+    """Locate .desktop file by name
+
+    Returns absolute path to .desktop file found on $XDG_DATA search path
+    or None if no matching .desktop file is found.
+
+    Needed for `gio launch` support.
+    """
+    if not name.endswith(".desktop"):
+        # ensure it ends in .desktop
+        name += ".desktop"
+    xdg_data_home = os.environ.get("XDG_DATA_HOME") or os.path.expanduser(
+        "~/.local/share"
+    )
+    xdg_data_dirs = os.environ.get("XDG_DATA_DIRS") or "/usr/local/share/:/usr/share/"
+    all_data_dirs = [xdg_data_home]
+    all_data_dirs.extend(xdg_data_dirs.split(os.pathsep))
+    for data_dir in all_data_dirs:
+        desktop_path = os.path.join(data_dir, "applications", name)
+        if os.path.exists(desktop_path):
+            return desktop_path
+    return None
+
 # These are the right tests because all these Unix browsers require either
 # a console terminal or an X display to run.
 
 def register_X_browsers():
 
+    # use gtk-launch to launch preferred browser by name, if found
+    # this should be _before_ xdg-open, which doesn't necessarily launch a browser
+    if _os_preferred_browser and shutil.which("gtk-launch"):
+        register(
+            "gtk-launch",
+            None,
+            BackgroundBrowser(["gtk-launch", _os_preferred_browser, "%s"]),
+        )
+
     # use xdg-open if around
     if shutil.which("xdg-open"):
-        register("xdg-open", None, BackgroundBrowser("xdg-open"))
+        # `xdg-open` does NOT guarantee a browser is launched,
+        # so skip it for `file://`
+        register("xdg-open", None, BackgroundBrowser("xdg-open", _supports_file=False))
+
 
-    # Opens an appropriate browser for the URL scheme according to
+    # Opens the default application for the URL scheme according to
     # freedesktop.org settings (GNOME, KDE, XFCE, etc.)
     if shutil.which("gio"):
-        register("gio", None, BackgroundBrowser(["gio", "open", "--", "%s"]))
+        if _os_preferred_browser:
+            absolute_browser = _locate_xdg_desktop(_os_preferred_browser)
+            if absolute_browser:
+                register(
+                    "gio-launch",
+                    None,
+                    BackgroundBrowser(["gio", "launch", absolute_browser, "%s"]),
+                )
+        # `gio open` does NOT guarantee a browser is launched
+        register("gio", None, BackgroundBrowser(["gio", "open", "--", "%s"], _supports_file=False))
 
     xdg_desktop = os.getenv("XDG_CURRENT_DESKTOP", "").split(":")
 
     # The default GNOME3 browser
     if (("GNOME" in xdg_desktop or
          "GNOME_DESKTOP_SESSION_ID" in os.environ) and
             shutil.which("gvfs-open")):
-        register("gvfs-open", None, BackgroundBrowser("gvfs-open"))
+        register("gvfs-open", None, BackgroundBrowser("gvfs-open", _supports_file=False))
 
     # The default KDE browser
     if (("KDE" in xdg_desktop or
          "KDE_FULL_SESSION" in os.environ) and
             shutil.which("kfmclient")):
         register("kfmclient", Konqueror, Konqueror("kfmclient"))
 
+    # The default XFCE browser
+    if "XFCE" in xdg_desktop and shutil.which("exo-open"):
+        register(
+            "exo-open",
+            None,
+            BackgroundBrowser(["exo-open", "--launch", "WebBrowser", "%s"]),
+        )
+
     # Common symbolic link for the default X11 browser
     if shutil.which("x-www-browser"):
         register("x-www-browser", None, BackgroundBrowser("x-www-browser"))

Misc/NEWS.d/next/Library/2025-02-24-13-55-54.gh-issue-128540.Pc4Pa4.rst

@@ -0,0 +1,6 @@
+:func:`webbrowser.open` should launch default webbrowsers for URLs that are
+not ``http[s]://`` more often (especially ``file://``,
+where the default application by file type was often launched, instead of a browser).
+This works by adding support for ``gtk-launch`` and ``gio
+launch``,
+and making sure generic application launchers like ``xdg-open`` are not used for ``file://`` URLs.