Docs & Typing: Improve upsert docs, add operations type hints, test J…

tests/test_storages.py

@@ -279,3 +279,9 @@ def test_encoding(tmpdir):
 
     jap_storage = JSONStorage(path, encoding="cp936")
     assert japanese_doc == jap_storage.read()
+
+
+def test_json_invalid_mode_warning(tmpdir):
+    path = str(tmpdir.join('test.db'))
+    with pytest.warns(UserWarning, match='Using an `access_mode` other than'):
+        JSONStorage(path, access_mode='w')

tinydb/operations.py

@@ -9,61 +9,64 @@
 """
 
 
-def delete(field):
+from typing import Callable, Mapping, Any, Union
+
+
+def delete(field: str) -> Callable[[Mapping], None]:
     """
     Delete a given field from the document.
     """
-    def transform(doc):
+    def transform(doc: Mapping):
         del doc[field]
 
     return transform
 
 
-def add(field, n):
+def add(field: str, n: Union[int, float]) -> Callable[[Mapping], None]:
     """
     Add ``n`` to a given field in the document.
     """
-    def transform(doc):
+    def transform(doc: Mapping):
         doc[field] += n
 
     return transform
 
 
-def subtract(field, n):
+def subtract(field: str, n: Union[int, float]) -> Callable[[Mapping], None]:
     """
     Subtract ``n`` to a given field in the document.
     """
-    def transform(doc):
+    def transform(doc: Mapping):
         doc[field] -= n
 
     return transform
 
 
-def set(field, val):
+def set(field: str, val: Any) -> Callable[[Mapping], None]:
     """
     Set a given field to ``val``.
     """
-    def transform(doc):
+    def transform(doc: Mapping):
         doc[field] = val
 
     return transform
 
 
-def increment(field):
+def increment(field: str) -> Callable[[Mapping], None]:
     """
     Increment a given field in the document by 1.
     """
-    def transform(doc):
+    def transform(doc: Mapping):
         doc[field] += 1
 
     return transform
 
 
-def decrement(field):
+def decrement(field: str) -> Callable[[Mapping], None]:
     """
     Decrement a given field in the document by 1.
     """
-    def transform(doc):
+    def transform(doc: Mapping):
         doc[field] -= 1
 
     return transform

tinydb/table.py

@@ -554,9 +554,12 @@ def upsert(self, document: Mapping, cond: Optional[QueryLike] = None) -> List[in
         """
         Update documents, if they exist, insert them otherwise.
 
-        Note: This will update *all* documents matching the query. Document
-        argument can be a tinydb.table.Document object if you want to specify a
-        doc_id.
+        Note: This will update *all* documents matching the query.
+        For example, if the query matches 3 documents, all 3 will be updated
+        with the new data. If no documents match, a new one is inserted.
+
+        Document argument can be a tinydb.table.Document object if you want
+        to specify a doc_id.
 
         :param document: the document to insert or the fields to update
         :param cond: which document to look for, optional if you've passed a