general: set min version to 3.12; update ci to run 3.14

It's a bit of a toll to support so many versions, especially with new 3.12 type syntax and other goodies.

With pyenv/uv these days using custom python version is far easier than before and even preferred.

Author: karlicoss

.github/workflows/main.yml

@@ -30,7 +30,7 @@ jobs:
       fail-fast: false
       matrix:
         platform: [ubuntu-latest, macos-latest]  # windows-latest
-        python-version: ['3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.12', '3.13', '3.14']
         # vvv just an example of excluding stuff from matrix
         # exclude: [{platform: macos-latest, python-version: '3.6'}]
 
@@ -43,16 +43,16 @@ jobs:
     # ugh https://github.com/actions/toolkit/blob/main/docs/commands.md#path-manipulation
     - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
         submodules: recursive
         fetch-depth: 0  # nicer to have all git history when debugging/for tests
 
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 
-    - uses: astral-sh/setup-uv@v5
+    - uses: astral-sh/setup-uv@v7
       with:
         enable-cache: false  # we don't have lock files, so can't use them as cache key
 
@@ -93,16 +93,16 @@ jobs:
     # ugh https://github.com/actions/toolkit/blob/main/docs/commands.md#path-manipulation
     - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
         submodules: recursive
         fetch-depth: 0  # pull all commits to correctly infer vcs version
 
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
-    - uses: astral-sh/setup-uv@v5
+    - uses: astral-sh/setup-uv@v7
       with:
         enable-cache: false  # we don't have lock files, so can't use them as cache key
 

README.ipynb

@@ -17,7 +17,7 @@
     "\n",
     "    path_s = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], text=True).strip()\n",
     "    path = Path(path_s)\n",
-    "    assert path.is_absolute(), path   # just in case\n",
+    "    assert path.is_absolute(), path  # just in case\n",
     "    return path\n",
     "\n",
     "\n",
@@ -49,6 +49,7 @@
     "        rpath = Path(c.module_path).relative_to(src_dir)\n",
     "        return f'src/{rpath}#L{c.line}'\n",
     "\n",
+    "\n",
     "# TODO ugh.. annoying, seems like Jedi can't get the functions source?\n",
     "# maybe because it's doing partial parsing or something?\n",
     "# there is c._get_module_context().code_lines, but it returns all lines in a source file??\n",
@@ -67,7 +68,7 @@
     "        raise RuntimeError(f'Function not found: {symbol}')\n",
     "\n",
     "    # ugh lineno is 1-indexed, and seems like a closed interval?\n",
-    "    return ''.join(src_lines[x.lineno - 1: x.end_lineno])\n",
+    "    return ''.join(src_lines[x.lineno - 1 : x.end_lineno])\n",
     "\n",
     "\n",
     "def getdoc(symbol: str) -> str:\n",
@@ -100,7 +101,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "\n",
     "from IPython.display import Markdown as md  # ty: ignore[unresolved-import]\n",
     "\n",
     "dmd = lambda x: display(md(x.strip()))  # ty: ignore[unresolved-reference]"

pyproject.toml

@@ -8,7 +8,7 @@ dependencies = [
     "orjson",           # fast json serialization
     "typing-extensions",# for depreceated decorator
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 
 ## these need to be set if you're planning to upload to pypi
 # description = "TODO"
@@ -39,23 +39,27 @@ optional = [
 # On the other hand, it's a bit annoying that it's always included by default? 
 # To make sure it's not included, need to use `uv run --exact --no-default-groups ...`
 testing = [
-    "pytz", "types-pytz",  # optional runtime only dependency
-
     "pytest",
+    "ruff",
+
+    "pytz",
+
     "more-itertools",
     "patchy",  # for injecting sleeps and testing concurrent behaviour
     "enlighten",  # used in logging helper, but not really required
     "cattrs",  # benchmarking alternative marshalling implementation
     "pyinstrument",  # for profiling from within tests
     "codetiming", # Timer context manager
-
-    "ruff",
-    "mypy",
-    "lxml", # for mypy html coverage
-    "ty>=0.0.1a19",
 ]
 typecheck = [
     { include-group = "testing" },
+
+    "mypy",
+    "lxml",  # for mypy coverage
+    "ty>=0.0.1a22",
+
+    "types-pytz",  # optional runtime only dependency
+
     "cachew[optional]",
 ]
 

ruff.toml

@@ -1,4 +1,4 @@
-line-length = 140  # impacts import sorting
+line-length = 120  # impacts import sorting
 
 lint.extend-select = [
     "ALL",
@@ -72,6 +72,7 @@ lint.ignore = [
 
     "TRY003",  # suggests defining exception messages in exception class -- kinda annoying
     "TRY201",  # raise without specifying exception name -- sometimes hurts readability
+    "TRY400",  # a bit dumb, and results in false positives (see https://github.com/astral-sh/ruff/issues/18070)
     "TRY401",  # redundant exception in logging.exception call? TODO double check, might result in excessive logging
 
     "TID252",  # Prefer absolute imports over relative imports from parent modules

src/cachew/__init__.py

@@ -13,10 +13,7 @@
 from typing import (
     TYPE_CHECKING,
     Any,
-    Generic,
     Literal,
-    ParamSpec,
-    TypeVar,
     cast,
     get_args,
     get_origin,
@@ -88,13 +85,8 @@ def get_logger() -> logging.Logger:
 }
 
 
-R = TypeVar('R')
-P = ParamSpec('P')
-CC = Callable[P, R]  # need to give it a name, if inlined into bound=, mypy runs in a bug
-PathProvider = PathIsh | Callable[P, PathIsh]
-HashFunction = Callable[P, SourceHash]
-
-F = TypeVar('F', bound=CC)
+type PathProvider[**P] = PathIsh | Callable[P, PathIsh]
+type HashFunction[**P] = Callable[P, SourceHash]
 
 
 def default_hash(*args, **kwargs) -> SourceHash:
@@ -109,9 +101,9 @@ def mtime_hash(path: Path, *args, **kwargs) -> SourceHash:
     return default_hash(f'{path}.{mt}', *args, **kwargs)
 
 
-Failure = str
-Kind = Literal['single', 'multiple']
-Inferred = tuple[Kind, type[Any]]
+Failure = str  # deliberately not a type =, used in type checks
+type Kind = Literal['single', 'multiple']
+type Inferred = tuple[Kind, type[Any]]
 
 
 def infer_return_type(func) -> Failure | Inferred:
@@ -161,12 +153,12 @@ def infer_return_type(func) -> Failure | Inferred:
     >>> infer_return_type(int_provider)
     ('multiple', <class 'int'>)
 
-    >>> from typing import Iterator, Union
-    >>> def union_provider() -> Iterator[Union[str, int]]:
+    >>> from typing import Iterator
+    >>> def union_provider() -> Iterator[str | int]:
     ...     yield 1
     ...     yield 'aaa'
     >>> infer_return_type(union_provider)
-    ('multiple', typing.Union[str, int])
+    ('multiple', str | int)
 
     # a bit of an edge case
     >>> from typing import Tuple
@@ -275,13 +267,13 @@ def cachew_error(e: Exception, *, logger: logging.Logger) -> None:
 
 # using cachew_impl here just to use different signatures during type checking (see below)
 @doublewrap
-def cachew_impl(
+def cachew_impl[**P](
     func=None,  # TODO should probably type it after switch to python 3.10/proper paramspec
-    cache_path: PathProvider[P] | None = use_default_path,
+    cache_path: PathProvider[P] | None = use_default_path,  # ty: ignore[too-many-positional-arguments]  # see https://github.com/astral-sh/ty/issues/157
     *,
     force_file: bool = False,
     cls: type | tuple[Kind, type] | None = None,
-    depends_on: HashFunction[P] = default_hash,
+    depends_on: HashFunction[P] = default_hash,  # ty: ignore[too-many-positional-arguments]
     logger: logging.Logger | None = None,
     chunk_by: int = 100,
     # NOTE: allowed values for chunk_by depend on the system.
@@ -402,7 +394,9 @@ def process(self, msg, kwargs):
         else:
             assert use_kind is not None
             if (use_kind, use_cls) != inference_res:
-                logger.warning(f"inferred type {inference_res} mismatches explicitly specified type {(use_kind, use_cls)}")
+                logger.warning(
+                    f"inferred type {inference_res} mismatches explicitly specified type {(use_kind, use_cls)}"
+                )
                 # TODO not sure if should be more serious error...
 
     if use_kind == 'single':
@@ -447,18 +441,18 @@ def binder(*args, **kwargs):
     # we need two versions due to @doublewrap
     # this is when we just annotate as @cachew without any args
     @overload
-    def cachew(fun: F) -> F: ...
+    def cachew[F: Callable](fun: F) -> F: ...
 
     # NOTE: we won't really be able to make sure the args of cache_path are the same as args of the wrapped function
     # because when cachew() is called, we don't know anything about the wrapped function yet
     # but at least it works for checking that cachew_path and depdns_on have the same args :shrug:
     @overload
-    def cachew(
-        cache_path: PathProvider[P] | None = ...,
+    def cachew[F, **P](
+        cache_path: PathProvider[P] | None = ...,  # ty: ignore[too-many-positional-arguments]
         *,
         force_file: bool = ...,
         cls: type | tuple[Kind, type] | None = ...,
-        depends_on: HashFunction[P] = ...,
+        depends_on: HashFunction[P] = ...,  # ty: ignore[too-many-positional-arguments]
         logger: logging.Logger | None = ...,
         chunk_by: int = ...,
         synthetic_key: str | None = ...,
@@ -546,7 +540,9 @@ def _module_is_disabled(module_name: str, logger: logging.Logger) -> bool:
     disabled_modules = _parse_disabled_modules(logger)
     for pat in disabled_modules:
         if _matches_disabled_module(module_name, pat):
-            logger.debug(f"caching disabled for {module_name} (matched '{pat}' from 'CACHEW_DISABLE={os.environ['CACHEW_DISABLE']})'")
+            logger.debug(
+                f"caching disabled for {module_name} (matched '{pat}' from 'CACHEW_DISABLE={os.environ['CACHEW_DISABLE']})'"
+            )
             return True
     return False
 
@@ -560,13 +556,13 @@ def _module_is_disabled(module_name: str, logger: logging.Logger) -> bool:
 
 
 @dataclass
-class Context(Generic[P]):
+class Context[**P]:
     # fmt: off
     func         : Callable
-    cache_path   : PathProvider[P]
+    cache_path   : PathProvider[P]   # ty: ignore[too-many-positional-arguments]
     force_file   : bool
     cls_         : type
-    depends_on   : HashFunction[P]
+    depends_on   : HashFunction[P]   # ty: ignore[too-many-positional-arguments]
     logger       : logging.Logger
     chunk_by     : int
     synthetic_key: str | None
@@ -605,9 +601,9 @@ def composite_hash(self, *args, **kwargs) -> dict[str, Any]:
     # fmt: on
 
 
-def cachew_wrapper(
+def cachew_wrapper[**P](
     *args,
-    _cachew_context: Context[P],
+    _cachew_context: Context[P],  # ty: ignore[too-many-positional-arguments]
     **kwargs,
 ):
     C = _cachew_context

src/cachew/backend/sqlite.py

@@ -120,7 +120,8 @@ def cached_blobs(self) -> Iterator[bytes]:
         raw_row_iterator = getattr(rows, '_raw_row_iterator', None)
         if raw_row_iterator is None:
             warnings.warn(
-                "CursorResult._raw_row_iterator method isn't found. This could lead to degraded cache reading performance.", stacklevel=2
+                "CursorResult._raw_row_iterator method isn't found. This could lead to degraded cache reading performance.",
+                stacklevel=2,
             )
             row_iterator = rows
         else:
@@ -168,7 +169,9 @@ def flush_blobs(self, chunk: Sequence[bytes]) -> None:
         # uhh. this gives a huge speedup for inserting
         # since we don't have to create intermediate dictionaries
         # TODO move this to __init__?
-        insert_into_table_cache_tmp_raw = str(self.table_cache_tmp.insert().compile(dialect=sqlite.dialect(paramstyle='qmark')))
+        insert_into_table_cache_tmp_raw = str(
+            self.table_cache_tmp.insert().compile(dialect=sqlite.dialect(paramstyle='qmark'))
+        )
         # I also tried setting paramstyle='qmark' in create_engine, but it seems to be ignored :(
         # idk what benefit sqlalchemy gives at this point, seems to just complicate things
         self.connection.exec_driver_sql(insert_into_table_cache_tmp_raw, [(c,) for c in chunk])

src/cachew/logging_helper.py

@@ -21,16 +21,24 @@ def test() -> None:
 
     M("   Logging module's defaults are not great:")
     l = logging.getLogger('default_logger')
-    l.error("For example, this should be logged as error. But it's not even formatted properly, doesn't have logger name or level")
+    l.error(
+        "For example, this should be logged as error. But it's not even formatted properly, doesn't have logger name or level"
+    )
 
     M("\n   The reason is that you need to remember to call basicConfig() first. Let's do it now:")
     logging.basicConfig()
-    l.error("OK, this is better. But the default format kinda sucks, I prefer having timestamps and the file/line number")
+    l.error(
+        "OK, this is better. But the default format kinda sucks, I prefer having timestamps and the file/line number"
+    )
 
-    M("\n   Also exception logging is kinda lame, doesn't print traceback by default unless you remember to pass exc_info:")
+    M(
+        "\n   Also exception logging is kinda lame, doesn't print traceback by default unless you remember to pass exc_info:"
+    )
     l.exception(ex)  # type: ignore[possibly-undefined]  # pylint: disable=used-before-assignment
 
-    M("\n\n    With make_logger you get a reasonable logging format, colours (via colorlog library) and other neat things:")
+    M(
+        "\n\n    With make_logger you get a reasonable logging format, colours (via colorlog library) and other neat things:"
+    )
 
     ll = make_logger('test')  # No need for basicConfig!
     ll.info("default level is INFO")
@@ -40,7 +48,9 @@ def test() -> None:
     M("\n    Exceptions print traceback by default now:")
     ll.exception(ex)
 
-    M("\n    You can (and should) use it via regular logging.getLogger after that, e.g. let's set logging level to DEBUG now")
+    M(
+        "\n    You can (and should) use it via regular logging.getLogger after that, e.g. let's set logging level to DEBUG now"
+    )
     logging.getLogger('test').setLevel(logging.DEBUG)
     ll.debug("... now debug messages are also displayed")