Doc Improvements

Author: VermiIIi0n

.github/workflows/ci-workflow.yml

@@ -1,7 +1,9 @@
 name: Python CI
 
 on:
-  push: {}
+  push:
+    branches:
+      - master
   pull_request:
     branches: [ master ]
 

.github/workflows/publish-workflow.yml

@@ -11,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v3
       with:
         python-version: '3.x'
     - name: Install dependencies

README.md

@@ -24,19 +24,19 @@ I will try to keep up with the latest version of `TinyDB`.
 
 # 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 do something before or after 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.
+* **Redesigned ID & Doc Class**: You can [replace](#replacing-id-&-document-class) and [customise them](#customise-id-class) more pleasingly.
 
-* **DB-level caching**: This significantly improves the performance of all operations. However, the responsibility of converting the data to the correct type is transferred to the Storage[^2][^disable-db-level]. 
+* **DB-level Caching**: This significantly improves the performance of all operations. However, the responsibility of converting the data to the correct type is transferred to the Storage[^2][^disable-db-level]. 
 
 * **Built-in `Modifier`**: Use `Modifier` to easily [encrypt](#encryption), [compress](./docs/Modifier.md#Compression) and [extend types](./docs/Modifier.md#Conversion) of your database. Sure you can do much more than these. _(See [Modifier](./docs/Modifier.md))_
 
 * **Isolation Level**: Performance or ACID? It's up to you[^isolevel].
 
 * **Atomic Write**: **A**CID!
 
-* **Batch search by IDs**: `search` method now takes an extra `doc_ids` argument (works like an additional condition)
+* **Batch Search By IDs**: `search` method now takes an extra `doc_ids` argument (works like an additional condition)
 
 # How to use it?
 
@@ -63,7 +63,7 @@ That's it.
 
 ******
 
-## Documents For Advances Usage
+## Documents For Advanced Usage
 
 * [Modifier](./docs/Modifier.md)
 * [Event Hooks](./docs/EventHooks.md)
@@ -134,8 +134,8 @@ db.isolevel = 2
 `isolevel`:
 
 0. No isolation
-1. Serialised CRUD operations (Also ensures thread safety) (default)
-2. Deepcopy documents on CRUD (Ensures `Index` & `Query Cache` consistency)
+1. Serialised(Atomic) CRUD operations (Also ensures thread safety) (default)
+2. Deepcopy documents on insertion and searching (**CR**UD) (Ensures `Index` & `Query Cache` consistency)
 
 
 

docs/Modifier.md

@@ -24,7 +24,8 @@ async def main():
 asyncio.run(main())
 
 ```
-That's it! After calling `Modifier.Encryption.AES_GCM`, the database will be encrypted.  
+That's it! 
+After calling `Modifier.Encryption.AES_GCM`, the database will be encrypted.  
 **Applying modifiers at the beginning of the database instantiation is strongly recommended.**
 
 ## Order
@@ -93,7 +94,7 @@ Modifier.Encryption.AES_GCM(db, "your key goes here")
 **Order-Aware**
 
 This subclass contains methods to add compression to the storage.
-## `brotli`
+### `brotli`
 
 * `events`: `write.post`, `read.pre`
 * `input`: `str`|`bytes`
@@ -107,7 +108,7 @@ db = TinyDB("db.json", access_mode="rb+")  # Binary mode is required
 Modifier.Compression.brotli(db)
 ```
 
-##  `blosc2`
+###  `blosc2`
 
 * `events`: `write.post`, `read.pre`
 * `input`: `str`|`bytes`
@@ -124,15 +125,16 @@ Modifier.Compression.blosc2(db)
 
 This subclass contains methods to convert the data to a different format.
 
-## `ExtendedJSON`
+### `ExtendedJSON`
 
 * `events`: `write.pre`, `read.post`
 * `input`: `dict`
 * `output`: `dict`
 
 This method allows JSONStorage to store more data types.
 
-### Extended Types
+#### Extended Types
+
 * `uuid.UUID`
 * `datetime.datetime`: Converted to `ISO 8601` format.
 * `datetime.timestamp`
@@ -149,11 +151,11 @@ db = TinyDB("db.json")
 Modifier.Converter.ExtendedJSON(db)
 ```
 
-### Customise Extended Types
+#### Customise Extended Types
 
 By passing `type_hooks` and `marker_hooks` arguments to the modifier, you can modifiy the behaviour of the conversion.
 
-### To modify `type_hooks`
+##### To modify `type_hooks`
 
 ```Python
 type_hooks = {
@@ -162,24 +164,56 @@ type_hooks = {
 }
 ```
 
-The first argument is the data to be converted.  
-The second argument is the converter function, useful when you are dealing with `Container` types.
+The first argument `x` is the data to be converted.  
+The second argument `c` is the converter function, useful when you are dealing with `Container` types.
 
-In this example, we convert `int` to a `dict` with a `$int` key (i.e. `42` -> `{"$int": "42"}`), and we remove `set` from the conversion.  
+In this example, we convert `int` to a `dict` with a `$int` key and a `str` as the value(i.e. `42` -> `{"$int": "42"}`), and we remove `set` from the conversion.  
 Return value of the hook does not necessarily have to be a `dict`. It can be anything that is JSON serializable.
 
-### To modify `marker_hooks`
+##### To modify `marker_hooks`
 
 A marker is a special key that is used to identify the type of the data.  
-We use a MongoDB style marker by default (starts with `'$'`), but you can change it to anything you want.
+We use a MongoDB style marker by default (a `str` starts with `'$'`), but you can change it to anything you want.
 
 ```Python
 marker_hooks = {
     "$int": lambda x, r: int(x["$int"]),
 }
 ```
 
-The first argument is the data to be converted.  
-The second argument is the reverse converter function, useful when you are dealing with `Container` types.
+The first argument `x` is the data to be converted.  
+The second argument `r` is the reverse converter function, useful when you are dealing with `Container` types.
 
 In this example, we convert `dict` with the `$int` marker back to an `int` (i.e. `{"$int":"42"}` -> `42`).
+
+##### A more complicated example
+
+```Python
+import asyncio
+from asynctinydb import TinyDB, Modifier
+
+class Myclass:
+  def __init__(self, value: bytes):
+    self.value = value
+
+type_hooks = {
+  Myclass: lambda x, c: {"$Myclass": c(x.value)}
+  # Converts `bytes` with the converter
+}
+
+marker_hooks = {
+  "$Myclass": lambda x, r: Myclass(r(x["$Myclass"]))
+  # Converts back to `bytes` then pass it to Myclass
+}
+
+async def main():
+  async with TinyDB("test.json") as db:
+    Modifier.Conversion.ExtendedJSON(db, 
+                                     type_hooks=type_hooks, 
+                                     marker_hooks=marker_hooks
+                                    )
+    db.insert({"test": Myclass(b"some bytes")})
+
+asyncio.run(main())
+```
+

pyproject.toml

@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
     "Operating System :: OS Independent",

tests/conftest.py

@@ -27,34 +27,36 @@
     "json-nocache", "json_extend"] + mods)
 async def db(request):
     with tempfile.TemporaryDirectory() as tmpdir:
-        if request.param == "json":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
-        elif request.param == "memory":
-            db_ = TinyDB(storage=MemoryStorage)
-        elif request.param == "json-encrypted":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"),
+        match request.param:
+            case "json":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
+            case "memory":
+                db_ = TinyDB(storage=MemoryStorage)
+            case "json-encrypted":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"),
                          storage=EncryptedJSONStorage, key=key)
-        elif request.param == "json-encrypted-modifier":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), access_mode="rb+")
-            Modifier.Encryption.AES_GCM(db_, key=key)
-        elif request.param == "json-isolevel0":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), isolevel=0)
-        elif request.param == "json-isolevel1":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
-            db_.isolevel = 1
-        elif request.param == "json-isolevel2":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
-            db_.isolevel = 2
-        elif request.param == "json-nocache":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), no_dbcache=True)
-        elif request.param == "json_extend":
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
-            Modifier.Conversion.ExtendedJSON(db_)
-        elif isinstance(request.param, tuple):
-            db_ = TinyDB(os.path.join(tmpdir, "test.db"),
-                         access_mode="rb+", storage=JSONStorage)
-            for mod in request.param:
-                mod(db_)
+            case "json-encrypted-modifier":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), access_mode="rb+")
+                Modifier.Encryption.AES_GCM(db_, key=key)
+            case "json-isolevel0":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), isolevel=0)
+            case "json-isolevel1":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
+                db_.isolevel = 1
+            case "json-isolevel2":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
+                db_.isolevel = 2
+            case "json-nocache":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), no_dbcache=True)
+            case "json_extend":
+                db_ = TinyDB(os.path.join(tmpdir, "test.db"), storage=JSONStorage)
+                Modifier.Conversion.ExtendedJSON(db_)
+            case _:
+                if isinstance(request.param, tuple):
+                    db_ = TinyDB(os.path.join(tmpdir, "test.db"),
+                            access_mode="rb+", storage=JSONStorage)
+                    for mod in request.param:
+                        mod(db_)
 
         await db_.drop_tables()
         await db_.insert_multiple({"int": 1, "char": c} for c in "abc")