max_iter parameter (#80)

* max_iter parameter

* lil cleanup

* Agree with @penguinolog suggestions

* Update logwrap/repr_utils.py

fix static check

* Apply suggestions from code review

Co-authored-by: Alexey Stepanov <[email protected]>

---------

Co-authored-by: Alexey Stepanov <[email protected]>

Author: vadim0x60

README.rst

@@ -70,7 +70,8 @@ Argumented usage with arguments from signature:
         log=None,  # if not set: try to find LOGGER, LOG, logger or log object in target module and use it if it logger instance. Fallback: logger named logwrap
         log_level=logging.DEBUG,
         exc_level=logging.ERROR,
-        max_indent=20,  # forwarded to the pretty_repr
+        max_indent=20,  # forwarded to the pretty_repr,
+        max_iter=0,  # forwarded to the pretty_repr, max number of items in the Iterable before ellipsis. Unlimited if 0.
         blacklisted_names=None,  # list argument names, which should be dropped from log
         blacklisted_exceptions=None,  # Exceptions to skip details in log (no traceback, no exception details - just class name)
         log_call_args=True,  # Log call arguments before call

doc/source/logwrap.rst

@@ -12,7 +12,7 @@ API: Decorators: `LogWrap` class and `logwrap` function.
 
     .. versionadded:: 2.2.0
 
-    .. py:method:: __init__(*, log=None, log_level=logging.DEBUG, exc_level=logging.ERROR, max_indent=20, blacklisted_names=None, blacklisted_exceptions=None, log_call_args=True, log_call_args_on_exc=True, log_traceback=True, log_result_obj=True, )
+    .. py:method:: __init__(*, log=None, log_level=logging.DEBUG, exc_level=logging.ERROR, max_indent=20, max_iter=0, blacklisted_names=None, blacklisted_exceptions=None, log_call_args=True, log_call_args_on_exc=True, log_traceback=True, log_result_obj=True, )
 
         :param log: logger object for decorator, by default trying to use logger from target module. Fallback: 'logwrap'
         :type log: logging.Logger | None
@@ -22,6 +22,8 @@ API: Decorators: `LogWrap` class and `logwrap` function.
         :type exc_level: int
         :param max_indent: maximum indent before classic `repr()` call.
         :type max_indent: int
+        :param max_iter: maximum number of elements to log from iterable
+        :type max_iter: int
         :param blacklisted_names: Blacklisted argument names.
                                   Arguments with this names will be skipped in log.
         :type blacklisted_names: Iterable[str] | None
@@ -44,6 +46,7 @@ API: Decorators: `LogWrap` class and `logwrap` function.
         .. versionchanged:: 5.1.0 log_traceback parameter
         .. versionchanged:: 8.0.0 pick up logger from target module if possible
         .. versionchanged:: 9.0.0 Only LogWrap instance act as decorator
+        .. versionchanged:: 12.0.0 max_iter parameter
 
     .. py:method:: pre_process_param(self, arg)
 
@@ -79,6 +82,7 @@ API: Decorators: `LogWrap` class and `logwrap` function.
     .. py:attribute:: log_level
     .. py:attribute:: exc_level
     .. py:attribute:: max_indent
+    .. py:attribute:: max_iter
     .. py:attribute:: blacklisted_names
 
         ``list[str]``, modified via mutability
@@ -98,7 +102,7 @@ API: Decorators: `LogWrap` class and `logwrap` function.
         :rtype: Callable | Awaitable
 
 
-.. py:function:: logwrap(func=None, *, log=None, log_level=logging.DEBUG, exc_level=logging.ERROR, max_indent=20, blacklisted_names=None, blacklisted_exceptions=None, log_call_args=True, log_call_args_on_exc=True, log_traceback=True, log_result_obj=True, )
+.. py:function:: logwrap(func=None, *, log=None, log_level=logging.DEBUG, exc_level=logging.ERROR, max_indent=20, max_iter=0, blacklisted_names=None, blacklisted_exceptions=None, log_call_args=True, log_call_args_on_exc=True, log_traceback=True, log_result_obj=True, )
 
     Log function calls and return values.
 
@@ -112,6 +116,8 @@ API: Decorators: `LogWrap` class and `logwrap` function.
     :type exc_level: int
     :param max_indent: maximum indent before classic `repr()` call.
     :type max_indent: int
+    :param max_iter: maximum number of elements to log from iterable
+    :type max_iter: int
     :param blacklisted_names: Blacklisted argument names. Arguments with this names will be skipped in log.
     :type blacklisted_names: Iterable[str] | None
     :param blacklisted_exceptions: list of exceptions, which should be re-raised
@@ -134,6 +140,7 @@ API: Decorators: `LogWrap` class and `logwrap` function.
     .. versionchanged:: 5.1.0 log_traceback parameter
     .. versionchanged:: 8.0.0 pick up logger from target module if possible
     .. versionchanged:: 9.0.0 Only LogWrap instance act as decorator
+    .. versionchanged:: 12.0.0 max_iter parameter
 
 
 .. py:class:: BoundParameter(inspect.Parameter)

logwrap/log_on_access.py

@@ -172,6 +172,7 @@ def __init__(
         log_traceback: bool = True,
         override_name: str | None = None,
         max_indent: int = 20,
+        max_iter: int = 0,
     ) -> None:
         """Advanced property main entry point.
 
@@ -203,6 +204,8 @@ def __init__(
         :type override_name: str | None
         :param max_indent: maximal indent before classic repr() call
         :type max_indent: int
+        :param max_iter: maximal number of items to display in iterables
+        :type max_iter: int
         """
         super().__init__(fget=fget, fset=fset, fdel=fdel, doc=doc)
 
@@ -220,6 +223,7 @@ def __init__(
         self.__log_traceback: bool = log_traceback
         self.__override_name: str | None = override_name
         self.__max_indent: int = max_indent
+        self.__max_iter: int = max_iter
         self.__name: str = ""
         self.__owner: type[_OwnerT] | None = None
 
@@ -270,7 +274,7 @@ def __get_obj_source(self, instance: _OwnerT, owner: type[_OwnerT] | None = None
         :rtype: str
         """
         if self.log_object_repr:
-            return repr_utils.pretty_repr(instance, max_indent=self.max_indent)
+            return repr_utils.pretty_repr(instance, max_indent=self.max_indent, max_iter=self.max_iter)
         if owner is not None:
             return f"<{owner.__name__}() at 0x{id(instance):X}>"
         if self.__objclass__ is not None:
@@ -623,6 +627,24 @@ def max_indent(self, value: int) -> None:
         """
         self.__max_indent = value
 
+    @property
+    def max_iter(self) -> int:
+        """Max number of items in iterables during repr.
+
+        :return: maximum iter before classic `repr()` call.
+        :rtype: int
+        """
+        return self.__max_iter
+
+    @max_iter.setter
+    def max_iter(self, value: int) -> None:
+        """Max number of items in iterables during repr.
+
+        :param value: maximum iter before classic `repr()` call.
+        :type value: int
+        """
+        self.__max_iter = value
+
     @property
     def __name__(self) -> str:  # noqa: A003,PLW3201,RUF100
         """Name getter.

logwrap/log_wrap.py

@@ -186,6 +186,7 @@ class LogWrap:
         "__log_traceback",
         "__logger",
         "__max_indent",
+        "__max_iter",
     )
 
     def __init__(
@@ -194,6 +195,7 @@ def __init__(
         log_level: int = DEBUG,
         exc_level: int = ERROR,
         max_indent: int = 20,
+        max_iter: int = 0,
         blacklisted_names: Iterable[str] | None = None,
         blacklisted_exceptions: Iterable[type[Exception]] | None = None,
         log_call_args: bool = True,
@@ -211,6 +213,8 @@ def __init__(
         :type exc_level: int
         :param max_indent: maximum indent before classic `repr()` call.
         :type max_indent: int
+        :param max_iter: maximum number of elements in iterable before ellipsis.
+        :type max_iter: int
         :param blacklisted_names: Blacklisted argument names. Arguments with this names will be skipped in log.
         :type blacklisted_names: Iterable[str] | None
         :param blacklisted_exceptions: list of exception, which should be re-raised
@@ -229,6 +233,7 @@ def __init__(
         .. versionchanged:: 5.1.0 log_traceback parameter
         .. versionchanged:: 8.0.0 pick up logger from target module if possible
         .. versionchanged:: 9.0.0 Only LogWrap instance act as decorator
+        .. versionchanged:: 12.0.0 max_iter parameter
         """
         # Typing fix:
         if blacklisted_names is None:
@@ -248,6 +253,7 @@ def __init__(
         self.__log_level: int = log_level
         self.__exc_level: int = exc_level
         self.__max_indent: int = max_indent
+        self.__max_iter: int = max_iter
         self.__log_call_args: bool = log_call_args
         self.__log_call_args_on_exc: bool = log_call_args_on_exc
         self.__log_traceback: bool = log_traceback
@@ -336,6 +342,27 @@ def max_indent(self, val: int) -> None:
             raise TypeError(f"Unexpected type: {val.__class__.__name__}. Should be {int.__name__}.")
         self.__max_indent = val
 
+    @property
+    def max_iter(self) -> int:
+        """Maximum number of elements in iterable before ellipsis.
+
+        :return: maximum number of elements in iterable before ellipsis
+        :rtype: int
+        """
+        return self.__max_iter
+
+    @max_iter.setter
+    def max_iter(self, val: int) -> None:
+        """Maximum number of elements in iterable before ellipsis.
+
+        :param val: maximum number of elements in iterable before ellipsis
+        :type val: int
+        :raises TypeError: max_iter is not integer
+        """
+        if not isinstance(val, int):
+            raise TypeError(f"Unexpected type: {val.__class__.__name__}. Should be {int.__name__}.")
+        self.__max_iter = val
+
     @property
     def blacklisted_names(self) -> list[str]:
         """List of arguments names to ignore in log.
@@ -459,6 +486,7 @@ def __repr__(self) -> str:
             f"log_level={self.log_level}, "
             f"exc_level={self.exc_level}, "
             f"max_indent={self.max_indent}, "
+            f"max_iter={self.max_iter}, "
             f"blacklisted_names={self.blacklisted_names}, "
             f"blacklisted_exceptions={self.blacklisted_exceptions}, "
             f"log_call_args={self.log_call_args}, "
@@ -519,6 +547,7 @@ def _safe_val_repr(self, value: Any) -> str:
                 indent=INDENT,
                 no_indent_start=True,
                 max_indent=self.max_indent,
+                max_iter=self.max_iter,
             )
         except Exception as exc:
             base_name: str = getattr(value, "name", getattr(value, "__name__", value.__class__.__name__))
@@ -610,7 +639,9 @@ def _make_done_record(
         msg: str = f"Done: {func_name!r}"
 
         if self.log_result_obj:
-            msg += f" with result:\n{repr_utils.pretty_repr(result, max_indent=self.max_indent)}"
+            msg += (
+                f" with result:\n{repr_utils.pretty_repr(result, max_indent=self.max_indent, max_iter=self.max_iter)}"
+            )
         logger.log(level=self.log_level, msg=msg)
 
     def _make_calling_record(
@@ -743,6 +774,7 @@ def logwrap(
     log_level: int = DEBUG,
     exc_level: int = ERROR,
     max_indent: int = 20,
+    max_iter: int = 20,
     blacklisted_names: Iterable[str] | None = None,
     blacklisted_exceptions: Iterable[type[Exception]] | None = None,
     log_call_args: bool = True,
@@ -762,6 +794,7 @@ def logwrap(
     log_level: int = DEBUG,
     exc_level: int = ERROR,
     max_indent: int = 20,
+    max_iter: int = 20,
     blacklisted_names: Iterable[str] | None = None,
     blacklisted_exceptions: Iterable[type[Exception]] | None = None,
     log_call_args: bool = True,
@@ -781,6 +814,7 @@ def logwrap(
     log_level: int = DEBUG,
     exc_level: int = ERROR,
     max_indent: int = 20,
+    max_iter: int = 0,
     blacklisted_names: Iterable[str] | None = None,
     blacklisted_exceptions: Iterable[type[Exception]] | None = None,
     log_call_args: bool = True,
@@ -799,6 +833,7 @@ def logwrap(
     log_level: int = DEBUG,
     exc_level: int = ERROR,
     max_indent: int = 20,
+    max_iter: int = 0,
     blacklisted_names: Iterable[str] | None = None,
     blacklisted_exceptions: Iterable[type[Exception]] | None = None,
     log_call_args: bool = True,
@@ -818,6 +853,8 @@ def logwrap(
     :type exc_level: int
     :param max_indent: maximum indent before classic `repr()` call.
     :type max_indent: int
+    :param max_iter: maximum number of elements to log from iterables.
+    :type max_iter: int
     :param blacklisted_names: Blacklisted argument names. Arguments with this names will be skipped in log.
     :type blacklisted_names: Iterable[str] | None
     :param blacklisted_exceptions: list of exceptions, which should be re-raised
@@ -840,12 +877,14 @@ def logwrap(
     .. versionchanged:: 5.1.0 log_traceback parameter
     .. versionchanged:: 8.0.0 pick up logger from target module if possible
     .. versionchanged:: 9.0.0 Only LogWrap instance act as decorator
+    .. versionchanged:: 12.0.0 max_iter parameter
     """
     wrapper = LogWrap(
         log=log,
         log_level=log_level,
         exc_level=exc_level,
         max_indent=max_indent,
+        max_iter=max_iter,
         blacklisted_names=blacklisted_names,
         blacklisted_exceptions=blacklisted_exceptions,
         log_call_args=log_call_args,

logwrap/repr_utils.py

@@ -248,9 +248,9 @@ class PrettyFormat(abc.ABC):
     Designed for usage as __repr__ and __str__ replacement on complex objects
     """
 
-    __slots__ = ("__indent_step", "__max_indent")
+    __slots__ = ("__indent_step", "__max_indent", "__max_iter")
 
-    def __init__(self, max_indent: int = 20, indent_step: int = 4) -> None:
+    def __init__(self, max_indent: int = 20, max_iter: int = 0, indent_step: int = 4) -> None:
         """Pretty Formatter.
 
         :param max_indent: maximal indent before classic repr() call
@@ -259,6 +259,7 @@ def __init__(self, max_indent: int = 20, indent_step: int = 4) -> None:
         :type indent_step: int
         """
         self.__max_indent: int = max_indent
+        self.__max_iter: int = max_iter
         self.__indent_step: int = indent_step
 
     @property
@@ -270,6 +271,15 @@ def max_indent(self) -> int:
         """
         return self.__max_indent
 
+    @property
+    def max_iter(self) -> int:
+        """Max iterable items getter.
+
+        :return: maximal items count for iterable objects
+        :rtype: int
+        """
+        return self.__max_iter
+
     @property
     def indent_step(self) -> int:
         """Indent step getter.
@@ -556,14 +566,15 @@ def _repr_iterable_items(
         """
         next_indent: int = self.next_indent(indent)
         buf: list[str] = []
-        for elem in src:
-            buf.extend(
-                (
-                    "\n",
-                    self.process_element(src=elem, indent=next_indent),
-                    ",",
-                )
-            )
+
+        for idx, elem in enumerate(src, start=1):
+            buf.extend(("\n", self.process_element(src=elem, indent=next_indent)))
+
+            if idx == self.max_iter:
+                buf.append("...")
+                break
+
+            buf.append(",")
         return "".join(buf)
 
     def _repr_rich(
@@ -947,6 +958,7 @@ def pretty_repr(
     indent: int = 0,
     no_indent_start: bool = False,
     max_indent: int = 20,
+    max_iter: int = 0,
     indent_step: int = 4,
 ) -> str:
     """Make human readable repr of object.
@@ -959,12 +971,14 @@ def pretty_repr(
     :type no_indent_start: bool
     :param max_indent: maximal indent before classic repr() call
     :type max_indent: int
+    :param max_iter: maximal number of items to iterate
+    :type max_iter: int
     :param indent_step: step for the next indentation level
     :type indent_step: int
     :return: formatted string
     :rtype: str
     """
-    return PrettyRepr(max_indent=max_indent, indent_step=indent_step)(
+    return PrettyRepr(max_indent=max_indent, max_iter=max_iter, indent_step=indent_step)(
         src=src,
         indent=indent,
         no_indent_start=no_indent_start,
@@ -976,6 +990,7 @@ def pretty_str(
     indent: int = 0,
     no_indent_start: bool = False,
     max_indent: int = 20,
+    max_iter: int = 20,
     indent_step: int = 4,
 ) -> str:
     """Make human readable str of object.
@@ -988,11 +1003,13 @@ def pretty_str(
     :type no_indent_start: bool
     :param max_indent: maximal indent before classic repr() call
     :type max_indent: int
+    :param max_iter: maximal number of items to log in iterables
+    :type max_iter: int
     :param indent_step: step for the next indentation level
     :type indent_step: int
     :return: formatted string
     """
-    return PrettyStr(max_indent=max_indent, indent_step=indent_step)(
+    return PrettyStr(max_indent=max_indent, max_iter=max_iter, indent_step=indent_step)(
         src=src,
         indent=indent,
         no_indent_start=no_indent_start,