def controlled(
        self,
        num_controls: int | None = None,
        control_values: cv.AbstractControlValues | Sequence[int | Collection[int]] | None = None,
        control_qid_shape: tuple[int, ...] | None = None,
    ) -> Gate:
        """Returns a controlled version of this gate. If no arguments are
        specified, defaults to a single qubit control.

        Args:
            num_controls: Total number of control qubits.
            control_values: Which control computational basis state to apply the
                sub gate.  A sequence of length `num_controls` where each
                entry is an integer (or set of integers) corresponding to the
                computational basis state (or set of possible values) where that
                control is enabled.  When all controls are enabled, the sub gate is
                applied.  If unspecified, control values default to 1.
            control_qid_shape: The qid shape of the controls.  A tuple of the
                expected dimension of each control qid.  Defaults to
                `(2,) * num_controls`.  Specify this argument when using qudits.

        Returns:
            A `cirq.Gate` representing `self` controlled by the given control values
                and qubits. This is a `cirq.ControlledGate` in the base
                implementation, but subclasses may return a different gate type.
        """

        if num_controls == 0:
            return self
        return ops.controlled_gate.ControlledGate(
            self,
            num_controls=num_controls,
            control_values=control_values,
            control_qid_shape=control_qid_shape,
        )
Returns a controlled version of this gate. If no arguments are
        specified, defaults to a single qubit control.

        Args:
            num_controls: Total number of control qubits.
            control_values: Which control computational basis state to apply the
                sub gate.  A sequence of length `num_controls` where each
                entry is an integer (or set of integers) corresponding to the
                computational basis state (or set of possible values) where that
                control is enabled.  When all controls are enabled, the sub gate is
                applied.  If unspecified, control values default to 1.
            control_qid_shape: The qid shape of the controls.  A tuple of the
                expected dimension of each control qid.  Defaults to
                `(2,) * num_controls`.  Specify this argument when using qudits.

        Returns:
            A `cirq.Gate` representing `self` controlled by the given control values
                and qubits. This is a `cirq.ControlledGate` in the base
                implementation, but subclasses may return a different gate type.
        
cirq-core/cirq/ops/raw_types.py