style: General type hints fixes and imports optimizing

scrapling/core/_types.py

@@ -4,6 +4,7 @@ Type definitions for type checking purposes.
 
 from typing import (
     TYPE_CHECKING,
+    overload,
     Any,
     Callable,
     Dict,

scrapling/core/custom_types.py

@@ -7,14 +7,15 @@ from orjson import dumps, loads
 
 from scrapling.core._types import (
     Dict,
-    Iterable,
     List,
-    Literal,
-    Optional,
-    Pattern,
-    SupportsIndex,
-    TypeVar,
     Union,
+    TypeVar,
+    Literal,
+    Pattern,
+    Iterable,
+    Optional,
+    Generator,
+    SupportsIndex,
 )
 from scrapling.core.utils import _is_iterable, flatten
 from scrapling.core._html_utils import _replace_entities
@@ -341,7 +342,9 @@ class AttributesHandler(Mapping[str, _TextHandlerType]):
         """Acts like the standard dictionary `.get()` method"""
         return self._data.get(key, default)
 
-    def search_values(self, keyword, partial=False):
+    def search_values(
+        self, keyword: str, partial: bool = False
+    ) -> Generator["AttributesHandler", None, None]:
         """Search current attributes by values and return a dictionary of each matching item
         :param keyword: The keyword to search for in the attribute values
         :param partial: If True, the function will search if keyword in each value instead of perfect match

scrapling/core/storage.py

@@ -9,7 +9,7 @@ from orjson import dumps, loads
 from tldextract import extract as tld
 
 from scrapling.core.utils import _StorageTools, log
-from scrapling.core._types import Dict, Optional, Union
+from scrapling.core._types import Dict, Optional, Union, Any
 
 
 class StorageSystemMixin(ABC):
@@ -106,7 +106,7 @@ class SQLiteStorageSystem(StorageSystemMixin):
         """)
         self.connection.commit()
 
-    def save(self, element: HtmlElement, identifier: str):
+    def save(self, element: HtmlElement, identifier: str) -> None:
         """Saves the elements unique properties to the storage for retrieval and relocation later
 
         :param element: The element itself which we want to save to storage.
@@ -126,7 +126,7 @@ class SQLiteStorageSystem(StorageSystemMixin):
             self.cursor.fetchall()
             self.connection.commit()
 
-    def retrieve(self, identifier: str) -> Optional[Dict]:
+    def retrieve(self, identifier: str) -> Optional[Dict[str, Any]]:
         """Using the identifier, we search the storage and return the unique properties of the element
 
         :param identifier: This is the identifier that will be used to retrieve the element from the storage. See

scrapling/core/utils.py

@@ -5,7 +5,7 @@ from itertools import chain
 import orjson
 from lxml import html
 
-from scrapling.core._types import Any, Dict, Iterable, Union
+from scrapling.core._types import Any, Dict, Iterable, Union, List
 
 # Using cache on top of a class is a brilliant way to achieve a Singleton design pattern without much code
 from functools import lru_cache  # isort:skip
@@ -41,8 +41,8 @@ def setup_logger():
 log = setup_logger()
 
 
-def is_jsonable(content: Union[bytes, str]) -> bool:
-    if type(content) is bytes:
+def is_jsonable(content: bytes | str) -> bool:
+    if isinstance(content, bytes):
         content = content.decode()
 
     try:
@@ -52,14 +52,14 @@ def is_jsonable(content: Union[bytes, str]) -> bool:
         return False
 
 
-def flatten(lst: Iterable):
+def flatten(lst: Iterable[Any]) -> List[Any]:
     return list(chain.from_iterable(lst))
 
 
-def _is_iterable(s: Any):
+def _is_iterable(obj: Any) -> bool:
     # This will be used only in regex functions to make sure it's iterable but not string/bytes
     return isinstance(
-        s,
+        obj,
         (
             list,
             tuple,