extra docstrings

Author: penguinolog

logwrap/class_decorator.py

@@ -71,7 +71,6 @@ def __init__(self, func: typing.Optional[typing.Callable[..., ReturnType]] = Non
         :param func: function to wrap
         :type func: typing.Optional[typing.Callable]
         """
-        # noinspection PyArgumentList
         super().__init__()
         self.__func: typing.Optional[typing.Callable[..., ReturnType]] = func
         if self.__func is not None:
@@ -81,6 +80,7 @@ def __init__(self, func: typing.Optional[typing.Callable[..., ReturnType]] = Non
     def _func(self) -> typing.Optional[typing.Callable[..., ReturnType]]:
         """Get wrapped function.
 
+        :return: wrapped function
         :rtype: typing.Optional[typing.Callable]
         """
         return self.__func  # pragma: no cover
@@ -91,6 +91,7 @@ def _get_function_wrapper(self, func: typing.Callable[..., ReturnType]) -> typin
 
         :param func: Wrapped function
         :type func: typing.Callable
+        :return: function wrapper
         :rtype: typing.Callable
         """
         raise NotImplementedError()
@@ -131,7 +132,7 @@ def __repr__(self) -> str:
         :return: representation for logging/debug purposes
         :rtype: str
         """
-        return f"<{self.__class__.__name__}({self.__func!r}) at 0x{id(self):X}>"  # pragma: no cover
+        return f"<{self.__class__.__name__}({self.__func!r}) at 0x{id(self):X}>"
 
 
 # 8<----------------------------------------------------------------------------

logwrap/class_decorator.pyx

@@ -34,7 +34,6 @@ cdef class BaseDecorator:
         :param func: function to wrap
         :type func: typing.Optional[typing.Callable]
         """
-        # noinspection PyArgumentList
         super().__init__()
         self._func = func
         if self._func is not None:
@@ -45,6 +44,7 @@ cdef class BaseDecorator:
 
         :param func: Wrapped function
         :type func: typing.Callable
+        :return: function wrapper
         :rtype: typing.Callable
         """
         raise NotImplementedError()
@@ -73,4 +73,4 @@ cdef class BaseDecorator:
         :return: representation for logging/debug purposes
         :rtype: str
         """
-        return f"<{self.__class__.__name__}({self._func!r}) at 0x{id(self):X}>"  # pragma: no cover
+        return f"<{self.__class__.__name__}({self._func!r}) at 0x{id(self):X}>"

logwrap/log_wrap.py

@@ -85,14 +85,14 @@ def __str__(self) -> str:
         :return: string representation for parameter. */** flags is attached if positional (*args) or keyword (**kwargs)
         :rtype: str
         """
-        # POSITIONAL_ONLY is only in precompiled functions
+        # POSITIONAL_ONLY is only in precompiled functions or Python 3.8+
         if self.kind == self.POSITIONAL_ONLY:  # pragma: no cover
             as_str: str = "" if self.name is None else f"<{self.name}>"
         else:
             as_str = self.name or ""
 
         # Add annotation if applicable (python 3 only)
-        if self.annotation is not self.empty:  # pragma: no cover
+        if self.annotation is not self.empty:
             as_str += f": {inspect.formatannotation(self.annotation)!s}"
 
         value = self.value
@@ -145,7 +145,6 @@ def bind_args_kwargs(sig: inspect.Signature, *args: typing.Any, **kwargs: typing
     return result
 
 
-# noinspection PyAbstractClass
 class LogWrap(class_decorator.BaseDecorator):
     """Base class for LogWrap implementation."""
 
@@ -270,6 +269,7 @@ def _get_logger_for_func(self, func: FuncResultType) -> logging.Logger:
     def log_level(self) -> int:
         """Log level for normal behavior.
 
+        :return: log level for normal behavior
         :rtype: int
         """
         return self.__log_level
@@ -290,6 +290,7 @@ def log_level(self, val: int) -> None:
     def exc_level(self) -> int:
         """Log level for exceptions.
 
+        :return: log level for exceptions cases
         :rtype: int
         """
         return self.__exc_level
@@ -310,6 +311,7 @@ def exc_level(self, val: int) -> None:
     def max_indent(self) -> int:
         """Maximum indentation.
 
+        :return: maximum allowed identation before switch to normal repr
         :rtype: int
         """
         return self.__max_indent
@@ -330,6 +332,7 @@ def max_indent(self, val: int) -> None:
     def blacklisted_names(self) -> typing.List[str]:
         """List of arguments names to ignore in log.
 
+        :return: list of arguments to ignore in log
         :rtype: typing.List[str]
         """
         return self.__blacklisted_names
@@ -338,6 +341,7 @@ def blacklisted_names(self) -> typing.List[str]:
     def blacklisted_exceptions(self) -> typing.List[typing.Type[Exception]]:
         """List of exceptions to re-raise without log traceback and text.
 
+        :return: list of exceptions to re-raise silent
         :rtype: typing.List[typing.Type[Exception]]
         """
         return self.__blacklisted_exceptions
@@ -346,6 +350,7 @@ def blacklisted_exceptions(self) -> typing.List[typing.Type[Exception]]:
     def log_call_args(self) -> bool:
         """Flag: log call arguments before call.
 
+        :return: log cal arguments before call
         :rtype: bool
         """
         return self.__log_call_args
@@ -366,6 +371,7 @@ def log_call_args(self, val: bool) -> None:
     def log_call_args_on_exc(self) -> bool:
         """Flag: log call arguments on exception.
 
+        :return: log call arguments in case of exception logging
         :rtype: bool
         """
         return self.__log_call_args_on_exc
@@ -386,6 +392,7 @@ def log_call_args_on_exc(self, val: bool) -> None:
     def log_traceback(self) -> bool:
         """Flag: log traceback on exception.
 
+        :return: log traceback in case of exception logging
         :rtype: bool
         """
         return self.__log_traceback
@@ -406,6 +413,7 @@ def log_traceback(self, val: bool) -> None:
     def log_result_obj(self) -> bool:
         """Flag: log result object.
 
+        :return: log execution result object
         :rtype: bool
         """
         return self.__log_result_obj
@@ -426,6 +434,7 @@ def log_result_obj(self, val: bool) -> None:
     def _logger(self) -> typing.Optional[logging.Logger]:
         """Logger instance.
 
+        :return: logger instance if configured
         :rtype: typing.Optional[logging.Logger]
         """
         return self.__logger
@@ -434,6 +443,7 @@ def _logger(self) -> typing.Optional[logging.Logger]:
     def _spec(self) -> typing.Optional[typing.Callable[..., FuncResultType]]:
         """Spec for function arguments.
 
+        :return: function specification to grab information from
         :rtype: typing.Callable
         """
         return self.__spec
@@ -560,8 +570,11 @@ def _get_func_args_repr(
     def _make_done_record(self, logger: logging.Logger, func_name: str, result: typing.Any) -> None:
         """Construct success record.
 
+        :param logger: logger instance to use
         :type logger: logging.Logger
+        :param func_name: function name
         :type func_name: str
+        :param result: function execution result
         :type result: typing.Any
         """
         msg: str = f"Done: {func_name!r}"
@@ -573,19 +586,27 @@ def _make_done_record(self, logger: logging.Logger, func_name: str, result: typi
     def _make_calling_record(self, logger: logging.Logger, name: str, arguments: str, method: str = "Calling") -> None:
         """Make log record before execution.
 
+        :param logger: logger instance to use
         :type logger: logging.Logger
+        :param name: function name
         :type name: str
+        :param arguments: function arguments repr
         :type arguments: str
+        :param method: "calling" or "awaiting"
         :type method: str
         """
         logger.log(level=self.log_level, msg=f"{method}: \n{name}({arguments if self.log_call_args else ''})")
 
     def _make_exc_record(self, logger: logging.Logger, name: str, arguments: str, exception: Exception) -> None:
         """Make log record if exception raised.
 
+        :param logger: logger instance to use
         :type logger: logging.Logger
+        :param name: function name
         :type name: str
+        :param arguments: function arguments repr
         :type arguments: str
+        :param exception: exception captured
         :type exception: Exception
         """
         exc_info = sys.exc_info()

logwrap/log_wrap.pyx

@@ -251,12 +251,20 @@ cdef class LogWrap(class_decorator.BaseDecorator):
 
     @property
     def blacklisted_names(self) -> typing.List[str]:
-        """List of arguments names to ignore in log."""
+        """List of arguments names to ignore in log.
+
+        :return: list of arguments to ignore in log
+        :rtype: typing.List[str]
+        """
         return self.__blacklisted_names
 
     @property
     def blacklisted_exceptions(self) -> typing.List[typing.Type[Exception]]:
-        """List of exceptions to re-raise without log."""
+        """List of exceptions to re-raise without log.
+
+        :return: list of exceptions to re-raise silent
+        :rtype: typing.List[typing.Type[Exception]]
+        """
         return self.__blacklisted_exceptions
 
     def __repr__(self) -> str:
@@ -373,8 +381,11 @@ cdef class LogWrap(class_decorator.BaseDecorator):
         void _make_done_record(self, logger: logging.Logger, str func_name, result: typing.Any) except *:
             """Construct success record.
 
+            :param logger: logger instance to use
             :type logger: logging.Logger
+            :param func_name: function name
             :type func_name: str
+            :param result: function execution result
             :type result: typing.Any
             """
             cdef:
@@ -396,9 +407,13 @@ cdef class LogWrap(class_decorator.BaseDecorator):
         void _make_calling_record(self, logger: logging.Logger, str name, str arguments, str method="Calling") except *:
             """Make log record before execution.
 
+            :param logger: logger instance to use
             :type logger: logging.Logger
+            :param name: function name
             :type name: str
+            :param arguments: function arguments repr
             :type arguments: str
+            :param method: "calling" or "awaiting"
             :type method: str
             """
             logger.log(
@@ -409,9 +424,13 @@ cdef class LogWrap(class_decorator.BaseDecorator):
         void _make_exc_record(self, logger: logging.Logger, str name, str arguments, Exception exception) except *:
             """Make log record if exception raised.
 
+            :param logger: logger instance to use
             :type logger: logging.Logger
+            :param name: function name
             :type name: str
+            :param arguments: function arguments repr
             :type arguments: str
+            :param exception: exception captured
             :type exception: Exception
             """
             exc_info = sys.exc_info()

logwrap/repr_utils.py

@@ -126,7 +126,7 @@ def kind(self) -> int:
         return self.parameter.kind  # type: ignore
 
     # noinspection PyTypeChecker
-    def __hash__(self) -> typing.NoReturn:  # pragma: no cover
+    def __hash__(self) -> typing.NoReturn:
         """Block hashing.
 
         :raises TypeError: Not hashable.
@@ -192,6 +192,7 @@ def __init__(self, max_indent: int = 20, indent_step: int = 4) -> None:
     def max_indent(self) -> int:
         """Max indent getter.
 
+        :return: maximal indent before switch to normal repr
         :rtype: int
         """
         return self.__max_indent
@@ -200,6 +201,7 @@ def max_indent(self) -> int:
     def indent_step(self) -> int:
         """Indent step getter.
 
+        :return: indent step for nested definitions
         :rtype: int
         """
         return self.__indent_step
@@ -323,6 +325,7 @@ def _repr_iterable_items(self, src: typing.Iterable[typing.Any], indent: int = 0
     def _magic_method_name(self) -> str:
         """Magic method name.
 
+        :return: magic method name to lookup in processing objects
         :rtype: str
         """
 
@@ -398,6 +401,7 @@ class PrettyRepr(PrettyFormat):
     def _magic_method_name(self) -> str:
         """Magic method name.
 
+        :return: magic method name to lookup in processing objects
         :rtype: str
         """
         return "__pretty_repr__"