add option to abide by XDG directory specification rather than use ~/.shiv

shiv build option `--xdg` will enable **dynamic** runtime determination of
appropriate XDG-compatible cache directory.

For example, if the archive is globally-installed, and /var/cache/ is
writable – *or* a satisfactory extant cache directory is discovered
there to read – then this will be used.

Alternatively, the directory specified by environment variable
XDG_CACHE_HOME will be used.

Finally, the directory ~/.cache/ will be used.

Author: jesteria

src/shiv/bootstrap/__init__.py

@@ -87,23 +87,106 @@ def import_string(import_name):
         raise ImportError(e)
 
 
-def cache_path(archive, root_dir, build_id):
+def is_dir_writeable(path):
+    """Whether the given Path `path` is writeable or createable.
+
+    Returns whether the *extant portion* of the given path is writeable.
+    If so, the path is either extant and writeable or its nearest extant
+    parent is writeable (and as such the path may be created in a
+    writeable form).
+
+    """
+    while not path.exists():
+        parent = path.parent
+
+        # reliably determine whether this is the root
+        if parent == path:
+            break
+
+        path = parent
+
+    return os.access(path, os.W_OK)
+
+
+#
+# support for py38
+#
+def is_relative_to(path, root):
+    """Return True if the path is relative to another path or False."""
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    else:
+        return True
+
+
+def is_system_path(path):
+    """Whether the given Path `path` appears to be a non-user path.
+
+    Returns bool – or None if called on an unsupported platform
+    (_i.e._ implicitly False).
+
+    """
+    if sys.platform == 'linux':
+        return not is_relative_to(path, '/home') and not is_relative_to(path, '/root')
+
+    if sys.platform == 'darwin':
+        return not is_relative_to(path, '/Users')
+
+
+def xdg_root(archive,
+             build_id,
+             system_base='/var/cache',
+             user_base=os.getenv('XDG_CACHE_HOME', '~/.cache')):
+    """Return an XDG-compatible default extraction path.
+
+    * If the archive is installed to a system path and `system_base` is
+      either already populated or writeable by the current user:
+      `system_base` will be used.
+
+    * Otherwise: `user_base` will be used.
+
+    """
+    archive_path = Path(archive.filename).resolve()
+
+    #
+    # 1) let's see about system_base
+    #
+    if is_system_path(archive_path):
+        root = Path(system_base) / archive_path.name
+
+        cache = cache_path(archive, str(root), False, build_id)
+        site_packages = cache / 'site-packages'
+
+        if site_packages.exists() or is_dir_writeable(cache):
+            return root
+
+    #
+    # 2) at least let's try to respect XDG
+    #
+    return Path(user_base).expanduser() / archive_path.name
+
+
+def cache_path(archive, root_dir, xdg_compat, build_id):
     """Returns a ~/.shiv cache directory for unzipping site-packages during bootstrap.
 
     :param ZipFile archive: The zipfile object we are bootstrapping from.
     :param str root_dir: Optional, either a path or environment variable pointing to a SHIV_ROOT.
     :param str build_id: The build id generated at zip creation.
     """
-
     if root_dir:
-
         if root_dir.startswith("$"):
             root_dir = os.environ.get(root_dir[1:], root_dir[1:])
 
-        root_dir = Path(root_dir).expanduser()
+        root = Path(root_dir).expanduser()
+    elif xdg_compat:
+        root = xdg_root(archive, build_id)
+    else:
+        root = Path("~/.shiv").expanduser()
 
-    root = root_dir or Path("~/.shiv").expanduser()
     name = Path(archive.filename).resolve().name
+
     return root / f"{name}_{build_id}"
 
 
@@ -190,7 +273,7 @@ def bootstrap():  # pragma: no cover
         env = Environment.from_json(archive.read("environment.json").decode())
 
         # get a site-packages directory (from env var or via build id)
-        site_packages = cache_path(archive, env.root, env.build_id) / "site-packages"
+        site_packages = cache_path(archive, env.root, env.xdg, env.build_id) / "site-packages"
 
         # determine if first run or forcing extract
         if not site_packages.exists() or env.force_extract:

src/shiv/bootstrap/environment.py

@@ -38,6 +38,7 @@ def __init__(
         script=None,
         preamble=None,
         root=None,
+        xdg=False,
     ):
         self.always_write_cache = always_write_cache
         self.build_id = build_id
@@ -47,6 +48,7 @@ def __init__(
         self.reproducible = reproducible
         self.shiv_version = shiv_version
         self.preamble = preamble
+        self.xdg = xdg
 
         # properties
         self._entry_point = entry_point

src/shiv/cli.py

@@ -154,7 +154,12 @@ def copytree(src: Path, dst: Path) -> None:
         "but before invoking your entry point."
     ),
 )
-@click.option("--root", type=click.Path(), help="Override the 'root' path (default is ~/.shiv).")
+@click.option("--root", type=click.Path(), help="Override the 'root' path (default is XDG or ~/.shiv).")
+@click.option(
+    "--xdg",
+    is_flag=True,
+    help="If specified, the default 'root' path will conform to the XDG specification (rather than ~/.shiv).",
+)
 @click.argument("pip_args", nargs=-1, type=click.UNPROCESSED)
 def main(
     output_file: str,
@@ -170,6 +175,7 @@ def main(
     no_modify: bool,
     preamble: Optional[str],
     root: Optional[str],
+    xdg: bool,
     pip_args: List[str],
 ) -> None:
     """
@@ -259,6 +265,7 @@ def main(
             reproducible=reproducible,
             preamble=Path(preamble).name if preamble else None,
             root=root,
+            xdg=xdg,
         )
 
         if no_modify:

test/test_bootstrap.py

@@ -65,10 +65,21 @@ def test_cache_path(self, env_var):
         mock_zip.filename = "test"
         uuid = str(uuid4())
 
-        assert cache_path(mock_zip, 'foo', uuid) == Path("foo", f"test_{uuid}")
+        # specified root
+        assert cache_path(mock_zip, 'foo', False, uuid) == Path("foo", f"test_{uuid}")
 
+        # same as envvar
         with env_var("FOO", "foo"):
-            assert cache_path(mock_zip, '$FOO', uuid) == Path("foo", f"test_{uuid}")
+            assert cache_path(mock_zip, '$FOO', False, uuid) == Path("foo", f"test_{uuid}")
+
+        # same with xdg otherwise enabled
+        assert cache_path(mock_zip, 'foo', True, uuid) == Path("foo", f"test_{uuid}")
+
+        # xdg enabled and root unspecified
+        assert cache_path(mock_zip, None, True, uuid) == Path.home() / ".cache" / "test" / f"test_{uuid}"
+
+        # xdg disabled and root unspecified
+        assert cache_path(mock_zip, None, False, uuid) == Path.home() / ".shiv" / f"test_{uuid}"
 
     def test_first_sitedir_index(self):
         with mock.patch.object(sys, "path", ["site-packages", "dir", "dir", "dir"]):