"""Shared helpers for deterministic resource cleanup."""

from loguru import logger


def safe_close(
    resource,
    name: str = "resource",
    *,
    allow_none: bool = False,
    closing_optional: bool = False,
):
    """Close a resource, logging a warning on failure. Never raises.

    Args:
        resource: The resource to close.
        name: Human-readable label for log messages.
        allow_none: If True, silently skip None resources. If False (default),
            log a warning — the caller likely failed to initialize it.
        closing_optional: If True, silently skip resources without a close()
            method. If False (default), log a warning — the caller likely
            passed the wrong object.
    """
    if resource is None:
        if not allow_none:
            logger.warning(f"Resource {name!r} is None — nothing to close")
        return
    if not hasattr(resource, "close"):
        if not closing_optional:
            logger.warning(
                f"Resource {name!r} ({type(resource).__name__}) has no close() method"
            )
        return
    try:
        resource.close()
    except Exception:
        logger.warning(f"Failed to close {name}")
