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]"

README.md

@@ -125,10 +125,10 @@ Cachew gives the best of two worlds and makes it both **easy and efficient**. Th
 
 # How it works
 
-- first your objects get [converted](src/cachew/marshall/cachew.py#L32) into a simpler JSON-like representation
+- first your objects get [converted](src/cachew/marshall/cachew.py#L28) into a simpler JSON-like representation
 - after that, they are mapped into byte blobs via [`orjson`](https://github.com/ijl/orjson).
 
-When the function is called, cachew [computes the hash of your function's arguments ](src/cachew/__init__.py#L575)
+When the function is called, cachew [computes the hash of your function's arguments ](src/cachew/__init__.py#L571)
 and compares it against the previously stored hash value.
 
 - If they match, it would deserialize and yield whatever is stored in the cache database
@@ -140,18 +140,18 @@ and compares it against the previously stored hash value.
 
 
 
-* automatic schema inference: [1](src/cachew/tests/test_cachew.py#L384), [2](src/cachew/tests/test_cachew.py#L398)
+* automatic schema inference: [1](src/cachew/tests/test_cachew.py#L381), [2](src/cachew/tests/test_cachew.py#L395)
 * supported types:
 
     * primitive: `str`, `int`, `float`, `bool`, `datetime`, `date`, `Exception`
 
-      See [tests.test_types](src/cachew/tests/test_cachew.py#L684), [tests.test_primitive](src/cachew/tests/test_cachew.py#L722), [tests.test_dates](src/cachew/tests/test_cachew.py#L634), [tests.test_exceptions](src/cachew/tests/test_cachew.py#L1122)
-    * [@dataclass and NamedTuple](src/cachew/tests/test_cachew.py#L599)
-    * [Optional](src/cachew/tests/test_cachew.py#L528) types
-    * [Union](src/cachew/tests/test_cachew.py#L829) types
-    * [nested datatypes](src/cachew/tests/test_cachew.py#L444)
+      See [tests.test_types](src/cachew/tests/test_cachew.py#L683), [tests.test_primitive](src/cachew/tests/test_cachew.py#L721), [tests.test_dates](src/cachew/tests/test_cachew.py#L633), [tests.test_exceptions](src/cachew/tests/test_cachew.py#L1125)
+    * [@dataclass and NamedTuple](src/cachew/tests/test_cachew.py#L598)
+    * [Optional](src/cachew/tests/test_cachew.py#L525) types
+    * [Union](src/cachew/tests/test_cachew.py#L828) types
+    * [nested datatypes](src/cachew/tests/test_cachew.py#L441)
 
-* detects [datatype schema changes](src/cachew/tests/test_cachew.py#L474) and discards old data automatically
+* detects [datatype schema changes](src/cachew/tests/test_cachew.py#L471) and discards old data automatically
 
 
 # Performance
@@ -165,20 +165,20 @@ You can find some of my performance tests in [benchmarks/](benchmarks) dir, and
 
 
 # Using
-See [docstring](src/cachew/__init__.py#L278) for up-to-date documentation on parameters and return types.
+See [docstring](src/cachew/__init__.py#L270) for up-to-date documentation on parameters and return types.
 You can also use [extensive unit tests](src/cachew/tests/test_cachew.py#L1) as a reference.
 
 Some useful (but optional) arguments of `@cachew` decorator:
 
-* `cache_path` can be a directory, or a callable that [returns a path](src/cachew/tests/test_cachew.py#L421) and depends on function's arguments.
+* `cache_path` can be a directory, or a callable that [returns a path](src/cachew/tests/test_cachew.py#L418) and depends on function's arguments.
 
    By default, `settings.DEFAULT_CACHEW_DIR` is used.
 
 * `depends_on` is a function which determines whether your inputs have changed, and the cache needs to be invalidated.
 
    By default it just uses string representation of the arguments, you can also specify a custom callable.
 
-   For instance, it can be used to [discard cache](src/cachew/tests/test_cachew.py#L118) if the input file was modified.
+   For instance, it can be used to [discard cache](src/cachew/tests/test_cachew.py#L115) if the input file was modified.
 
 * `cls` is the type that would be serialized.
 
@@ -274,7 +274,7 @@ Now you can use `@mcachew` in place of `@cachew`, and be certain things don't br
 ## Settings
 
 
-[cachew.settings](src/cachew/__init__.py#L61) exposes some parameters that allow you to control `cachew` behaviour:
+[cachew.settings](src/cachew/__init__.py#L58) exposes some parameters that allow you to control `cachew` behaviour:
 - `ENABLE`: set to `False` if you want to disable caching for without removing the decorators (useful for testing and debugging).
    You can also use [cachew.extra.disabled_cachew](src/cachew/extra.py#L25) context manager to do it temporarily.
 - `DEFAULT_CACHEW_DIR`: override to set a different base directory. The default is the "user cache directory" (see [platformdirs docs](https://github.com/tox-dev/platformdirs?tab=readme-ov-file#example-output)).

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])