decorator¶

Decorators for Alfred workflow Script Filter functions.

afwf.decorator.log_error(log_file: str | Path | None = None, tb_limit: int | None = None, max_bytes: int = 500000, backup_count: int = 2)[source]¶

Decorator factory that logs exception tracebacks to a rotating file.

On success, the wrapped function behaves identically to the original. On error, the traceback is appended to log_file, then re-raised.

The logger is created lazily — zero file I/O on the happy path. RotatingFileHandler handles both rotation and thread safety.

Parameters:

log_file – Path to the log file. ~ is expanded. Parent directories are created automatically. Defaults to ~/.alfred-afwf/error.log.
tb_limit – Maximum number of stack frames. None = full traceback.
max_bytes – Rotate the file when it exceeds this size in bytes. Defaults to 500 000 (≈ 500 KB).
backup_count – Number of rotated backup files to keep. Defaults to 2 (i.e. error.log, error.log.1, error.log.2).

Usage:

import afwf.api as afwf

@afwf.log_error()
def main(query: str) -> afwf.ScriptFilter:
    ...

@afwf.log_error(log_file="~/.alfred-afwf/search_bookmarks.log", max_bytes=200_000)
def main(query: str) -> afwf.ScriptFilter:
    ...