add docstring and typing, thanks codemium.com for this great docstrin…

…g generator 99% accurate

easy/admin/decorators.py

@@ -1,32 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import asdict
 from functools import wraps
+from typing import Optional, Callable, Union, List
+
 from django import utils as django_utils
 from django.core.cache import cache as django_cache
 from django.utils.safestring import mark_safe
 
 from easy import helper
 
+Model: "django.db.models.Model"
 
 def smart(**kwargs):
     """
     Simple decorator to get custom fields on admin class, using this you will use less line codes
 
-    :param short_description: description of custom field
-    :type str:
-
-    :param admin_order_field: field to order on click
-    :type str:
-
-    :param allow_tags: allow html tags
-    :type bool:
-
-    :param boolean: if field is True, False or None
-    :type bool:
-
-    :param empty_value_display: Default value when field is null
-    :type str:
-
-    :return: method decorated
-    :rtype: method
+    :param short_description: description of custom field (Optional[str])
+    :type short_description: str
+    :param admin_order_field: field to order on click (Optional[str])
+    :type admin_order_field: str
+    :param allow_tags: allow html tags (Optional[bool])
+    :type allow_tags: bool
+    :param boolean: if field boolean (Optional[bool])
+    :type boolean: bool
+    :param empty_value_display: Default value when field is null (Optional[str])
+    :type empty_value_display: str
+
+    :return: method decorated (Callable)
     """
 
     def decorator(func):
@@ -45,8 +46,15 @@ def decorator(func):
 }
 
 
-def short(**kwargs):
-    def decorator(func):
+def short(**kwargs: Union[str, bool]) -> Callable:
+    """
+    Short decorator to set some attrs on admin method.
+
+    :param kwargs: key-value pairs to set on method.
+    :return: method decorated (Callable)
+    """
+
+    def decorator(func: Callable) :
         for key, value in kwargs.items():
             if key in FUNCTION_MAP:
                 setattr(func, FUNCTION_MAP[key], value)
@@ -63,8 +71,16 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
-def action(short_description, permission=None):
-    def decorator(func):
+def action(short_description: str, permission: Optional[Union[str, List[str]]] = None) -> Callable:
+    """
+    Action decorator to set some attrs on admin method.
+
+    :param short_description: description of custom field (str)
+    :param permission: permission to use. (Optional[Union[str, List[str]]])
+    :return: method decorated (Callable)
+    """
+
+    def decorator(func: Callable) -> Callable:
         func.short_description = short_description
         if permission:
             if isinstance(permission, str):
@@ -76,8 +92,15 @@ def decorator(func):
     return decorator
 
 
-def utils(django_utils_function):
-    def decorator(func):
+def utils(django_utils_function: str) -> Callable[[Callable], Callable]:
+    """
+    Util decorator to apply a django.utils function on the method result.
+
+    :param django_utils_function: name of the function to apply (str)
+    :return: function decorated (Callable[[Callable], Callable])
+    """
+
+    def decorator(func: Callable):
         util_function = helper.deep_getattribute(django_utils, django_utils_function)
         if isinstance(util_function, helper.Nothing):
             raise Exception('Function {} not exist on django.utils module.'.format(django_utils_function))
@@ -91,9 +114,17 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
-def filter(django_builtin_filter, load=None, *extra):  # noqa
+def filter(django_builtin_filter: str, load: Optional[str] = None, *extra: Union[str, List[str]]) -> Callable[[Callable], Callable]:
+    """
+    Filter decorator to apply a django builtin filter on the method result.
 
-    def decorator(func):
+    :param django_builtin_filter: name of the filter to apply (str)
+    :param load: library to be loaded like load in templatetag. (Optional[str])
+    :param extra: extra arguments to pass to the filter. (Union[str, List[str]])
+    :return: method decorated (Callable[[Callable], Callable])
+    """
+
+    def decorator(func: Callable) -> Callable:
         filter_method = helper.get_django_filter(django_builtin_filter, load)
 
         @wraps(func)
@@ -106,6 +137,10 @@ def wrapper(*args, **kwargs):
 
 
 def with_tags():
+    """
+    Decorator to mark result of method as safe and allow tags.
+    """
+
     def decorator(func):
         @wraps(func)
         def wrapper(*args, **kwargs):
@@ -114,8 +149,15 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
-def cache(seconds=60):
-    def decorator(func):
+def cache(seconds: int = 60):
+    """
+    Cache decorator to cache the result of a method.
+
+    :param seconds: The cache time in seconds. (int)
+    :return: The cached method
+    """
+
+    def decorator(func: Callable) -> Callable:
         @wraps(func)
         def wrapper(admin, model):
             cache_method_key = helper.cache_method_key(model, func.__name__)
@@ -134,8 +176,14 @@ def wrapper(admin, model):
     return decorator
 
 
-def clear_cache(model):
+def clear_cache(model: Model) -> None:
+    """
+    Clear cache for specific model.
+
+    :param model: The model to clear cache for.
+    :type model: django.db.models.Model
+    """
     cache_object_key = helper.cache_object_key(model)
     obj_methods_caches = django_cache.get(cache_object_key)
-    methods_key = obj_methods_caches.split('|')
+    methods_key = obj_methods_caches.split('|') if obj_methods_caches else []
     django_cache.delete_many(methods_key)