Fit cache_remedy to the cache location numba picked

docs/numbox.core.configurations.rst

@@ -51,10 +51,21 @@ the check here makes a file named as long as the longest numba writes for the pa
 which a test holds every function of the package under), so that location turns caching off with the
 warning instead.
 
-- For a source file on disk the remedy is ``NUMBA_CACHE_DIR`` pointed at a writable directory; where its
-  location is too long for the file system, a shorter ``NUMBA_CACHE_DIR`` or none, since each location numba
-  picks for a source on disk but the one beside it appends the source's directory path, else the package
-  installed at a shorter path.
+- For a source file on disk the remedy is ``NUMBA_CACHE_DIR`` pointed at a writable directory; where it is
+  set and numba passed it over, the warning names it and asks for a writable directory at a short path, since
+  numba passes over one too deep to make its directory in as it does an unwritable one; and where
+  ``NUMBA_CACHE_LOCATOR_CLASSES``, from numba 0.62, puts another locator first, it is the locations that
+  names made writable. Where the
+  location is too long for the file system, the remedy is for the location the error names: numba takes a
+  directory under ``NUMBA_CACHE_DIR`` where that is set, else the ``__pycache__`` beside the source, else a
+  directory under the user's cache directory, each of the two under a cache directory named for the source's
+  directory, by its name and a hash of its path. So a shorter ``NUMBA_CACHE_DIR`` for the first; the
+  package installed at a shorter path for the second; the user's cache directory at a shorter path, through
+  ``XDG_CACHE_HOME`` or ``HOME``, ``HOME`` alone on macOS and nothing on Windows, where numba asks the system,
+  for the third; and for either of the last two ``NUMBA_CACHE_DIR`` set to a short path, which numba takes
+  first, or, where it is set and numba passed it over, unwritable or too deep, the warning names it and the
+  remedy is a writable directory at a short path. Where ``NUMBA_CACHE_LOCATOR_CLASSES`` puts
+  another locator first, ``NUMBA_CACHE_DIR`` is not offered.
 - For a ``.zip``, or a frozen application, it is the user's cache directory made writable: a ``.zip`` is the
   one archive numba caches, from 0.61 on, and it caches it there, taking the directory without checking that
   it can be written; a frozen application (``sys.frozen``) is cached there too, its sources not being on disk.
@@ -71,6 +82,14 @@ warning instead.
 A function numba cannot cache is compiled in every process that uses it, never wrong; that is the cost the
 warning reports. An error at decoration that is not the cache's is raised as it was.
 
+A package built on numbox can put the same question for its own files: ``check_cache_location`` asks it for
+one file, ``is_a_cache_error`` tells numba's cache errors from the rest, and ``cache_remedy`` words the
+remedy, given the package's name for the two remedies that tell the reader to install it again, at a shorter
+path or with its source files on disk. The bound on file names is the package's own:
+``LONGEST_CACHE_FILE_NAME`` holds numbox's functions only, so a package passes ``check_cache_location`` the
+longest name numba writes for its own, as ``longest_file_name``, or a location that fits numbox's names and not
+the package's passes the check and the first save overflows it.
+
 The code numbox generates at run time, ``make_structref``'s, ``compile_kernel``'s, the work builder's derives
 and the sqlite registrations', is anchored to a file under ``NUMBA_CACHE_DIR`` or the user's cache directory
 so that numba can cache it. That directory can be unwritable where the package's own functions cache, since

docs/numbox.utils.rst

@@ -180,14 +180,15 @@ the directory is the only part that can make it so, ``NUMBA_CACHE_DIR``
 or the user's cache directory, and ``NUMBA_CACHE_DIR`` at a shorter
 path moves the anchor out of either. The anchor's check writes names
 shorter than the longest numba writes for a struct, which carry its name
-and its methods', so a user cache directory within about 230 bytes of
-the path limit, 4096 on Linux, passes it and overflows at numba's first
-save instead, where numba's own error names the length; the remedy is
-the same. A ``NUMBA_CACHE_DIR`` that deep is too deep for the package's
-own files first, whose location under it appends their directory's path
-and whose check reserves the length of numba's files, so the package
-answers, with its remedy, and the generated code compiles under its
-answer.
+and its methods', so a user cache directory or a ``NUMBA_CACHE_DIR``
+within about 230 bytes of the path limit, 4096 on Linux, passes it and
+overflows at numba's first save instead, where numba's own error names
+the length; the remedy is the same. The package's own check answers
+first only nearer the limit, within about 175 bytes of it: the package's
+location under ``NUMBA_CACHE_DIR`` is a directory named for its own, by
+its name and a hash of its path, and its check reserves the length of
+numba's files for the package's functions, so it fails only where those
+no longer fit; the generated code then compiles under its answer.
 
 The anchor's name carries the struct's or the function's, and numba
 names its cache files after the anchor and the qualified name of the

numbox/core/configurations.py

@@ -217,31 +217,107 @@ def _compiled_from(zip_path, directory, stem):
         return None
 
 
-def cache_remedy(py_file, failure, silence):
+def _moved_through():
+    """What moves numba's user cache directory on this platform, as a clause for a remedy; nothing on Windows.
+
+    numba's ``appdirs`` asks the system for it on Windows, which no variable changes, puts it under ``HOME`` on
+    macOS, and takes ``XDG_CACHE_HOME``, else a directory under ``HOME``, elsewhere.
+    """
+    if sys.platform == "win32":
+        return ""
+    if sys.platform == "darwin":
+        return ", through HOME"
+    return ", through XDG_CACHE_HOME or HOME"
+
+
+def cache_remedy(py_file, failure, silence, package="numbox"):
     """The remedy for ``failure``, numba's for a function whose file is ``py_file``, ending in ``silence``.
 
-    ``NUMBA_CACHE_DIR`` for a source file on disk, which is the only kind numba reads the variable for; where its
-    location is too long for the file system, a shorter ``NUMBA_CACHE_DIR`` or none, since each location numba
-    picks for a source on disk but the one beside it appends the source's directory path, else the package at a
-    shorter path. For a ``.zip`` or a frozen application, both cached under the user's cache directory, the
-    location made writable:
+    ``NUMBA_CACHE_DIR`` for a source file on disk, which is the only kind numba reads the variable for; where it is
+    set and numba passed it over, the variable named and a writable directory at a short path asked for, since
+    numba passes over one too deep to make its directory in as it does an unwritable one; and where
+    ``NUMBA_CACHE_LOCATOR_CLASSES``, from numba 0.62, puts another locator first, the locations it names made
+    writable. Where the
+    location is too long for the file system, the error names it, and the remedy is for the one it is: numba takes
+    a directory under ``NUMBA_CACHE_DIR`` where that is set, else the ``__pycache__`` beside the source, else a
+    directory under the user's cache directory, each of the two under a cache directory named for the source's
+    directory, by its name and a hash of its path. So a shorter ``NUMBA_CACHE_DIR`` for the first; the
+    package at a shorter path for the second; the user's cache directory at a shorter path, through
+    ``XDG_CACHE_HOME`` or ``HOME``, ``HOME`` alone on macOS and nothing on Windows, for the third; and for either
+    of the last two ``NUMBA_CACHE_DIR`` set to a short path, which numba takes first, or, where it is set and numba
+    passed it over, named and made a writable directory at a short path. Where ``NUMBA_CACHE_LOCATOR_CLASSES``
+    puts another locator first, ``NUMBA_CACHE_DIR`` is not offered. The error can name the
+    location or a file numba writes in it. For a ``.zip`` or a frozen application, both cached under the user's cache
+    directory, the location made writable:
     the ``.zip``'s error names it, a directory of numba's under the user's cache directory; the frozen
     application's is the no-locator one, numba having passed the location over on its error, so the user's
     cache directory is named. For any other archive, or a module without its source, the source files on disk
     or a ``.zip`` holding them. A ``.zip``'s location too long for the file system is the user's cache
     directory's doing, with the names numba makes bounded, and the remedy is that directory at a shorter
-    path, through ``XDG_CACHE_HOME`` or ``HOME``.
+    path, through what moves it on the platform.
+
+    ``package`` is the one the remedy tells the reader to install again, at a shorter path or with its source
+    files on disk: a package built on numbox that puts the question for its own files with
+    ``check_cache_location`` and ``is_a_cache_error`` passes its own name, as it passes ``check_cache_location`` a
+    ``longest_file_name`` for its own functions, ``LONGEST_CACHE_FILE_NAME`` being numbox's.
     """
     if os.path.exists(py_file):
+        from numba import config
+        # numba takes NUMBA_CACHE_DIR first unless NUMBA_CACHE_LOCATOR_CLASSES,
+        # from numba 0.62, orders its locators otherwise; an entry is a class
+        # of numba's caching module, by its name or its dotted path.
+        locators = getattr(config, "CACHE_LOCATOR_CLASSES", "")
+        first = locators.split(",")[0].strip().rsplit(".", 1)[-1] if locators else "UserProvidedCacheLocator"
+        cache_dir_first = first.lstrip("_") == "UserProvidedCacheLocator"
         if isinstance(failure, OSError) and failure.errno == errno.ENAMETOOLONG:
             # numba's own check passes the location, its temporary file
-            # fitting where its cache files would not; the error names it.
-            return (
-                "the path is too long for the file system: a shorter NUMBA_CACHE_DIR, or none, where it is set, "
-                f"else numbox installed at a shorter path; or {silence}"
-            )
+            # fitting where its cache files would not; the error names it,
+            # and which of numba's three it is decides what shortens it. Each
+            # is a path numba builds from the file, matched whole, since the
+            # three can nest: an install under either cache directory, or
+            # NUMBA_CACHE_DIR above the user's.
+            from numba.core.caching import _CacheLocator
+            # The error names the location, or a file numba writes in it.
+            named = os.path.abspath(failure.filename or "")
+            named = {named, os.path.dirname(named)}
+            subpath = _CacheLocator.get_suitable_cache_subpath(py_file)
+            user_cache_dir = AppDirs(appname="numba", appauthor=False).user_cache_dir
+            if not cache_dir_first:
+                instead = ""
+            elif config.CACHE_DIR:
+                # Taken first and set, so a location elsewhere means numba
+                # passed the variable over: unwritable, or too deep.
+                instead = (
+                    f", or NUMBA_CACHE_DIR, which is set to {config.CACHE_DIR} and numba could not use, made a "
+                    "writable directory at a short path"
+                )
+            else:
+                instead = ", or NUMBA_CACHE_DIR set to a short path"
+            if os.path.abspath(os.path.join(os.path.dirname(py_file), "__pycache__")) in named:
+                cure = f"{package} installed at a shorter path{instead}"
+            elif config.CACHE_DIR and os.path.abspath(os.path.join(config.CACHE_DIR, subpath)) in named:
+                cure = "a shorter NUMBA_CACHE_DIR"
+            elif os.path.abspath(os.path.join(user_cache_dir, subpath)) in named:
+                cure = f"the user's cache directory, {user_cache_dir}, at a shorter path{_moved_through()}{instead}"
+            elif instead:
+                cure = f"{instead[len(', or '):]}, which numba takes first"
+            else:
+                cure = f"that location, {failure.filename}, at a shorter path"
+            return f"the path is too long for the file system: {cure}; or {silence}"
         # numba itself passes a location it cannot make or write over, for a
         # source on disk, so the error here is the no-locator one.
+        if not cache_dir_first:
+            return (
+                f"numba looks only where NUMBA_CACHE_LOCATOR_CLASSES, {locators}, says: make one of those locations "
+                f"writable, or {silence}"
+            )
+        if config.CACHE_DIR:
+            # Set and passed over: unwritable, or too deep for numba to make
+            # its directory there, which a writable one as deep would not cure.
+            return (
+                f"NUMBA_CACHE_DIR is set to {config.CACHE_DIR}, which numba could not use: set it to a writable "
+                f"directory at a short path, or {silence}"
+            )
         return f"Set NUMBA_CACHE_DIR to a writable directory, or {silence}"
     if isinstance(failure, OSError) or getattr(sys, "frozen", False):
         # The .zip's error names the location numba picked, which is under
@@ -261,8 +337,7 @@ def cache_remedy(py_file, failure, silence):
             return (
                 "numba caches a .zip, or a frozen application, in the user's cache directory, and NUMBA_CACHE_DIR "
                 f"has no effect here, because the source is not a file on disk: the path is too long for the file "
-                f"system, so put that directory, {location}, at a shorter path, through XDG_CACHE_HOME or HOME, or "
-                f"{silence}"
+                f"system, so put that directory, {location}, at a shorter path{_moved_through()}, or {silence}"
             )
         return (
             "numba caches a .zip, or a frozen application, in the user's cache directory, and NUMBA_CACHE_DIR "
@@ -271,7 +346,7 @@ def cache_remedy(py_file, failure, silence):
         )
     return (
         "NUMBA_CACHE_DIR has no effect here, because the source is not a file on disk: to cache, "
-        "install numbox with its source files on disk, unpacked from any archive, or import it from a "
+        f"install {package} with its source files on disk, unpacked from any archive, or import it from a "
         f".zip holding its source files, which numba 0.61 and later cache in the user's cache directory; or "
         f"{silence}"
     )
@@ -289,8 +364,9 @@ def uncached_where_no_cache_can_be_written(options):
     Every function numbox caches decorates under the one ``jit_options``, so the question is put here, once, for
     a source file in each directory of the package that holds a module, and answered for the package. Where
     numba can cache no function of one of those files the options come back with ``cache`` off and one warning
-    names the remedy: ``NUMBA_CACHE_DIR`` for a source file on disk, or a shorter one, or none, where the
-    location is too long for the file system; for a ``.zip``, the user's cache directory made writable, since
+    names the remedy: ``NUMBA_CACHE_DIR`` for a source file on disk, and where the location is too long for the
+    file system what shortens the one it is, as ``cache_remedy`` sets out; for a ``.zip``, the user's cache
+    directory made writable, since
     numba reads ``NUMBA_CACHE_DIR`` only for a source file on disk; for any other archive,
     or a ``.pyc``-only install, or a ``.pyc`` in a ``.zip``, the source files on disk or a ``.zip`` holding them,
     which numba 0.61 and later cache in the user's cache directory. ``NUMBOX_JIT_OPTIONS='{"cache": false}'``