refactor: add more precise type hints for Table.get (#602)

* Provide more precise type hints for Table.get

* Provide even more precise type hints for Table.get

The `doc_ids` branch always returns a list, never None.

* Add type hint for invalid use of Table.get

Author: alex-ball

tinydb/table.py

@@ -10,10 +10,12 @@
     Iterator,
     List,
     Mapping,
+    NoReturn,
     Optional,
     Union,
     cast,
-    Tuple
+    Tuple,
+    overload
 )
 
 from .queries import QueryLike
@@ -280,12 +282,50 @@ def search(self, cond: QueryLike) -> List[Document]:
 
         return docs
 
+    @overload
+    def get(self) -> NoReturn: ...
+
+    @overload
+    def get(
+        self, cond: QueryLike, doc_id: None = ..., doc_ids: None = ...
+    ) -> Optional[Document]: ...
+
+    @overload
+    def get(
+        self, *, cond: QueryLike, doc_id: None = ..., doc_ids: None = ...
+    ) -> Optional[Document]: ...
+
+    @overload
+    def get(
+        self, cond: Optional[QueryLike], doc_id: int, doc_ids: Optional[List] = ...
+    ) -> Optional[Document]: ...
+
+    @overload
+    def get(
+        self, *, cond: Optional[QueryLike] = ..., doc_id: int, doc_ids: Optional[List] = ...,
+    ) -> Optional[Document]: ...
+
+    @overload
+    def get(
+        self, cond: Optional[QueryLike], doc_id: None, doc_ids: List
+    ) -> List[Document]: ...
+
+    @overload
+    def get(
+        self, cond: Optional[QueryLike], *, doc_id: None = ..., doc_ids: List
+    ) -> List[Document]: ...
+
+    @overload
+    def get(
+        self, *, cond: Optional[QueryLike] = ..., doc_id: None = ..., doc_ids: List
+    ) -> List[Document]: ...
+
     def get(
         self,
         cond: Optional[QueryLike] = None,
         doc_id: Optional[int] = None,
         doc_ids: Optional[List] = None
-    ) -> Optional[Union[Document, List[Document]]]:
+    ):
         """
         Get exactly one document specified by a query or a document ID.
         However, if multiple document IDs are given then returns all