def transformer(cls_or_func: Any = None, *, add_deep_support: bool = False) -> Any:
    """Decorator to verify API and append logging functionality to transformer functions & classes.

    A transformer is a callable that takes as inputs a `cirq.AbstractCircuit` and
    `cirq.TransformerContext`, and returns another `cirq.AbstractCircuit` without
    modifying the input circuit. A transformer could be a function, for example:

    >>> @cirq.transformer
    ... def convert_to_cz(
    ...    circuit: cirq.AbstractCircuit, *, context: cirq.TransformerContext | None = None
    ... ) -> cirq.Circuit:
    ...    ...

    Or it could be a class that implements `__call__` with the same API, for example:

    >>> @cirq.transformer
    ... class ConvertToSqrtISwaps:
    ...    def __init__(self):
    ...        ...
    ...    def __call__(
    ...        self,
    ...        circuit: cirq.AbstractCircuit,
    ...        *,
    ...        context: cirq.TransformerContext | None = None,
    ...    ) -> cirq.Circuit:
    ...        ...

    Note that transformers which take additional parameters as `**kwargs`, with default values
    specified for each keyword argument, are also supported. For example:

    >>> @cirq.transformer
    ... def convert_to_sqrt_iswap(
    ...     circuit: cirq.AbstractCircuit,
    ...     *,
    ...     context: cirq.TransformerContext | None = None,
    ...     atol: float = 1e-8,
    ...     sqrt_iswap_gate: cirq.ISwapPowGate = cirq.SQRT_ISWAP_INV,
    ...     cleanup_operations: bool = True,
    ... ) -> cirq.Circuit:
    ...     pass

    Args:
        cls_or_func: The callable class or function to be decorated.
        add_deep_support: If True, the decorator adds the logic to first apply the
            decorated transformer on subcircuits wrapped inside `cirq.CircuitOperation`s
            before applying it on the top-level circuit, if context.deep is True.

    Returns:
        Decorated class / function which includes additional logging boilerplate.
    """

    # If keyword arguments were specified, python invokes the decorator method
    # without a `cls` argument, then passes `cls` into the result.
    if cls_or_func is None:
        return lambda deferred_cls_or_func: transformer(
            deferred_cls_or_func, add_deep_support=add_deep_support
        )

    if isinstance(cls_or_func, type):
        cls = cls_or_func
        method = cls.__call__
        default_context = _get_default_context(method)

        @functools.wraps(method)
        def method_with_logging(
            self, circuit: cirq.AbstractCircuit, **kwargs
        ) -> cirq.AbstractCircuit:
            return _transform_and_log(
                add_deep_support,
                lambda circuit, **kwargs: method(self, circuit, **kwargs),
                cls.__name__,
                circuit,
                kwargs.get('context', default_context),
                **kwargs,
            )

        setattr(cls, '__call__', method_with_logging)
        return cls
    else:
        assert callable(cls_or_func)
        func = cls_or_func
        default_context = _get_default_context(func)

        @functools.wraps(func)
        def func_with_logging(circuit: cirq.AbstractCircuit, **kwargs) -> cirq.AbstractCircuit:
            return _transform_and_log(
                add_deep_support,
                func,
                func.__name__,
                circuit,
                kwargs.get('context', default_context),
                **kwargs,
            )

        return func_with_logging
Decorator to verify API and append logging functionality to transformer functions & classes.

    A transformer is a callable that takes as inputs a `cirq.AbstractCircuit` and
    `cirq.TransformerContext`, and returns another `cirq.AbstractCircuit` without
    modifying the input circuit. A transformer could be a function, for example:

    >>> @cirq.transformer
    ... def convert_to_cz(
    ...    circuit: cirq.AbstractCircuit, *, context: cirq.TransformerContext | None = None
    ... ) -> cirq.Circuit:
    ...    ...

    Or it could be a class that implements `__call__` with the same API, for example:

    >>> @cirq.transformer
    ... class ConvertToSqrtISwaps:
    ...    def __init__(self):
    ...        ...
    ...    def __call__(
    ...        self,
    ...        circuit: cirq.AbstractCircuit,
    ...        *,
    ...        context: cirq.TransformerContext | None = None,
    ...    ) -> cirq.Circuit:
    ...        ...

    Note that transformers which take additional parameters as `**kwargs`, with default values
    specified for each keyword argument, are also supported. For example:

    >>> @cirq.transformer
    ... def convert_to_sqrt_iswap(
    ...     circuit: cirq.AbstractCircuit,
    ...     *,
    ...     context: cirq.TransformerContext | None = None,
    ...     atol: float = 1e-8,
    ...     sqrt_iswap_gate: cirq.ISwapPowGate = cirq.SQRT_ISWAP_INV,
    ...     cleanup_operations: bool = True,
    ... ) -> cirq.Circuit:
    ...     pass

    Args:
        cls_or_func: The callable class or function to be decorated.
        add_deep_support: If True, the decorator adds the logic to first apply the
            decorated transformer on subcircuits wrapped inside `cirq.CircuitOperation`s
            before applying it on the top-level circuit, if context.deep is True.

    Returns:
        Decorated class / function which includes additional logging boilerplate.
    
cirq-core/cirq/transformers/transformer_api.py