core/general: add assert_never + typing annotations for dataset

my/core/__init__.py

@@ -5,6 +5,7 @@ from .common import LazyLogger
 from .common import warn_if_empty
 from .common import stat, Stats
 from .common import datetime_naive, datetime_aware
+from .common import assert_never
 
 from .cfg import make_config
 from .util import __NOT_HPI_MODULE__

my/core/common.py

@@ -4,7 +4,7 @@ from datetime import datetime
 import functools
 from contextlib import contextmanager
 import types
-from typing import Union, Callable, Dict, Iterable, TypeVar, Sequence, List, Optional, Any, cast, Tuple, TYPE_CHECKING
+from typing import Union, Callable, Dict, Iterable, TypeVar, Sequence, List, Optional, Any, cast, Tuple, TYPE_CHECKING, NoReturn
 import warnings
 from . import warnings as core_warnings
 
@@ -632,5 +632,11 @@ class DummyExecutor(Executor):
     def shutdown(self, wait: bool=True) -> None:  # type: ignore[override]
         self._shutdown = True
 
+
+# see https://hakibenita.com/python-mypy-exhaustive-checking#exhaustiveness-checking
+def assert_never(value: NoReturn) -> NoReturn:
+    assert False, f'Unhandled value: {value} ({type(value).__name__})'
+
+
 # legacy deprecated import
 from .compat import cached_property as cproperty

my/core/dataset.py

@@ -1,11 +1,29 @@
+from __future__ import annotations
 from .common import assert_subpackage; assert_subpackage(__name__)
 
 from .common import PathIsh
+from .compat import Protocol
 from .sqlite import sqlite_connect_immutable
 
+## sadly dataset doesn't have any type definitions
+from typing import Iterable, Iterator, Dict, Optional, Any
+from contextlib import AbstractContextManager
+
+
+# NOTE: may not be true in general, but will be in the vast majority of cases
+row_type_T = Dict[str, Any]
+
+
+class TableT(Iterable, Protocol):
+    def find(self, *, order_by: Optional[str]=None) -> Iterator[row_type_T]: ...
+
+
+class DatabaseT(AbstractContextManager['DatabaseT'], Protocol):
+    def __getitem__(self, table: str) -> TableT: ...
+##
 
 # TODO wonder if also need to open without WAL.. test this on read-only directory/db file
-def connect_readonly(db: PathIsh):
+def connect_readonly(db: PathIsh) -> DatabaseT:
     import dataset # type: ignore
     # see https://github.com/pudo/dataset/issues/136#issuecomment-128693122
     # todo not sure if mode=ro has any benefit, but it doesn't work on read-only filesystems