Make the GTK backend respect XDG app path environment variables.

This commit also updates related documentation.

Author: cyphase

changes/3482.bugfix.rst

@@ -0,0 +1 @@
+The GTK backend now respects XDG app path environment variables.

changes/3482.removal.rst

@@ -0,0 +1 @@
+The GTK backend now respects XDG app path environment variables, which means the places it expects to find app data might change in environments where those variables were previously set and being ignored. You'll have to manage that transition; Toga will not move any data itself.

docs/reference/api/resources/app_paths.rst

@@ -23,7 +23,8 @@ location to which they can be considered relative.
 Complicating matters further, operating systems have conventions (and in some
 cases, hard restrictions) over where certain file types should be stored. For
 example, macOS provides the ``~/Library/Application Support`` folder; Linux
-encourages use of the ``~/.config`` folder (amongst others), and Windows
+encourages use of the ``~/.config`` folder (amongst others),
+while allowing users to override the defaults; and Windows
 provides the ``AppData/Local`` folder in the user's home directory. Application
 sandbox and security policies will sometimes prevent reading or
 writing files in any location other than these pre-approved locations.
@@ -43,6 +44,16 @@ up you to create any desired subdirectory - if you want to create a
 ``apps.path.config`` will exist, but you must take responsibility for
 creating the ``credentials`` subdirectory before saving ``user.toml``.
 
+Notes
+-----
+
+* The GTK backend partially implements the
+  `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/>`__;
+  specifically, it uses the default XDG paths for data, config, state, and cache
+  directories, and respects the environment variables that allow overriding the
+  default paths. Per the specification, the override paths must be absolute; relative
+  paths will be ignored.
+
 Reference
 ---------
 

gtk/src/toga_gtk/paths.py

@@ -1,3 +1,4 @@
+import os
 from pathlib import Path
 
 from toga import App
@@ -7,14 +8,28 @@ class Paths:
     def __init__(self, interface):
         self.interface = interface
 
+    def _get_root(self, envvar, default):
+        custom_root_raw = os.getenv(envvar)
+        custom_root = Path(custom_root_raw) if custom_root_raw else None
+
+        # The XDG Base Directory spec requires paths to be absolute
+        if custom_root and custom_root.is_absolute():
+            return custom_root
+
+        return Path.home() / default
+
     def get_config_path(self):
-        return Path.home() / f".config/{App.app.app_name}"
+        root = self._get_root("XDG_CONFIG_HOME", ".config")
+        return root / App.app.app_name
 
     def get_data_path(self):
-        return Path.home() / f".local/share/{App.app.app_name}"
+        root = self._get_root("XDG_DATA_HOME", ".local/share")
+        return root / App.app.app_name
 
     def get_cache_path(self):
-        return Path.home() / f".cache/{App.app.app_name}"
+        root = self._get_root("XDG_CACHE_HOME", ".cache")
+        return root / App.app.app_name
 
     def get_logs_path(self):
-        return Path.home() / f".local/state/{App.app.app_name}/log"
+        root = self._get_root("XDG_STATE_HOME", ".local/state")
+        return root / App.app.app_name / "log"

gtk/tests_backend/app.py

@@ -1,4 +1,5 @@
 import os
+import tempfile
 from contextlib import contextmanager
 from pathlib import Path
 
@@ -32,16 +33,69 @@ def is_cursor_visible(self):
 
     @contextmanager
     def prepare_paths(self, *, custom):
-        if custom:
-            pytest.xfail("This backend doesn't implement app path customization.")
-
-        yield {
-            "config": Path.home() / ".config/testbed",
-            "data": Path.home() / ".local/share/testbed",
-            "cache": Path.home() / ".cache/testbed",
-            "logs": Path.home() / ".local/state/testbed/log",
+        # Backup environment variables for later restoration
+        backup = {
+            "XDG_CONFIG_HOME": os.getenv("XDG_CONFIG_HOME"),
+            "XDG_DATA_HOME": os.getenv("XDG_DATA_HOME"),
+            "XDG_CACHE_HOME": os.getenv("XDG_CACHE_HOME"),
+            "XDG_STATE_HOME": os.getenv("XDG_STATE_HOME"),
         }
 
+        # Creating this variable here so it can be checked during cleanup
+        temp_custom_dir = None
+
+        try:
+            if custom:
+                # This will be cleaned up later
+                temp_custom_dir = tempfile.TemporaryDirectory()
+
+                custom_root = Path(temp_custom_dir.name)
+                app_paths = {
+                    "config": custom_root / "config",
+                    "data": custom_root / "data",
+                    "cache": custom_root / "cache",
+                    "state": custom_root / "state",
+                }
+
+                # Set the custom paths
+                os.environ["XDG_CONFIG_HOME"] = str(app_paths["config"])
+                os.environ["XDG_DATA_HOME"] = str(app_paths["data"])
+                os.environ["XDG_CACHE_HOME"] = str(app_paths["cache"])
+                os.environ["XDG_STATE_HOME"] = str(app_paths["state"])
+            else:
+                # Delete existing environment variables to replicate the
+                # default state.
+                for envvar in backup:
+                    if envvar in os.environ:
+                        del os.environ[envvar]
+
+                # The default paths
+                app_paths = {
+                    "config": Path.home() / ".config",
+                    "data": Path.home() / ".local/share",
+                    "cache": Path.home() / ".cache",
+                    "state": Path.home() / ".local/state",
+                }
+
+            yield {
+                "config": app_paths["config"] / "testbed",
+                "data": app_paths["data"] / "testbed",
+                "cache": app_paths["cache"] / "testbed",
+                "logs": app_paths["state"] / "testbed" / "log",
+            }
+        finally:
+            # Restore environment variables
+            for envvar, value in backup.items():
+                if value is not None:
+                    os.environ[envvar] = value
+                else:
+                    if envvar in os.environ:
+                        del os.environ[envvar]
+
+            # Clean up temporary custom directory if it was created
+            if temp_custom_dir:
+                temp_custom_dir.cleanup()
+
     def unhide(self):
         pytest.xfail("This platform doesn't have an app level unhide.")