Source code for cement.core.output

"""Cement core output module."""

from abc import abstractmethod
from typing import Any

from ..core.handler import Handler
from ..core.interface import Interface
from ..utils.misc import minimal_logger

LOG = minimal_logger(__name__)




class OutputInterface(Interface):

    """
    This class defines the Output Interface.  Handlers that implement this
    interface must provide the methods and attributes defined below. In
    general, most implementations should sub-class from the provided
    :class:`OutputHandler` base class as a starting point.
    """



    class Meta(Interface.Meta):

        """Handler meta-data."""

        #: The string identifier of the interface
        interface = 'output'


    # D-09: render data is user-arbitrary (apps render dicts of any shape);
    # the *args/**kwargs are passthrough to mix output handlers with
    # different feature sets per the docstring. Public OutputInterface (D-12).


    @abstractmethod
    def render(self, data: dict[str, Any], *args: Any, **kwargs: Any) -> str | None:
        """
        Render the ``data`` dict into output in some fashion.  This function
        must accept both ``*args`` and ``**kwargs`` to allow an application to
        mix output handlers that support different features.

        Args:
            data (dict): The dictionary whose data we need to render into
                output.

        Returns:
            str, None: The rendered output string, or ``None`` if no output is
            rendered

        """
        pass  # pragma: nocover  # abstract method






class OutputHandler(OutputInterface, Handler):

    """Output handler implementation."""



    class Meta(Handler.Meta):
        pass  # pragma: nocover  # abstract method