esptest.common.decorators module

esptest.common.decorators.enhance_import_error_message(message)

Decorator that enriches ImportError with function name and custom message.

When the decorated function raises an ImportError, the exception message is appended with `` from {func.__name__}: {message}`` to aid fixing.

Parameters:

message (str) – Extra hint to append to the ImportError message.

Returns:

A decorator for the target function.

Return type:

t.Callable[[GenericFunc], GenericFunc]

esptest.common.decorators.retry(max_retry=3, on_result=<function <lambda>>, on_exception=(<class 'esptest.common.decorators._NotUsedException'>, ), delay=0)

Retry decorator

The decorated function is called at most max_retry times. A retry happens when: - The return value fails the on_result check (if configured), or - An exception matching on_exception is raised (if configured).

on_result controls retry based on return value. It can be: - list: Retry when the return value is not in the list; stop and return when it is in the list. - callable: Retry when the callable returns True (result unacceptable); stop and return when it returns False. Default is a callable that always returns False, so no retry based on result.

on_exception limits which exceptions trigger a retry. Only exceptions whose type is in this tuple are caught and cause a retry; others are re-raised. Default uses an internal sentinel so no retry on exception.

Parameters:

• max_retry (int) – Maximum number of total calls. Defaults to 3.

• on_result (List[Any] | Callable[[Any], bool]) – Retry based on return value, see description above. Default: no retry on result.

• on_exception (Tuple[Type[Exception], ...]) – Retry when one of these exceptions is raised. Default: no exception handled.

• delay (float) – Delay before next retry. Defaults to 0.

Returns:

A decorator for the target function.

Return type:

t.Callable[[GenericFunc], GenericFunc]

esptest.common.decorators.deprecated(reason='')

Show deprecated message when method is called

Parameters:

reason (str)

Return type:

Callable[[GenericFunc], GenericFunc]

esptest.common.decorators.suppress_stdout()

Redirect stdout and stderr to discard output during the decorated function’s execution.

Note

contextlib.redirect_stdout/stderr swap the process-global sys.stdout/ sys.stderr. If the decorated function runs in multiple threads at once (e.g. detecting several ports concurrently via asyncio.to_thread), the threads would clobber each other’s redirection and restore the wrong stream. _stdout_lock prevents this corruption, but as a side effect it serializes all concurrent calls of the decorated function, so they gain no parallelism. If true concurrency is needed, replace the global redirect with a per-thread stdout interception instead of this lock.

Return type:

Callable[[GenericFunc], GenericFunc]

esptest.common.decorators.timeit(print_func=<bound method Logger.critical of <Logger esptest.basic (WARNING)>>, format_str='Func {func_name} time used: {time_used:.2f} s')

Show time used after method is called.

After the function returns, print_func is called with the formatted string (supports {func_name} and {time_used} placeholders).

Parameters:

• callable[[str] (print_func) – Callable to output the timing message. Defaults to logger.critical.

• None] – Callable to output the timing message. Defaults to logger.critical.

• str (format_str) – Format string for the message. Defaults to ‘Func {func_name} time used: {time_used:.2f} s’.

• print_func (Callable[[str], None])

• format_str (str)

Returns:

A decorator for the target function.

Return type:

t.Callable[[GenericFunc], GenericFunc]