logger ¤

def trace(logger: logging.Logger, message: str, *args: Any, **kwargs: Any) -> None:
    """
    TRACE level logger.

    To display TRACE logs, set the logging level to 5.

    Example:
    ```py
    LOGGING = {
        "version": 1,
        "disable_existing_loggers": False,
        "handlers": {
            "console": {
                "class": "logging.StreamHandler",
                "stream": sys.stdout,
            },
        },
        "loggers": {
            "django_components": {
                "level": 5,
                "handlers": ["console"],
            },
        },
    }
    ```
    """
    if actual_trace_level_num == -1:
        setup_logging()
    if logger.isEnabledFor(actual_trace_level_num):
        logger.log(actual_trace_level_num, message, *args, **kwargs)

def trace_msg(
    action: Literal["PARSE", "ASSOC", "RENDR", "GET", "SET"],
    node_type: Literal["COMP", "FILL", "SLOT", "PROVIDE", "N/A"],
    node_name: str,
    node_id: str,
    msg: str = "",
    component_id: Optional[str] = None,
) -> None:
    """
    TRACE level logger with opinionated format for tracing interaction of components,
    nodes, and slots. Formats messages like so:

    `"ASSOC SLOT test_slot ID 0088 TO COMP 0087"`
    """
    msg_prefix = ""
    if action == "ASSOC":
        if not component_id:
            raise ValueError("component_id must be set for the ASSOC action")
        msg_prefix = f"TO COMP {component_id}"
    elif action == "RENDR" and node_type == "FILL":
        if not component_id:
            raise ValueError("component_id must be set for the RENDER action")
        msg_prefix = f"FOR COMP {component_id}"

    msg_parts = [f"{action} {node_type} {node_name} ID {node_id}", *([msg_prefix] if msg_prefix else []), msg]
    full_msg = " ".join(msg_parts)

    # NOTE: When debugging tests during development, it may be easier to change
    # this to `print()`
    trace(logger, full_msg)