Lists the existing groups.

        Example:
            >>> from google.cloud import monitoring_v3
            >>>
            >>> client = monitoring_v3.GroupServiceClient()
            >>>
            >>> name = client.project_path('[PROJECT]')
            >>>
            >>> # Iterate over all results
            >>> for element in client.list_groups(name):
            ...     # process element
            ...     pass
            >>>
            >>>
            >>> # Alternatively:
            >>>
            >>> # Iterate over results one page at a time
            >>> for page in client.list_groups(name).pages:
            ...     for element in page:
            ...         # process element
            ...         pass

        Args:
            name (str): The project whose groups are to be listed. The format is
                ``"projects/{project_id_or_number}"``.
            children_of_group (str): A group name: ``"projects/{project_id_or_number}/groups/{group_id}"``.
                Returns groups whose ``parentName`` field contains the group name. If no
                groups have this parent, the results are empty.
            ancestors_of_group (str): A group name: ``"projects/{project_id_or_number}/groups/{group_id}"``.
                Returns groups that are ancestors of the specified group. The groups are
                returned in order, starting with the immediate parent and ending with
                the most distant ancestor. If the specified group has no immediate
                parent, the results are empty.
            descendants_of_group (str): A group name: ``"projects/{project_id_or_number}/groups/{group_id}"``.
                Returns the descendants of the specified group. This is a superset of
                the results returned by the ``childrenOfGroup`` filter, and includes
                children-of-children, and so forth.
            page_size (int): The maximum number of resources contained in the
                underlying API response. If page streaming is performed per-
                resource, this parameter does not affect the return value. If page
                streaming is performed per-page, this determines the maximum number
                of resources in a page.
            retry (Optional[google.api_core.retry.Retry]):  A retry object used
                to retry requests. If ``None`` is specified, requests will not
                be retried.
            timeout (Optional[float]): The amount of time, in seconds, to wait
                for the request to complete. Note that if ``retry`` is
                specified, the timeout applies to each individual attempt.
            metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata
                that is provided to the method.

        Returns:
            A :class:`~google.gax.PageIterator` instance. By default, this
            is an iterable of :class:`~google.cloud.monitoring_v3.types.Group` instances.
            This object can also be configured to iterate over the pages
            of the response through the `options` parameter.

        Raises:
            google.api_core.exceptions.GoogleAPICallError: If the request
                    failed for any reason.
            google.api_core.exceptions.RetryError: If the request failed due
                    to a retryable error and retry attempts failed.
            ValueError: If the parameters are invalid.

def list_groups(
        self,
        name,
        children_of_group=None,
        ancestors_of_group=None,
        descendants_of_group=None,
        page_size=None,
        retry=google.api_core.gapic_v1.method.DEFAULT,
        timeout=google.api_core.gapic_v1.method.DEFAULT,
        metadata=None,
    ):
        """
        Lists the existing groups.

        Example:
            >>> from google.cloud import monitoring_v3
            >>>
            >>> client = monitoring_v3.GroupServiceClient()
            >>>
            >>> name = client.project_path('[PROJECT]')
            >>>
            >>> # Iterate over all results
            >>> for element in client.list_groups(name):
            ...     # process element
            ...     pass
            >>>
            >>>
            >>> # Alternatively:
            >>>
            >>> # Iterate over results one page at a time
            >>> for page in client.list_groups(name).pages:
            ...     for element in page:
            ...         # process element
            ...         pass

        Args:
            name (str): The project whose groups are to be listed. The format is
                ``"projects/{project_id_or_number}"``.
            children_of_group (str): A group name: ``"projects/{project_id_or_number}/groups/{group_id}"``.
                Returns groups whose ``parentName`` field contains the group name. If no
                groups have this parent, the results are empty.
            ancestors_of_group (str): A group name: ``"projects/{project_id_or_number}/groups/{group_id}"``.
                Returns groups that are ancestors of the specified group. The groups are
                returned in order, starting with the immediate parent and ending with
                the most distant ancestor. If the specified group has no immediate
                parent, the results are empty.
            descendants_of_group (str): A group name: ``"projects/{project_id_or_number}/groups/{group_id}"``.
                Returns the descendants of the specified group. This is a superset of
                the results returned by the ``childrenOfGroup`` filter, and includes
                children-of-children, and so forth.
            page_size (int): The maximum number of resources contained in the
                underlying API response. If page streaming is performed per-
                resource, this parameter does not affect the return value. If page
                streaming is performed per-page, this determines the maximum number
                of resources in a page.
            retry (Optional[google.api_core.retry.Retry]):  A retry object used
                to retry requests. If ``None`` is specified, requests will not
                be retried.
            timeout (Optional[float]): The amount of time, in seconds, to wait
                for the request to complete. Note that if ``retry`` is
                specified, the timeout applies to each individual attempt.
            metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata
                that is provided to the method.

        Returns:
            A :class:`~google.gax.PageIterator` instance. By default, this
            is an iterable of :class:`~google.cloud.monitoring_v3.types.Group` instances.
            This object can also be configured to iterate over the pages
            of the response through the `options` parameter.

        Raises:
            google.api_core.exceptions.GoogleAPICallError: If the request
                    failed for any reason.
            google.api_core.exceptions.RetryError: If the request failed due
                    to a retryable error and retry attempts failed.
            ValueError: If the parameters are invalid.
        """
        if metadata is None:
            metadata = []
        metadata = list(metadata)
        # Wrap the transport method to add retry and timeout logic.
        if "list_groups" not in self._inner_api_calls:
            self._inner_api_calls[
                "list_groups"
            ] = google.api_core.gapic_v1.method.wrap_method(
                self.transport.list_groups,
                default_retry=self._method_configs["ListGroups"].retry,
                default_timeout=self._method_configs["ListGroups"].timeout,
                client_info=self._client_info,
            )

        # Sanity check: We have some fields which are mutually exclusive;
        # raise ValueError if more than one is sent.
        google.api_core.protobuf_helpers.check_oneof(
            children_of_group=children_of_group,
            ancestors_of_group=ancestors_of_group,
            descendants_of_group=descendants_of_group,
        )

        request = group_service_pb2.ListGroupsRequest(
            name=name,
            children_of_group=children_of_group,
            ancestors_of_group=ancestors_of_group,
            descendants_of_group=descendants_of_group,
            page_size=page_size,
        )
        if metadata is None:
            metadata = []
        metadata = list(metadata)
        try:
            routing_header = [("name", name)]
        except AttributeError:
            pass
        else:
            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
                routing_header
            )
            metadata.append(routing_metadata)

        iterator = google.api_core.page_iterator.GRPCIterator(
            client=None,
            method=functools.partial(
                self._inner_api_calls["list_groups"],
                retry=retry,
                timeout=timeout,
                metadata=metadata,
            ),
            request=request,
            items_field="group",
            request_token_field="page_token",
            response_token_field="next_page_token",
        )
        return iterator