core/cachew: rely on ~/.cache for default cache path

- rely on appdirs for default cache path instead of hardcoded /var/tmp/cachew
  technically backwards incompatible, but no action needed
  you might want to clean /var/tmp/cachew after updating

- use default cache path (e.g. ~/.cache) by default
  see https://github.com/ActiveState/appdirs#some-example-output for more info
  *warning*: things will be cached by default now (used to be uncached before)

- treat cache_dir = None in the config
  *warning*: kind of backwards incompatible.. but again nothing disasterous

my/core/cachew.py

@@ -1,8 +1,12 @@
 from contextlib import contextmanager
 from pathlib import Path
+from typing import Optional
 
+# can lead to some unexpected issues if you 'import cachew' which being in my/core directory.. so let's protect against it
+# NOTE: if we use overlay, name can be smth like my.origg.my.core.cachew ...
+assert 'my.core' in __name__, f'Expected module __name__ ({__name__}) to start with my.core'
 
-def disable_cachew():
+def disable_cachew() -> None:
     try:
         import cachew
     except ImportError:
@@ -13,8 +17,9 @@ def disable_cachew():
     settings.ENABLE = False
 
 
+from typing import Iterator
 @contextmanager
-def disabled_cachew():
+def disabled_cachew() -> Iterator[None]:
     try:
         import cachew
     except ImportError:
@@ -26,18 +31,13 @@ def disabled_cachew():
         yield
 
 
-def cache_dir() -> Path:
-    '''
-    Base directory for cachew.
-    To override, add to your config file:
-    class config:
-        cache_dir = '/your/custom/cache/path'
-    '''
-    from .core_config import config
-    cdir = config.cache_dir
-    if cdir is None:
-        # TODO handle this in core_config.py
-        # TODO fallback to default cachew dir instead? or appdirs cache
-        return Path('/var/tmp/cachew')
-    else:
-        return Path(cdir)
+def _appdirs_cache_dir() -> Path:
+    import appdirs # type: ignore
+    cd = Path(appdirs.user_cache_dir('my'))
+    cd.mkdir(exist_ok=True, parents=True)
+    return cd
+
+
+def cache_dir() -> Optional[Path]:
+    from . import core_config as CC
+    return CC.config.get_cache_dir()

my/core/common.py

@@ -214,7 +214,8 @@ if TYPE_CHECKING:
 
     mcachew: McachewType
 
-# TODO set default cache dir here instead?
+
+# TODO I don't really like 'mcachew', just 'cache' would be better... maybe?
 # todo ugh. I think it needs doublewrap, otherwise @mcachew without args doesn't work
 def mcachew(*args, **kwargs): # type: ignore[no-redef]
     """

my/core/core_config.py

@@ -4,8 +4,7 @@ Bindings for the 'core' HPI configuration
 import re
 from typing import Sequence, Optional
 
-from .common import PathIsh
-from . import warnings
+from . import warnings, PathIsh, Path
 
 try:
     from my.config import core as user_config # type: ignore[attr-defined]
@@ -20,22 +19,50 @@ except Exception as e:
         user_config = object # type: ignore[assignment, misc]
 
 
+_HPI_CACHE_DIR_DEFAULT = ''
+
 from dataclasses import dataclass
 @dataclass
 class Config(user_config):
-    # TODO if attr is set _and_ it's none, disable cache?
-    # todo or empty string?
-    # I guess flip the switch at some point when I'm confident in cachew
-    cache_dir: Optional[PathIsh] = None # FIXME use appdirs cache dir or something
+    '''
+    Config for the HPI itself.
+    To override, add to your config file something like
+
+    class config:
+        cache_dir = '/your/custom/cache/path'
+    '''
+
+    cache_dir: Optional[PathIsh] = _HPI_CACHE_DIR_DEFAULT
+    '''
+    Base directory for cachew.
+    - if None             , means cache is disabled
+    - if '' (empty string), use user cache dir (see https://github.com/ActiveState/appdirs for more info). This is the default.
+    - otherwise           , use the specified directory as base cache directory
+
+    NOTE: you shouldn't use this attribute in HPI modules directly, use Config.get_cache_dir()/cachew.cache_dir() instead
+    '''
 
-    # list of regexes/globs
-    # None means 'rely on disabled_modules'
     enabled_modules : Optional[Sequence[str]] = None
+    '''
+    list of regexes/globs
+    - None means 'rely on disabled_modules'
+    '''
 
-    # list of regexes/globs
-    # None means 'rely on enabled_modules'
     disabled_modules: Optional[Sequence[str]] = None
+    '''
+    list of regexes/globs
+    - None means 'rely on enabled_modules'
+    '''
 
+    def get_cache_dir(self) -> Optional[Path]:
+        cdir = self.cache_dir
+        if cdir is None:
+            return None
+        if cdir == _HPI_CACHE_DIR_DEFAULT:
+            from .cachew import _appdirs_cache_dir
+            return _appdirs_cache_dir()
+        else:
+            return Path(cdir)
 
     def _is_module_active(self, module: str) -> Optional[bool]:
         # None means the config doesn't specify anything
@@ -81,6 +108,7 @@ def _reset_config() -> Iterator[Config]:
     with override_config(config) as cc:
         cc.enabled_modules  = None
         cc.disabled_modules = None
+        cc.cache_dir        = None
         yield cc