Improves Type Hints

Author: VermiIIi0n

.flake8

@@ -18,13 +18,13 @@ I will try to keep up with the latest version of `TinyDB`.
 
 * **`ujson`:** Using `ujson` instead of `json`. Some arguments aren't compatible with `json`[^1]
 
-* **Storage `closed` property**: Original `TinyDB` won't raise exceptions when operating on a closed file. Now the property `closed` of `Storage` classes is required to be implemented. An `IOError` should be raised.
+* **Storage `closed` property**: Original `TinyDB` won't raise exceptions when operating on a closed file. Now the property `closed` of `Storage` classes is required to be implemented[^why-closed][^operating-on-closed].
 
-* **[Miscellaneous](#misc)**: Differences only matter in edge cases.
+* **[Miscellaneous](#misc)**: Differences that only matter in edge cases.
 
 # New Features
 
-* **Event Hooks**: You can now use event hooks to do something before or after an operation. See [Event Hooks](#event-hooks) for more details.
+* **Event Hooks**: You can now use event hooks to hook into an operation. See [Event Hooks](#event-hooks) for more details.
 
 * **Redesigned ID & Doc Class**: You can [replace](#replacing-id-&-document-class) and [customise them](#customise-id-class) more pleasingly.
 
@@ -266,7 +266,7 @@ Make sure you have implemented all the methods required by  `BaseDocument` class
 * `search` accepts optional `cond`, returns all docs if no arguments are provided
 * `get` and `contains` raises `ValueError` instead of `RuntimeError` when `cond` and `doc_id` are both `None`
 * `LRUCache` stores `tuple`s of ids instead of `list`s of docs
-* `search` and `get` treat `doc_id` and `doc_ids` as extra conditions instead of ignoring conditions when they are provided. That is to say, when `cond` and `doc_id(s)` are passed, they return docs satisfies both conditions.
+* `search` and `get` treat `doc_id` and `doc_ids` as extra conditions instead of ignoring conditions when they are provided. That is to say, when `cond` and `doc_id(s)` are passed, they return docs satisfies both `cond` and `doc_id(s)`.
 
 
 
@@ -275,3 +275,6 @@ Make sure you have implemented all the methods required by  `BaseDocument` class
 [^UUID-version]:Currently using UUID4
 [^disable-db-level]: See [DB-level caching](#db-level-caching) to learn how to disable this feature if it causes dirty reads.
 [^isolevel]: See [isolevel](#isolation-level)
+[^why-closed]: This is for `Middileware` classes to reliably determine whether the `Storage` is closed, so they can raise `IOError`
+[^operating-on-closed]: An `IOError` should be raised when operating on a closed storage.
+

README.md

@@ -26,6 +26,7 @@
 
 from .queries import Query, where
 from .storages import Storage, JSONStorage, EncryptedJSONStorage, MemoryStorage
+from .middlewares import CachingMiddleware
 from .modifier import Modifier
 from .database import TinyDB
 from .version import __version__  # noqa
@@ -34,6 +35,7 @@
 __all__ = (
     "TinyDB", "Storage", "JSONStorage",
     "EncryptedJSONStorage", "MemoryStorage",
+    "CachingMiddleware",
     "Query", "where", "BaseID", "BaseDocument",
     "Modifier", "IncreID", "Document", "UUID"
 )

asynctinydb/__init__.py

@@ -184,7 +184,7 @@ def get_create_loop():
     try:
         return asyncio.get_running_loop()
     except RuntimeError:
-        loop: asyncio.AbstractEventLoop = getattr(_LOCAL, "loop", None)
+        loop: asyncio.AbstractEventLoop | None = getattr(_LOCAL, "loop", None)
         if loop is None or loop.is_closed():
             loop = asyncio.new_event_loop()
             asyncio.set_event_loop(loop)

asynctinydb/async_utils.py

@@ -3,19 +3,20 @@
 """
 
 from __future__ import annotations
-from typing import AsyncGenerator, Type, overload, TypeVar, Generic
+from typing import AsyncGenerator, Type, overload, TypeVar, Generic, Any
 
 from .storages import Storage, JSONStorage
+from .middlewares import Middleware
 from .table import Table, Document, IncreID, IDVar, DocVar, BaseDocument
 from .utils import with_typehint, sync_await
 
 # The table's base class. This is used to add type hinting from the Table
 # class to TinyDB. Currently, this supports PyCharm, Pyright/VS Code and MyPy.
 TableBase: Type[Table] = with_typehint(Table)
-_S = TypeVar("_S", bound=Storage)
+S = TypeVar("S", bound=Storage, covariant=True)
 
 
-class TinyDB(Generic[_S], TableBase):
+class TinyDB(Generic[S], TableBase):
     """
     The main class of TinyDB.
 
@@ -86,16 +87,14 @@ class TinyDB(Generic[_S], TableBase):
     default_storage_class = JSONStorage
 
     @overload
-    def __init__(self: TinyDB[_S], *args, storage: Type[_S], **kw) -> None:
-        ...
-
+    def __init__(self: TinyDB[S], *args, storage: Type[S], **kw) -> None:
+        """For `Storage` classes passed to `storage`"""
     @overload
-    def __init__(self: TinyDB[Storage], *args, storage, **kw) -> None:
-        ...
-
+    def __init__(self: TinyDB[S], *args, storage: Middleware[S], **kw) -> None:
+        """For `Middleware` passed to `storage`"""
     @overload
     def __init__(self: TinyDB[JSONStorage], *args, **kw) -> None:
-        ...
+        """For default `JSONStorage`"""
 
     def __init__(self, *args, **kw) -> None:
         """
@@ -109,7 +108,7 @@ def __init__(self, *args, **kw) -> None:
         self._no_dbcache: bool = kw.pop("no_dbcache", False)
 
         # Prepare the storage
-        self._storage: _S = kw.pop(
+        self._storage: S = kw.pop(
             "storage", type(self).default_storage_class)(*args, **kw)
 
         self._opened = True
@@ -271,7 +270,7 @@ async def drop_table(self, name: str) -> None:
         await self.storage.write(data)
 
     @property
-    def storage(self) -> _S:
+    def storage(self) -> S:
         """
         Get the storage instance used for this TinyDB instance.
 

asynctinydb/database.py

@@ -27,7 +27,7 @@ def __init__(self, actions: Iterable[ActionVar] | None = None,
         * `limit` is the maximum number of actions to add to the chain. 
         Set to 0 for unlimited.
         """
-        self._seq = list[ActionVar](actions or [])
+        self._seq: list[ActionVar] = list(actions or [])
         self.limit = limit
 
     def append(self, action: ActionVar) -> None:
@@ -232,6 +232,7 @@ class EventHook(dict[str, BaseActionChain]):
     # Event Hook Class
     Binds events to action chains.
     """
+
     def __init__(self, chain: Mapping[str, Iterable[ActionVar]] | None = None):
         dict.__init__(self)
         if chain is not None:

asynctinydb/event_hooks.py

@@ -3,10 +3,14 @@
 middlewares and implementations.
 """
 
+from __future__ import annotations
+from typing import TypeVar, Type, Generic
 from .storages import Storage
 
+S = TypeVar('S', bound=Storage, covariant=True)
 
-class Middleware:
+
+class Middleware(Generic[S]):
     """
     The base class for all Middlewares.
 
@@ -17,9 +21,9 @@ class Middleware:
     constructor so the middleware chain can be configured properly.
     """
 
-    def __init__(self, storage_cls):
+    def __init__(self, storage_cls: Type[S]):
         self._storage_cls = storage_cls
-        self.storage: Storage = None
+        self.storage: Storage = None  # type: ignore
 
     @property
     def on(self):
@@ -80,7 +84,7 @@ def __getattr__(self, name):
         return getattr(self.__dict__['storage'], name)
 
 
-class CachingMiddleware(Middleware):
+class CachingMiddleware(Middleware[S]):
     """
     Add some caching to TinyDB.
 
@@ -89,7 +93,7 @@ class CachingMiddleware(Middleware):
     from cache.
     """
 
-    def __init__(self, storage_cls, cache_size=1000):
+    def __init__(self, storage_cls: Type[S], cache_size=1000):
         # Initialize the parent constructor
         super().__init__(storage_cls)
 

asynctinydb/middlewares.py

@@ -4,15 +4,16 @@
 from typing import Any, Callable, TypeVar
 from warnings import warn
 from functools import partial
-from .storages import Storage
+from .storages import Storage, StorageWithWriteReadPrePostHooks
 from .utils import async_run
 from .database import TinyDB
 
 
-_S = TypeVar('_S', bound=Storage)
+S = TypeVar('S', bound=Storage)
+SWRPH = TypeVar("SWRPH", bound=StorageWithWriteReadPrePostHooks)
 
 
-def _get_storage(item: _S | TinyDB[_S]) -> _S:
+def _get_storage(item: S | TinyDB[S]) -> S:
     """Get the storage from a TinyDB or Storage object."""
     if isinstance(item, TinyDB):
         return item.storage
@@ -27,7 +28,7 @@ class Encryption:
         """
 
         @staticmethod
-        def AES_GCM(s: _S | TinyDB[_S], key: str | bytes, **kw) -> _S:
+        def AES_GCM(s: SWRPH | TinyDB[SWRPH], key: str | bytes, **kw) -> SWRPH:
             """
             ### Add AES-GCM Encryption to TinyDB Storage
             Hooks to `write.post` and `read.pre` to encrypt/decrypt data.
@@ -71,8 +72,8 @@ async def encrypt_aes_gcm(_: str, s: Storage, data: str | bytes):
             async def decrypt_aes_gcm(_: str, s: Storage, data: bytes):
                 d_len = data[0]  # digest length
                 digest = data[1: d_len + 1]
-                cipher: GcmMode = AES.new(
-                    key, nonce=data[d_len + 1:d_len + 17], **kw)  # type: ignore
+                cipher: GcmMode = AES.new(key,  # type: ignore
+                                          nonce=data[d_len + 1:d_len + 17], **kw)
                 data = data[d_len + 17:]
                 task = async_run(cipher.decrypt_and_verify, data, digest)
                 ret = await task
@@ -84,8 +85,8 @@ async def decrypt_aes_gcm(_: str, s: Storage, data: bytes):
             return s
 
     @classmethod
-    def add_encryption(cls, s: _S | TinyDB[_S], key: str | bytes,
-                       encoding=None, **kw) -> _S:
+    def add_encryption(cls, s: SWRPH | TinyDB[SWRPH], key: str | bytes,
+                       encoding: str = None, **kw) -> SWRPH:
         """
         ### Add AES-GCM Encryption to TinyDB Storage
         **Deprecated, consider using Modifier.Encryption.AES_GCM**
@@ -113,7 +114,7 @@ class Compression:
         """
 
         @staticmethod
-        def brotli(s: _S | TinyDB[_S], quality=11, **kw) -> _S:
+        def brotli(s: SWRPH | TinyDB[SWRPH], quality=11, **kw) -> SWRPH:
             """
             ### Add Brotli Compression to TinyDB Storage
             Hooks to `write.post` and `read.pre` to compress/decompress data.
@@ -153,7 +154,7 @@ async def decompress_brotli(ev: str, s: Storage, data: bytes):
             return s
 
         @staticmethod
-        def blosc2(s: _S | TinyDB[_S], clevel=9, **kw) -> _S:
+        def blosc2(s: SWRPH | TinyDB[SWRPH], clevel=9, **kw) -> SWRPH:
             """
             ### Add Blosc2 Compression to TinyDB Storage
             Hooks to `write.post` and `read.pre` to compress/decompress data.
@@ -198,13 +199,13 @@ class Conversion:
         """
 
         @staticmethod
-        def ExtendedJSON(s: _S | TinyDB[_S],
+        def ExtendedJSON(s: SWRPH | TinyDB[SWRPH],
                          type_hooks: dict[type, None | Callable[[
                              Any, Callable[[Any], Any]],
                              dict[str, Any]]] = None,
                          marker_hooks: dict[str, None | Callable[[
                              dict[str, Any], Callable[[Any], Any]],
-                             Any]] = None) -> _S:
+                             Any]] = None) -> SWRPH:
             """
             ### Extend JSON Data Types
 
@@ -325,7 +326,7 @@ def convert(obj, memo: set = None):
                             ret = hook(obj, _convert)
                 return ret
 
-            def recover(obj):
+            def recover(obj) -> Any:
                 """
                 ### Recursively recovery object from extended JSON
                 **No loop reference check**