From 2af55db70fd787481ec379d13fe8f897fccf16f8 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 29 Mar 2016 21:45:33 -0400
Subject: [PATCH 01/61] Add gcloud.monitoring with fetching of metric
 descriptors.

---
 docs/index.rst                     |   9 ++
 docs/monitoring-client.rst         |  16 +++
 docs/monitoring-label.rst          |   7 ++
 docs/monitoring-metric.rst         |   7 ++
 gcloud/monitoring/__init__.py      |  24 ++++
 gcloud/monitoring/client.py        |  68 +++++++++++
 gcloud/monitoring/connection.py    |  47 ++++++++
 gcloud/monitoring/label.py         |  51 +++++++++
 gcloud/monitoring/metric.py        | 175 +++++++++++++++++++++++++++++
 scripts/verify_included_modules.py |   1 +
 10 files changed, 405 insertions(+)
 create mode 100644 docs/monitoring-client.rst
 create mode 100644 docs/monitoring-label.rst
 create mode 100644 docs/monitoring-metric.rst
 create mode 100644 gcloud/monitoring/__init__.py
 create mode 100644 gcloud/monitoring/client.py
 create mode 100644 gcloud/monitoring/connection.py
 create mode 100644 gcloud/monitoring/label.py
 create mode 100644 gcloud/monitoring/metric.py

diff --git a/docs/index.rst b/docs/index.rst
index a9c1094a6789..a1e402e22d98 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -119,6 +119,15 @@
   logging-metric
   logging-sink
 
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Cloud Monitoring
+
+  Client <monitoring-client>
+  monitoring-label
+  monitoring-metric
+
 .. toctree::
   :maxdepth: 0
   :hidden:
diff --git a/docs/monitoring-client.rst b/docs/monitoring-client.rst
new file mode 100644
index 000000000000..8083d39d5f4f
--- /dev/null
+++ b/docs/monitoring-client.rst
@@ -0,0 +1,16 @@
+Monitoring Client
+=================
+
+.. automodule:: gcloud.monitoring.client
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Connection
+~~~~~~~~~~
+
+.. automodule:: gcloud.monitoring.connection
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
diff --git a/docs/monitoring-label.rst b/docs/monitoring-label.rst
new file mode 100644
index 000000000000..827058c92662
--- /dev/null
+++ b/docs/monitoring-label.rst
@@ -0,0 +1,7 @@
+Label Descriptors
+=================
+
+.. automodule:: gcloud.monitoring.label
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/docs/monitoring-metric.rst b/docs/monitoring-metric.rst
new file mode 100644
index 000000000000..79e608b63932
--- /dev/null
+++ b/docs/monitoring-metric.rst
@@ -0,0 +1,7 @@
+Metric Descriptors
+==================
+
+.. automodule:: gcloud.monitoring.metric
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/gcloud/monitoring/__init__.py b/gcloud/monitoring/__init__.py
new file mode 100644
index 000000000000..20f1a1f74247
--- /dev/null
+++ b/gcloud/monitoring/__init__.py
@@ -0,0 +1,24 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Google Monitoring API wrapper."""
+
+from gcloud.monitoring.client import Client
+from gcloud.monitoring.connection import Connection
+from gcloud.monitoring.label import LabelDescriptor
+from gcloud.monitoring.metric import Metric
+from gcloud.monitoring.metric import MetricDescriptor
+
+
+SCOPE = Connection.SCOPE
diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
new file mode 100644
index 000000000000..fcbfe4c75f47
--- /dev/null
+++ b/gcloud/monitoring/client.py
@@ -0,0 +1,68 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Client for interacting with the Google Monitoring API."""
+
+from gcloud.client import JSONClient
+from gcloud.monitoring.connection import Connection
+from gcloud.monitoring.metric import MetricDescriptor
+
+
+class Client(JSONClient):
+    """Client to bundle configuration needed for API requests.
+
+    :type project: string
+    :param project: The target project. If not passed, falls back to the
+                    default inferred from the environment.
+
+    :type credentials: :class:`oauth2client.client.OAuth2Credentials` or
+                       :class:`NoneType`
+    :param credentials: The OAuth2 Credentials to use for the connection
+                        owned by this client. If not passed (and if no ``http``
+                        object is passed), falls back to the default inferred
+                        from the environment.
+
+    :type http: :class:`httplib2.Http` or class that defines ``request()``
+    :param http: An optional HTTP object to make requests. If not passed, an
+                 ``http`` object is created that is bound to the
+                 ``credentials`` for the current object.
+    """
+
+    _connection_class = Connection
+
+    def fetch_metric_descriptor(self, metric_type):
+        """Look up a metric descriptor by type.
+
+        :type metric_type: string
+        :param metric_type: The metric type name.
+
+        :rtype: :class:`~gcloud.monitoring.metric.MetricDescriptor`
+        :returns: The metric descriptor instance.
+
+        :raises: :class:`gcloud.exceptions.NotFound`
+        """
+        return MetricDescriptor._fetch(self, metric_type)
+
+    def list_metric_descriptors(self, filter=None):
+        """List all metric descriptors for the project.
+
+        :type filter: string or ``NoneType``
+        :param filter: An optional filter string describing the metric
+                       descriptors to be returned.
+
+        :rtype: list of :class:`~gcloud.monitoring.metric.MetricDescriptor`
+        :returns: A list of metric descriptor instances.
+        """
+        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
+        return MetricDescriptor._list(self, filter)
diff --git a/gcloud/monitoring/connection.py b/gcloud/monitoring/connection.py
new file mode 100644
index 000000000000..5887da62e65d
--- /dev/null
+++ b/gcloud/monitoring/connection.py
@@ -0,0 +1,47 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Create / interact with gcloud monitoring connections."""
+
+from gcloud import connection as base_connection
+
+
+class Connection(base_connection.JSONConnection):
+    """A connection to Google Monitoring via the JSON REST API.
+
+    :type credentials: :class:`oauth2client.client.OAuth2Credentials`
+    :param credentials: (Optional) The OAuth2 Credentials to use for this
+                        connection.
+
+    :type http: :class:`httplib2.Http` or class that defines ``request()``
+    :param http: (Optional) HTTP object to make requests.
+
+    :type api_base_url: string
+    :param api_base_url: The base of the API call URL. Defaults to the value
+                         :attr:`Connection.API_BASE_URL`.
+    """
+
+    API_BASE_URL = 'https://monitoring.googleapis.com'
+    """The base of the API call URL."""
+
+    API_VERSION = 'v3'
+    """The version of the API, used in building the API call's URL."""
+
+    API_URL_TEMPLATE = '{api_base_url}/{api_version}{path}'
+    """A template for the URL of a particular API call."""
+
+    SCOPE = ('https://www.googleapis.com/auth/monitoring.read',
+             'https://www.googleapis.com/auth/monitoring',
+             'https://www.googleapis.com/auth/cloud-platform')
+    """The scopes required for authenticating as a Monitoring consumer."""
diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
new file mode 100644
index 000000000000..0439abfa41e2
--- /dev/null
+++ b/gcloud/monitoring/label.py
@@ -0,0 +1,51 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Label Descriptors for the Google Monitoring API."""
+
+import collections
+
+
+class LabelDescriptor(collections.namedtuple('LabelDescriptor',
+                                             'key value_type description')):
+    """Schema specification and documentation for a single label.
+
+    :type key: string
+    :param key: The name of the label.
+
+    :type value_type: string
+    :param value_type: The type of the label. It must be one of ``"STRING"``,
+                       ``"BOOL"``, or ``"INT64"``.
+
+    :type description: string
+    :param description: A human-readable description for the label.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a label descriptor from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`LabelDescriptor`
+        :returns: A label descriptor.
+        """
+        return cls(
+            info.get('key', ''),
+            info.get('valueType', 'STRING'),
+            info.get('description', ''),
+        )
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
new file mode 100644
index 000000000000..7bb9f3e5ca72
--- /dev/null
+++ b/gcloud/monitoring/metric.py
@@ -0,0 +1,175 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Metric Descriptors for the Google Monitoring API."""
+
+# Features intentionally omitted from this first version of the client library:
+#   - Creating and deleting metric descriptors.
+
+import collections
+
+from gcloud.monitoring.label import LabelDescriptor
+
+
+class MetricDescriptor(collections.namedtuple(
+        'MetricDescriptor', ('name type labels metric_kind value_type unit'
+                             ' description display_name'))):
+    """Specification of a metric type and its schema.
+
+    Metric descriptor instances are immutable.
+
+    :type name: string
+    :param name: The "resource name" of the metric descriptor. For example:
+                 ``"projects/<project_id>/metricDescriptors/<type>"``
+
+    :type type: string
+    :param type: The metric type including a DNS name prefix. For example:
+                 ``"compute.googleapis.com/instance/cpu/utilization"``
+
+    :type labels: list of :class:`~gcloud.monitoring.label.LabelDescriptor`
+    :param labels: A sequence of label descriptors specifying the labels used
+                   to identify a specific instance of this metric.
+
+    :type metric_kind: string
+    :param metric_kind: The kind of measurement. It must be one of ``"GAUGE"``,
+                        ``"DELTA"``, or ``"CUMULATIVE"``.
+
+    :type value_type: string
+    :param value_type: The value type of the metric. It must be one of
+                       ``"BOOL"``, ``"INT64"``, ``"DOUBLE"``, ``"STRING"``,
+                       ``"DISTRIBUTION"``, or ``"MONEY"``.
+
+    :type unit: string
+    :param unit: The unit in which the metric value is reported.
+
+    :type description: string
+    :param description: A detailed description of the metric.
+
+    :type display_name: string
+    :param display_name: A concise name for the metric.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def _fetch(cls, client, metric_type):
+        """Look up a metric descriptor by type.
+
+        :type client: :class:`gcloud.monitoring.client.Client`
+        :param client: The client to use.
+
+        :type metric_type: string
+        :param metric_type: The metric type name.
+
+        :rtype: :class:`MetricDescriptor`
+        :returns: The metric descriptor instance.
+
+        :raises: :class:`gcloud.exceptions.NotFound`
+        """
+        path = '/projects/{project}/metricDescriptors/{type}'.format(
+            project=client.project,
+            type=metric_type)
+        info = client.connection.api_request('GET', path)
+        return cls._from_dict(info)
+
+    @classmethod
+    def _list(cls, client, filter=None):
+        """List all metric descriptors for the project.
+
+        :type client: :class:`gcloud.monitoring.client.Client`
+        :param client: The client to use.
+
+        :type filter: string or None
+        :param filter: An optional filter string describing the metric
+                       descriptors to be returned.
+
+        :rtype: list of :class:`MetricDescriptor`
+        :returns: A list of metric descriptor instances.
+        """
+        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
+
+        path = '/projects/{}/metricDescriptors/'.format(client.project)
+
+        def _descriptors():
+            page_token = None
+            while True:
+                params = {}
+
+                if filter is not None:
+                    params['filter'] = filter
+
+                if page_token is not None:
+                    params['pageToken'] = page_token
+
+                response = client.connection.api_request('GET', path,
+                                                         query_params=params)
+                for info in response.get('metricDescriptors', []):
+                    yield cls._from_dict(info)
+
+                page_token = response.get('nextPageToken')
+                if not page_token:
+                    break
+
+        return list(_descriptors())
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a metric descriptor from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`MetricDescriptor`
+        :returns: A metric descriptor.
+        """
+        return cls(
+            type=info.get('type', ''),
+            name=info.get('name', ''),
+            description=info.get('description', ''),
+            display_name=info.get('displayName', ''),
+            labels=tuple(LabelDescriptor._from_dict(label)
+                         for label in info.get('labels', [])),
+            metric_kind=info['metricKind'],
+            value_type=info['valueType'],
+            unit=info.get('unit', ''),
+        )
+
+
+class Metric(collections.namedtuple('Metric', 'type labels')):
+    """A specific metric identified by specifying values for all labels.
+
+    :type type: string
+    :param type: The metric type name.
+
+    :type labels: dict
+    :param labels: A mapping from label names to values for all labels
+                   enumerated in the associated :class:`MetricDescriptor`.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a metric object from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`Metric`
+        :returns: A metric object.
+        """
+        return cls(
+            type=info.get('type', ''),
+            labels=info.get('labels', {}),
+        )
diff --git a/scripts/verify_included_modules.py b/scripts/verify_included_modules.py
index 41bb658ebe23..551c81d975e7 100644
--- a/scripts/verify_included_modules.py
+++ b/scripts/verify_included_modules.py
@@ -37,6 +37,7 @@
     'gcloud.dns.__init__',
     'gcloud.iterator',
     'gcloud.logging.__init__',
+    'gcloud.monitoring.__init__',
     'gcloud.pubsub.__init__',
     'gcloud.resource_manager.__init__',
     'gcloud.search.__init__',

From a03740e080459982e55cb7d8ac50305e89d3258d Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Wed, 30 Mar 2016 17:34:45 -0400
Subject: [PATCH 02/61] Add fetching of resource descriptors.

---
 docs/index.rst                |   1 +
 docs/monitoring-resource.rst  |   7 ++
 gcloud/monitoring/__init__.py |   2 +
 gcloud/monitoring/client.py   |  29 +++++-
 gcloud/monitoring/resource.py | 160 ++++++++++++++++++++++++++++++++++
 5 files changed, 198 insertions(+), 1 deletion(-)
 create mode 100644 docs/monitoring-resource.rst
 create mode 100644 gcloud/monitoring/resource.py

diff --git a/docs/index.rst b/docs/index.rst
index a1e402e22d98..3acb2fca3e77 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -127,6 +127,7 @@
   Client <monitoring-client>
   monitoring-label
   monitoring-metric
+  monitoring-resource
 
 .. toctree::
   :maxdepth: 0
diff --git a/docs/monitoring-resource.rst b/docs/monitoring-resource.rst
new file mode 100644
index 000000000000..8f6c23d470a7
--- /dev/null
+++ b/docs/monitoring-resource.rst
@@ -0,0 +1,7 @@
+Resource Descriptors
+====================
+
+.. automodule:: gcloud.monitoring.resource
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/gcloud/monitoring/__init__.py b/gcloud/monitoring/__init__.py
index 20f1a1f74247..48e601ba0d0e 100644
--- a/gcloud/monitoring/__init__.py
+++ b/gcloud/monitoring/__init__.py
@@ -19,6 +19,8 @@
 from gcloud.monitoring.label import LabelDescriptor
 from gcloud.monitoring.metric import Metric
 from gcloud.monitoring.metric import MetricDescriptor
+from gcloud.monitoring.resource import Resource
+from gcloud.monitoring.resource import ResourceDescriptor
 
 
 SCOPE = Connection.SCOPE
diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index fcbfe4c75f47..7d1278f75173 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -17,6 +17,7 @@
 from gcloud.client import JSONClient
 from gcloud.monitoring.connection import Connection
 from gcloud.monitoring.metric import MetricDescriptor
+from gcloud.monitoring.resource import ResourceDescriptor
 
 
 class Client(JSONClient):
@@ -57,7 +58,7 @@ def fetch_metric_descriptor(self, metric_type):
     def list_metric_descriptors(self, filter=None):
         """List all metric descriptors for the project.
 
-        :type filter: string or ``NoneType``
+        :type filter: string or None
         :param filter: An optional filter string describing the metric
                        descriptors to be returned.
 
@@ -66,3 +67,29 @@ def list_metric_descriptors(self, filter=None):
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
         return MetricDescriptor._list(self, filter)
+
+    def fetch_resource_descriptor(self, resource_type):
+        """Look up a resource descriptor by type.
+
+        :type resource_type: string
+        :param resource_type: The resource type name.
+
+        :rtype: :class:`~gcloud.monitoring.resource.ResourceDescriptor`
+        :returns: The resource descriptor instance.
+
+        :raises: :class:`gcloud.exceptions.NotFound`
+        """
+        return ResourceDescriptor._fetch(self, resource_type)
+
+    def list_resource_descriptors(self, filter=None):
+        """List all resource descriptors for the project.
+
+        :type filter: string or None
+        :param filter: An optional filter string describing the resource
+                       descriptors to be returned.
+
+        :rtype: list of :class:`~gcloud.monitoring.resource.ResourceDescriptor`
+        :returns: A list of resource descriptor instances.
+        """
+        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
+        return ResourceDescriptor._list(self, filter)
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
new file mode 100644
index 000000000000..ed633bae50f1
--- /dev/null
+++ b/gcloud/monitoring/resource.py
@@ -0,0 +1,160 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Resource Descriptors for the Google Monitoring API."""
+
+import collections
+
+from gcloud.monitoring.label import LabelDescriptor
+
+
+class ResourceDescriptor(collections.namedtuple(
+        'ResourceDescriptor', ('name type display_name description labels'))):
+    """Specification of a monitored resource type and its schema.
+
+    Resource descriptor instances are immutable.
+
+    :type name: string
+    :param name:
+        The "resource name" of the monitored resource descriptor:
+        ``"projects/<project_id>/monitoredResourceDescriptors/<type>"``
+
+    :type type: string
+    :param type:
+        The monitored resource type. For example: ``"gce_instance"``
+
+    :type display_name: string
+    :param display_name:
+        A concise name that might be displayed in user interfaces.
+
+    :type description: string
+    :param description:
+        A detailed description that might be used in documentation.
+
+    :type labels: list of :class:`~gcloud.monitoring.label.LabelDescriptor`
+    :param labels:
+        A sequence of label descriptors specifying the labels used
+        to identify a specific instance of this monitored resource.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def _fetch(cls, client, resource_type):
+        """Look up a resource descriptor by type.
+
+        :type client: :class:`gcloud.monitoring.client.Client`
+        :param client: The client to use.
+
+        :type resource_type: string
+        :param resource_type: The resource type name.
+
+        :rtype: :class:`ResourceDescriptor`
+        :returns: The resource descriptor instance.
+
+        :raises: :class:`gcloud.exceptions.NotFound`
+        """
+        path = '/projects/{}/monitoredResourceDescriptors/{}'.format(
+            client.project, resource_type)
+        info = client.connection.api_request('GET', path)
+        return cls._from_dict(info)
+
+    @classmethod
+    def _list(cls, client, filter=None):
+        """List all resource descriptors for the project.
+
+        :type client: :class:`gcloud.monitoring.client.Client`
+        :param client: The client to use.
+
+        :type filter: string or None
+        :param filter: An optional filter string describing the resource
+                       descriptors to be returned.
+
+        :rtype: list of :class:`ResourceDescriptor`
+        :returns: A list of resource descriptor instances.
+        """
+        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
+
+        path = '/projects/{}/monitoredResourceDescriptors/'.format(
+            client.project)
+
+        def _descriptors():
+            page_token = None
+            while True:
+                params = {}
+
+                if filter is not None:
+                    params['filter'] = filter
+
+                if page_token is not None:
+                    params['pageToken'] = page_token
+
+                response = client.connection.api_request('GET', path,
+                                                         query_params=params)
+                for info in response.get('resourceDescriptors', []):
+                    yield cls._from_dict(info)
+
+                page_token = response.get('nextPageToken')
+                if not page_token:
+                    break
+
+        return list(_descriptors())
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a resource descriptor from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`ResourceDescriptor`
+        :returns: A resource descriptor.
+        """
+        return cls(
+            name=info.get('name', ''),
+            type=info.get('type', ''),
+            display_name=info.get('displayName', ''),
+            description=info.get('description', ''),
+            labels=tuple(LabelDescriptor._from_dict(label)
+                         for label in info.get('labels', [])),
+        )
+
+
+class Resource(collections.namedtuple('Resource', 'type labels')):
+    """A monitored resource identified by specifying values for all labels.
+
+    :type type: string
+    :param type: The resource type name.
+
+    :type labels: dict
+    :param labels: A mapping from label names to values for all labels
+                   enumerated in the associated :class:`ResourceDescriptor`.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a resource object from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`Resource`
+        :returns: A resource object.
+        """
+        return cls(
+            type=info.get('type', ''),
+            labels=info.get('labels', {}),
+        )

From 6f57e6a175dfaa27fab775e6a00d645ea2b8ef99 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 31 Mar 2016 18:01:42 -0400
Subject: [PATCH 03/61] Add querying of time series.

---
 docs/index.rst                  |   3 +-
 docs/monitoring-timeseries.rst  |   7 +
 gcloud/monitoring/__init__.py   |   3 +
 gcloud/monitoring/client.py     |  91 +++-
 gcloud/monitoring/timeseries.py | 706 ++++++++++++++++++++++++++++++++
 5 files changed, 808 insertions(+), 2 deletions(-)
 create mode 100644 docs/monitoring-timeseries.rst
 create mode 100644 gcloud/monitoring/timeseries.py

diff --git a/docs/index.rst b/docs/index.rst
index 3acb2fca3e77..cd77db13620d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -125,9 +125,10 @@
   :caption: Cloud Monitoring
 
   Client <monitoring-client>
-  monitoring-label
+  monitoring-timeseries
   monitoring-metric
   monitoring-resource
+  monitoring-label
 
 .. toctree::
   :maxdepth: 0
diff --git a/docs/monitoring-timeseries.rst b/docs/monitoring-timeseries.rst
new file mode 100644
index 000000000000..120f7280c885
--- /dev/null
+++ b/docs/monitoring-timeseries.rst
@@ -0,0 +1,7 @@
+Time Series
+===========
+
+.. automodule:: gcloud.monitoring.timeseries
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/gcloud/monitoring/__init__.py b/gcloud/monitoring/__init__.py
index 48e601ba0d0e..823c143fcd07 100644
--- a/gcloud/monitoring/__init__.py
+++ b/gcloud/monitoring/__init__.py
@@ -21,6 +21,9 @@
 from gcloud.monitoring.metric import MetricDescriptor
 from gcloud.monitoring.resource import Resource
 from gcloud.monitoring.resource import ResourceDescriptor
+from gcloud.monitoring.timeseries import Point
+from gcloud.monitoring.timeseries import TimeSeries
+from gcloud.monitoring.timeseries import Query
 
 
 SCOPE = Connection.SCOPE
diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 7d1278f75173..33062132c38f 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -12,12 +12,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Client for interacting with the Google Monitoring API."""
+"""Client for interacting with the Google Monitoring API.
+
+Example::
+
+    from gcloud import monitoring
+    client = monitoring.Client()
+    query = client.query(minutes=5)
+    print query.as_dataframe()  # Requires pandas.
+
+At present, the client supports querying of time series, metric descriptors,
+and monitored resource descriptors.
+
+See the documentation for
+`Google Monitoring API V3 <https://cloud.google.com/monitoring/api/>`_.
+"""
 
 from gcloud.client import JSONClient
 from gcloud.monitoring.connection import Connection
 from gcloud.monitoring.metric import MetricDescriptor
 from gcloud.monitoring.resource import ResourceDescriptor
+from gcloud.monitoring.timeseries import Query
 
 
 class Client(JSONClient):
@@ -42,9 +57,69 @@ class Client(JSONClient):
 
     _connection_class = Connection
 
+    def query(self,
+              metric_type=Query.DEFAULT_METRIC_TYPE,
+              resource_type=None,
+              end_time=None, start_time=None,
+              days=0, hours=0, minutes=0):
+        """Construct a query object for listing time series.
+
+        Example::
+
+            query = client.query(minutes=5)
+            print query.as_dataframe()  # Requires pandas.
+
+        :type metric_type: string
+        :param metric_type: The metric type name. The default value is
+            ``"compute.googleapis.com/instance/cpu/utilization"``, but
+            please note that this default value is provided only for
+            demonstration purposes and is subject to change.
+
+        :type resource_type: string
+        :param resource_type: An optional resource type to filter by.
+            For example: ``"gce_instance"``
+
+        :type end_time: :class:`datetime.datetime` or string or None
+        :param end_time: The end time (inclusive) of the time interval
+            for which results should be returned, as a datetime object.
+            The default is the start of the current minute. If the
+            ``days``/``hours``/``minutes`` parameters are not used, the
+            end time can alternatively be provided as a timestamp string
+            in RFC3339 UTC "Zulu" format.
+
+        :type start_time: :class:`datetime.datetime` or string or None
+        :param start_time: An optional start time (exclusive) of the time
+            interval for which results should be returned, as either a
+            datetime object or a timestamp string. If omitted and no
+            non-zero duration is specified, the interval is a point in
+            time. If any of ``days``, ``hours``, or ``minutes`` is non-zero,
+            these are combined and subtracted from the end time to determine
+            the start time.
+
+        :type days: integer
+        :param days: The number of days in the time interval.
+
+        :type hours: integer
+        :param hours: The number of hours in the time interval.
+
+        :type minutes: integer
+        :param minutes: The number of minutes in the time interval.
+
+        :rtype: :class:`~gcloud.monitoring.timeseries.Query`
+        :returns: The query object.
+        """
+        return Query(self, metric_type, resource_type,
+                     end_time=end_time, start_time=start_time,
+                     days=days, hours=hours, minutes=minutes)
+
     def fetch_metric_descriptor(self, metric_type):
         """Look up a metric descriptor by type.
 
+        Example::
+
+            METRIC = 'compute.googleapis.com/instance/cpu/utilization'
+            print client.fetch_metric_descriptor(METRIC)
+
         :type metric_type: string
         :param metric_type: The metric type name.
 
@@ -58,6 +133,11 @@ def fetch_metric_descriptor(self, metric_type):
     def list_metric_descriptors(self, filter=None):
         """List all metric descriptors for the project.
 
+        Example::
+
+            for descriptor in client.list_metric_descriptors():
+                print descriptor.type
+
         :type filter: string or None
         :param filter: An optional filter string describing the metric
                        descriptors to be returned.
@@ -71,6 +151,10 @@ def list_metric_descriptors(self, filter=None):
     def fetch_resource_descriptor(self, resource_type):
         """Look up a resource descriptor by type.
 
+        Example::
+
+            print client.fetch_resource_descriptor('gce_instance')
+
         :type resource_type: string
         :param resource_type: The resource type name.
 
@@ -84,6 +168,11 @@ def fetch_resource_descriptor(self, resource_type):
     def list_resource_descriptors(self, filter=None):
         """List all resource descriptors for the project.
 
+        Example::
+
+            for descriptor in client.list_resource_descriptors():
+                print descriptor.type
+
         :type filter: string or None
         :param filter: An optional filter string describing the resource
                        descriptors to be returned.
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
new file mode 100644
index 000000000000..f9f087c54a67
--- /dev/null
+++ b/gcloud/monitoring/timeseries.py
@@ -0,0 +1,706 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Time series in the Google Monitoring API."""
+
+# Features intentionally omitted from this first version of the client library:
+#   - Creating time series.
+#   - Natural representation of distribution values.
+
+import collections
+import copy
+import datetime
+import itertools
+
+import six
+
+from gcloud.monitoring.metric import Metric
+from gcloud.monitoring.resource import Resource
+
+TOP_RESOURCE_LABELS = [
+    'project_id',
+    'aws_account',
+    'location',
+    'region',
+    'zone',
+]
+
+
+class Query(object):
+    """Query object for listing time series.
+
+    The preferred way to construct a query object is using the
+    :meth:`~gcloud.monitoring.client.Client.query` method
+    of the :class:`~gcloud.monitoring.client.Client` class.
+
+    :type client: :class:`gcloud.monitoring.client.Client`
+    :param client: The client to use.
+
+    :type metric_type: string
+    :param metric_type: The metric type name. The default value is
+        ``"compute.googleapis.com/instance/cpu/utilization"``, but
+        please note that this default value is provided only for
+        demonstration purposes and is subject to change.
+
+    :type resource_type: string
+    :param resource_type: An optional resource type to filter by.
+        For example: ``"gce_instance"``
+
+    :type end_time: :class:`datetime.datetime` or string or None
+    :param end_time: The end time (inclusive) of the time interval
+        for which results should be returned, as a datetime object.
+        The default is the start of the current minute. If the
+        ``days``/``hours``/``minutes`` parameters are not used, the
+        end time can alternatively be provided as a timestamp string
+        in RFC3339 UTC "Zulu" format.
+
+    :type start_time: :class:`datetime.datetime` or string or None
+    :param start_time: An optional start time (exclusive) of the time
+        interval for which results should be returned, as either a
+        datetime object or a timestamp string. If omitted and no
+        non-zero duration is specified, the interval is a point in
+        time. If any of ``days``, ``hours``, or ``minutes`` is non-zero,
+        these are combined and subtracted from the end time to determine
+        the start time.
+
+    :type days: integer
+    :param days: The number of days in the time interval.
+
+    :type hours: integer
+    :param hours: The number of hours in the time interval.
+
+    :type minutes: integer
+    :param minutes: The number of minutes in the time interval.
+    """
+
+    DEFAULT_METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
+
+    def __init__(self, client,
+                 metric_type=DEFAULT_METRIC_TYPE, resource_type=None,
+                 end_time=None, start_time=None,
+                 days=0, hours=0, minutes=0):
+        if end_time is None:
+            end_time = datetime.datetime.utcnow().replace(second=0,
+                                                          microsecond=0)
+
+        if days or hours or minutes:
+            if start_time is not None:
+                raise ValueError('Duration and start time both specified.')
+            start_time = end_time - datetime.timedelta(days=days,
+                                                       hours=hours,
+                                                       minutes=minutes)
+
+        self._client = client
+        self._end_time = end_time
+        self._start_time = start_time
+        self._filter = _Filter(metric_type, resource_type)
+
+        self._per_series_aligner = None
+        self._alignment_period_seconds = None
+        self._cross_series_reducer = None
+        self._group_by_fields = ()
+
+    def __iter__(self):
+        return self.iter()
+
+    @property
+    def filter(self):
+        """The filter string.
+
+        This is constructed from the metric type, the resource type, and
+        selectors for the group ID, monitored projects, resource labels,
+        and metric labels.
+        """
+        return str(self._filter)
+
+    def select_group(self, group_id):
+        """Copy the query and add filtering by group.
+
+        :type group_id: string
+        :param group_id: The ID of a group to filter by.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.group_id = group_id
+        return new_query
+
+    def select_projects(self, *args):
+        """Copy the query and add filtering by monitored projects.
+
+        This is only useful if the target project represents a Stackdriver
+        account containing the specified monitored projects.
+
+        Examples::
+
+            query = query.select_projects('project-1')
+            query = query.select_projects('project-1', 'project-2')
+
+        :param args: Project IDs limiting the resources to be included
+            in the query.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.projects = args
+        return new_query
+
+    def select_resource_labels(self, *args, **kwargs):
+        """Copy the query and add filtering by resource labels.
+
+        Examples::
+
+            query = query.select_resource_labels(zone='us-central1-a')
+            query = query.select_resource_labels(zone_prefix='europe-')
+
+        A keyword argument ``<label>=<value>`` ordinarily generates a filter
+        expression of the form::
+
+            resource.label.<label> = "<value>"
+
+        However, by adding ``"_prefix"`` or ``"_suffix"`` to the keyword,
+        you can specify a partial match.
+
+        ``<label>_prefix=<value>`` generates::
+
+            resource.label.<label> = starts_with("<value>")
+
+        ``<label>_suffix=<value>`` generates::
+
+            resource.label.<label> = ends_with("<value>")
+
+        .. note::
+
+            The label ``"instance_name"`` is a metric label, not a
+            resource label. Use ``select_metric_labels(instance_name=...)``,
+            not this method.
+
+        :param args: Raw filter expression strings to include in the
+            conjunction. If just one is provided and no keyword arguments
+            are provided, it can be a disjunction.
+
+        :param kwargs: Label filters to include in the conjunction as
+            described above.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.select_resource_labels(*args, **kwargs)
+        return new_query
+
+    def select_metric_labels(self, *args, **kwargs):
+        """Copy the query and add filtering by metric labels.
+
+        Examples::
+
+            query = query.select_metric_labels(instance_name='myinstance')
+            query = query.select_metric_labels(
+                instance_name_prefix='mycluster-')
+
+        A keyword argument ``<label>=<value>`` ordinarily generates a filter
+        expression of the form::
+
+            metric.label.<label> = "<value>"
+
+        However, by adding ``"_prefix"`` or ``"_suffix"`` to the keyword,
+        you can specify a partial match.
+
+        ``<label>_prefix=<value>`` generates::
+
+            metric.label.<label> = starts_with("<value>")
+
+        ``<label>_suffix=<value>`` generates::
+
+            metric.label.<label> = ends_with("<value>")
+
+        :param args: Raw filter expression strings to include in the
+            conjunction. If just one is provided and no keyword arguments
+            are provided, it can be a disjunction.
+
+        :param kwargs: Label filters to include in the conjunction as
+            described above.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.select_metric_labels(*args, **kwargs)
+        return new_query
+
+    def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
+        """Copy the query and add temporal alignment.
+
+        If ``per_series_aligner`` is not ``"ALIGN_NONE"``, each time series
+        will contain data points only on the period boundaries.
+
+        Example::
+
+            query = query.align('ALIGN_MEAN', minutes=5)
+
+        :type per_series_aligner: string
+        :param per_series_aligner: The approach to be used to align individual
+            time series. For example: ``"ALIGN_MEAN"``
+
+        :type seconds: integer
+        :param seconds: The number of seconds in the alignment period.
+
+        :type minutes: integer
+        :param minutes: The number of minutes in the alignment period.
+
+        :type hours: integer
+        :param hours: The number of hours in the alignment period.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._per_series_aligner = per_series_aligner
+        new_query._alignment_period_seconds = seconds + 60 * (minutes +
+                                                              60 * hours)
+        return new_query
+
+    def reduce(self, cross_series_reducer, group_by_fields=()):
+        """Copy the query and add cross-series reduction.
+
+        :type cross_series_reducer: string
+        :param cross_series_reducer: The approach to be used to combine time
+            series. For example: ``"REDUCE_MEAN"``
+
+        :type group_by_fields: string or list of strings
+        :param group_by_fields: An optional field or set of fields
+            to be preserved by the reduction. For example, a value of
+            ``"resource.zone"`` will result in one time series per zone.
+            The default is to aggregate all of the time series into just one.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        if isinstance(group_by_fields, six.string_types):
+            group_by_fields = [group_by_fields]
+
+        new_query = self.copy()
+        new_query._cross_series_reducer = cross_series_reducer
+        new_query._group_by_fields = group_by_fields
+        return new_query
+
+    def iter(self, headers_only=False, _page_size=None):
+        """Yield all time series objects selected by the query.
+
+        Note that the :class:`Query` object itself is an iterable, such that
+        the following are equivalent::
+
+            for timeseries in query: ...
+            for timeseries in query.iter(): ...
+
+        :type headers_only: boolean
+        :param headers_only:
+             Whether to omit the point data from the time series objects.
+
+        :type _page_size: integer or None
+        :param _page_size:
+            An optional positive number specifying the maximum number of
+            points to return per page. This can be used to control how far
+            the iterator reads ahead.
+
+        :rtype: iterator over :class:`TimeSeries`
+        :returns: Time series objects, containing points ordered from oldest
+            to newest.
+        """
+        path = '/projects/{}/timeSeries'.format(self._client.project)
+
+        def _fragments():
+            page_token = None
+            while True:
+                params = self._build_query_params(
+                    headers_only=headers_only,
+                    page_size=_page_size,
+                    page_token=page_token,
+                )
+                response = self._client.connection.api_request(
+                    method='GET',
+                    path=path,
+                    query_params=params,
+                )
+                for info in response.get('timeSeries', []):
+                    yield TimeSeries._from_dict(info)
+
+                page_token = response.get('nextPageToken')
+                if not page_token:
+                    break
+
+        for timeseries, fragments in itertools.groupby(
+                _fragments(),
+                lambda fragment: fragment._replace(points=None)):
+            points = list(itertools.chain.from_iterable(
+                fragment.points for fragment in fragments))
+            points.reverse()  # Order from oldest to newest.
+            yield timeseries._replace(points=points)
+
+    def _build_query_params(self, headers_only, page_size, page_token):
+        """Assemble the list of key-value pairs for the URL query string.
+
+        We use a list of key-value pairs instead of a ``dict`` to allow for
+        repeated fields.
+
+        :type headers_only: boolean
+        :param headers_only:
+             Whether to omit the point data from the ``TimeSeries`` objects.
+
+        :type page_size: integer or None
+        :param page_size: A limit on the number of points to return per page.
+
+        :type page_token: string or None
+        :param page_token: A token to continue the retrieval.
+
+        :rtype: list of tuples
+        :returns:
+            A list of key-value pairs suitable for passing to ``urlencode``.
+        """
+        params = {'filter': self.filter}
+
+        params['interval.endTime'] = _format_timestamp(self._end_time)
+        if self._start_time is not None:
+            params['interval.startTime'] = _format_timestamp(self._start_time)
+
+        if self._per_series_aligner is not None:
+            params['aggregation.perSeriesAligner'] = self._per_series_aligner
+
+        if self._alignment_period_seconds is not None:
+            alignment_period = '{}s'.format(self._alignment_period_seconds)
+            params['aggregation.alignmentPeriod'] = alignment_period
+
+        if self._cross_series_reducer is not None:
+            params['aggregation.crossSeriesReducer'] = \
+                self._cross_series_reducer
+
+        if headers_only:
+            params['view'] = 'HEADERS'
+
+        if page_size is not None:
+            params['pageSize'] = page_size
+
+        if page_token is not None:
+            params['pageToken'] = page_token
+
+        # Convert to a list of tuples before adding repeated fields.
+        params = list(six.iteritems(params))
+
+        if self._group_by_fields:
+            params.extend(('aggregation.groupByFields', field)
+                          for field in self._group_by_fields)
+
+        return sorted(params)
+
+    def as_dataframe(self, label=None, labels=None):
+        """Return all the selected time series as a ``pandas`` dataframe.
+
+        .. note::
+
+            Use of this method requires that you have ``pandas`` installed.
+
+        Examples::
+
+            # Generate a dataframe with a multi-level column header including
+            # the resource type and all available resource and metric labels.
+            # This can be useful for seeing what labels are available.
+            dataframe = query.as_dataframe()
+
+            # Generate a dataframe using a particular label for the column
+            # names.
+            dataframe = query.as_dataframe(label='instance_name')
+
+            # Generate a dataframe with a multi-level column header.
+            dataframe = query.as_dataframe(labels=['zone', 'instance_name'])
+
+            # Generate a dataframe with a multi-level column header, assuming
+            # the metric is issued by more than one type of resource.
+            dataframe = query.as_dataframe(
+                labels=['resource_type', 'instance_id'])
+
+        :type label: string or None
+        :param label: The label name to use for the dataframe header.
+            This can be the name of a resource label or metric label
+            (e.g., ``"instance_name"``), or the string ``"resource_type"``.
+
+        :type labels: list of strings, or None
+        :param labels: A list or tuple of label names to use for the dataframe
+            header. If more than one label name is provided, the resulting
+            dataframe will have a multi-level column header. Providing values
+            for both ``label`` and ``labels`` is an error.
+
+        :rtype: :class:`pandas.DataFrame`
+        :returns: A dataframe where each column represents one time series.
+        """
+        import pandas   # pylint: disable=import-error
+
+        if label is not None and labels is not None:
+            raise ValueError('Cannot specify both "label" and "labels".')
+        elif not (labels or labels is None):
+            raise ValueError('"labels" must be non-empty or None.')
+
+        columns = []
+        headers = []
+        for time_series in self:
+            pandas_series = pandas.Series(
+                data=[p.value for p in time_series.points],
+                index=[p.end_time for p in time_series.points],
+            )
+            columns.append(pandas_series)
+            headers.append(time_series._replace(points=None))
+
+        # Implement a smart default of using all available labels.
+        if label is None and labels is None:
+            resource_labels = set(itertools.chain.from_iterable(
+                header.resource.labels for header in headers))
+            metric_labels = set(itertools.chain.from_iterable(
+                header.metric.labels for header in headers))
+            labels = (['resource_type'] +
+                      _sorted_resource_labels(resource_labels) +
+                      sorted(metric_labels))
+
+        # Assemble the columns into a DataFrame.
+        dataframe = pandas.DataFrame(columns).T
+
+        # Convert the timestamp strings into a DatetimeIndex.
+        dataframe.index = pandas.to_datetime(dataframe.index)
+
+        # Build a column Index or MultiIndex from the label values. Do not
+        # include level names in the column header if the user requested a
+        # single-level header by specifying "label".
+        level_names = labels or None
+        label_keys = labels or [label]
+        dataframe.columns = pandas.MultiIndex.from_arrays(
+            [[header.labels.get(key, '') for header in headers]
+             for key in label_keys],
+            names=level_names)
+
+        # Sort the rows just in case (since the API doesn't guarantee the
+        # ordering), and sort the columns lexicographically.
+        return dataframe.sort_index(axis=0).sort_index(axis=1)
+
+    def copy(self):
+        """Copy the query object.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = copy.copy(self)
+        new_query._filter = copy.copy(self._filter)
+        return new_query
+
+
+class TimeSeries(collections.namedtuple(
+        'TimeSeries', 'metric resource metric_kind value_type points')):
+    """A single time series of metric values.
+
+    :type metric: :class:`~gcloud.monitoring.metric.Metric`
+    :param metric: A metric object.
+
+    :type resource: :class:`~gcloud.monitoring.resource.Resource`
+    :param resource: A resource object.
+
+    :type metric_kind: string
+    :param metric_kind: The kind of measurement: ``"GAUGE"``, ``"DELTA"``,
+        or ``"CUMULATIVE"``.
+
+    :type value_type: string
+    :param value_type: The value type of the metric: ``"BOOL"``, ``"INT64"``,
+        ``"DOUBLE"``, ``"STRING"``, ``"DISTRIBUTION"``, or ``"MONEY"``.
+
+    :type points: list of :class:`Point`
+    :param points: A list of point objects.
+    """
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a time series from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`TimeSeries`
+        :returns: A time series object.
+        """
+        metric = Metric._from_dict(info['metric'])
+        resource = Resource._from_dict(info['resource'])
+        metric_kind = info['metricKind']
+        value_type = info['valueType']
+        points = [Point._from_dict(p) for p in info.get('points', [])]
+        return cls(metric, resource, metric_kind, value_type, points)
+
+    @property
+    def labels(self):
+        """A single dictionary with values for all the labels.
+
+        This combines ``resource.labels`` and ``metric.labels`` and also
+        adds ``"resource_type"``.
+        """
+        # pylint: disable=attribute-defined-outside-init
+        try:
+            return self._labels
+        except AttributeError:
+            labels = {'resource_type': self.resource.type}
+            labels.update(self.resource.labels)
+            labels.update(self.metric.labels)
+            self._labels = labels
+            return self._labels
+
+    def __repr__(self):
+        """Return a representation string with the points elided."""
+        return '\n'.join([
+            'TimeSeries(',
+            '    {},'.format(self.metric),
+            '    {},'.format(self.resource),
+            '    {}, {}, Number of points={})'.format(
+                self.metric_kind, self.value_type, len(self.points)),
+        ])
+
+
+class Point(collections.namedtuple('Point', 'end_time start_time value')):
+    """A single point in a time series.
+
+    :type end_time: string
+    :param end_time: The end time in RFC3339 UTC "Zulu" format.
+
+    :type start_time: string or None
+    :param start_time: An optional start time in RFC3339 UTC "Zulu" format.
+
+    :param value: The metric value. This can be a scalar or a distribution.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def _from_dict(cls, info):
+        """Construct a Point from the parsed JSON representation.
+
+        :type info: dict
+        :param info:
+            A ``dict`` parsed from the JSON wire-format representation.
+
+        :rtype: :class:`Point`
+        :returns: A point object.
+        """
+        end_time = info['interval']['endTime']
+        start_time = info['interval'].get('startTime')
+        value_type, value = next(six.iteritems(info['value']))
+        if value_type == 'int64Value':
+            value = int(value)  # Convert from string.
+
+        return cls(end_time, start_time, value)
+
+
+class _Filter(object):
+    """Helper for assembling a filter string."""
+
+    def __init__(self, metric_type, resource_type=None):
+        self.metric_type = metric_type
+        self.resource_type = resource_type
+        self.group_id = None
+        self.projects = ()
+        self.resource_label_filter = None
+        self.metric_label_filter = None
+
+    def select_resource_labels(self, *args, **kwargs):
+        """Select by resource labels.
+
+        See :meth:`Query.select_resource_labels`.
+        """
+        self.resource_label_filter = _build_label_filter('resource',
+                                                         *args, **kwargs)
+
+    def select_metric_labels(self, *args, **kwargs):
+        """Select by metric labels.
+
+        See :meth:`Query.select_metric_labels`.
+        """
+        self.metric_label_filter = _build_label_filter('metric',
+                                                       *args, **kwargs)
+
+    def __str__(self):
+        filters = ['metric.type = "{}"'.format(self.metric_type)]
+        if self.resource_type is not None:
+            filters.append('resource.type = "{}"'.format(self.resource_type))
+        if self.group_id is not None:
+            filters.append('group.id = "{}"'.format(self.group_id))
+        if self.projects:
+            filters.append(' OR '.join('project = "{}"'.format(project)
+                                       for project in self.projects))
+        if self.resource_label_filter:
+            filters.append(self.resource_label_filter)
+        if self.metric_label_filter:
+            filters.append(self.metric_label_filter)
+
+        # Parentheses are never actually required, because OR binds more
+        # tightly than AND in the Monitoring API's filter syntax.
+        return ' AND '.join(filters)
+
+
+def _build_label_filter(category, *args, **kwargs):
+    """Construct a filter string to filter on metric or resource labels."""
+    def _strip_suffix(key):
+        return key.rsplit('_', 1)[0]
+
+    def _terms():
+        for arg in args:
+            yield arg
+
+        for key in kwargs:
+            value = kwargs[key]
+            if value is None:
+                continue
+
+            key = '.'.join((category, 'label', key))
+            if key.endswith('_prefix'):
+                yield '{} = starts_with("{}")'.format(
+                    _strip_suffix(key), value)
+            elif key.endswith('_suffix'):
+                yield '{} = ends_with("{}")'.format(
+                    _strip_suffix(key), value)
+            else:
+                yield '{} = "{}"'.format(key, value)
+
+    return ' AND '.join(sorted(_terms()))
+
+
+def _sorted_resource_labels(labels):
+    """Sort label names, putting well-known resource labels first."""
+    head = [label for label in TOP_RESOURCE_LABELS if label in labels]
+    tail = sorted(label for label in labels
+                  if label not in TOP_RESOURCE_LABELS)
+    return head + tail
+
+
+def _format_timestamp(timestamp):
+    """Convert a datetime object to a string as required by the API.
+
+    :type timestamp: :class:`datetime.datetime` or string
+    :param timestamp: A :class:`~datetime.datetime` or a timestamp string
+        in RFC3339 UTC "Zulu" format.
+
+    :rtype: string
+    :returns: The formatted timestamp. For example:
+        ``"2016-02-17T19:18:01.763000Z"``
+    """
+    if isinstance(timestamp, six.string_types):
+        return timestamp
+
+    if timestamp.tzinfo is not None:
+        # Convert to UTC and remove the time zone info.
+        timestamp = timestamp.replace(tzinfo=None) - timestamp.utcoffset()
+
+    return timestamp.isoformat() + 'Z'

From 8ea9fc591b2e7723892c51376a92bb9ee8fd8411 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Mon, 4 Apr 2016 11:32:19 -0400
Subject: [PATCH 04/61] Add unit tests for everything but time series.

---
 gcloud/monitoring/metric.py          |   9 +-
 gcloud/monitoring/resource.py        |  15 +-
 gcloud/monitoring/test_client.py     | 227 ++++++++++++++++++
 gcloud/monitoring/test_connection.py |  44 ++++
 gcloud/monitoring/test_label.py      |  56 +++++
 gcloud/monitoring/test_metric.py     | 345 +++++++++++++++++++++++++++
 gcloud/monitoring/test_resource.py   | 325 +++++++++++++++++++++++++
 gcloud/monitoring/timeseries.py      |   3 +-
 8 files changed, 1012 insertions(+), 12 deletions(-)
 create mode 100644 gcloud/monitoring/test_client.py
 create mode 100644 gcloud/monitoring/test_connection.py
 create mode 100644 gcloud/monitoring/test_label.py
 create mode 100644 gcloud/monitoring/test_metric.py
 create mode 100644 gcloud/monitoring/test_resource.py

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 7bb9f3e5ca72..3446c87bde86 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -79,7 +79,7 @@ def _fetch(cls, client, metric_type):
         path = '/projects/{project}/metricDescriptors/{type}'.format(
             project=client.project,
             type=metric_type)
-        info = client.connection.api_request('GET', path)
+        info = client.connection.api_request(method='GET', path=path)
         return cls._from_dict(info)
 
     @classmethod
@@ -98,7 +98,8 @@ def _list(cls, client, filter=None):
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
 
-        path = '/projects/{}/metricDescriptors/'.format(client.project)
+        path = '/projects/{project}/metricDescriptors/'.format(
+            project=client.project)
 
         def _descriptors():
             page_token = None
@@ -111,8 +112,8 @@ def _descriptors():
                 if page_token is not None:
                     params['pageToken'] = page_token
 
-                response = client.connection.api_request('GET', path,
-                                                         query_params=params)
+                response = client.connection.api_request(
+                    method='GET', path=path, query_params=params)
                 for info in response.get('metricDescriptors', []):
                     yield cls._from_dict(info)
 
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index ed633bae50f1..b5fcd9dc943e 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -64,9 +64,10 @@ def _fetch(cls, client, resource_type):
 
         :raises: :class:`gcloud.exceptions.NotFound`
         """
-        path = '/projects/{}/monitoredResourceDescriptors/{}'.format(
-            client.project, resource_type)
-        info = client.connection.api_request('GET', path)
+        path = '/projects/{project}/monitoredResourceDescriptors/{type}' \
+            .format(project=client.project,
+                    type=resource_type)
+        info = client.connection.api_request(method='GET', path=path)
         return cls._from_dict(info)
 
     @classmethod
@@ -85,8 +86,8 @@ def _list(cls, client, filter=None):
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
 
-        path = '/projects/{}/monitoredResourceDescriptors/'.format(
-            client.project)
+        path = '/projects/{project}/monitoredResourceDescriptors/'.format(
+            project=client.project)
 
         def _descriptors():
             page_token = None
@@ -99,8 +100,8 @@ def _descriptors():
                 if page_token is not None:
                     params['pageToken'] = page_token
 
-                response = client.connection.api_request('GET', path,
-                                                         query_params=params)
+                response = client.connection.api_request(
+                    method='GET', path=path, query_params=params)
                 for info in response.get('resourceDescriptors', []):
                     yield cls._from_dict(info)
 
diff --git a/gcloud/monitoring/test_client.py b/gcloud/monitoring/test_client.py
new file mode 100644
index 000000000000..14514222dff8
--- /dev/null
+++ b/gcloud/monitoring/test_client.py
@@ -0,0 +1,227 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+
+class TestClient(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.client import Client
+        return Client
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_fetch_metric_descriptor(self):
+        PROJECT = 'my-project'
+        TYPE = 'custom.googleapis.com/my-metric'
+        NAME = 'projects/{project}/metricDescriptors/{type}'.format(
+            project=PROJECT, type=TYPE)
+        DESCRIPTION = 'This is my metric.'
+
+        METRIC_DESCRIPTOR = {
+            'name': NAME,
+            'type': TYPE,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION,
+        }
+
+        # This test is identical to TestMetricDescriptor.test_fetch()
+        # except for the following three lines.
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        connection = client.connection = _Connection(METRIC_DESCRIPTOR)
+        descriptor = client.fetch_metric_descriptor(TYPE)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + NAME}
+        self.assertEqual(request, expected_request)
+
+    def test_list_metric_descriptors(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
+
+        TYPE1 = 'custom.googleapis.com/my-metric-1'
+        DESCRIPTION1 = 'This is my first metric.'
+        NAME1 = PATH + TYPE1
+        METRIC_DESCRIPTOR1 = {
+            'name': NAME1,
+            'type': TYPE1,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION1,
+        }
+
+        TYPE2 = 'custom.googleapis.com/my-metric-2'
+        DESCRIPTION2 = 'This is my second metric.'
+        NAME2 = PATH + TYPE2
+        METRIC_DESCRIPTOR2 = {
+            'name': NAME2,
+            'type': TYPE2,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION2,
+        }
+
+        RESPONSE = {
+            'metricDescriptors': [METRIC_DESCRIPTOR1, METRIC_DESCRIPTOR2],
+        }
+
+        # This test is identical to TestMetricDescriptor.test_list()
+        # except for the following three lines.
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        connection = client.connection = _Connection(RESPONSE)
+        descriptors = client.list_metric_descriptors()
+
+        self.assertEqual(len(descriptors), 2)
+        descriptor1, descriptor2 = descriptors
+
+        self.assertEqual(descriptor1.name, NAME1)
+        self.assertEqual(descriptor1.type, TYPE1)
+        self.assertEqual(descriptor1.description, DESCRIPTION1)
+
+        self.assertEqual(descriptor2.name, NAME2)
+        self.assertEqual(descriptor2.type, TYPE2)
+        self.assertEqual(descriptor2.description, DESCRIPTION2)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + PATH,
+                            'query_params': {}}
+        self.assertEqual(request, expected_request)
+
+    def test_fetch_resource_descriptor(self):
+        PROJECT = 'my-project'
+        TYPE = 'gce_instance'
+        NAME = 'projects/{project}/monitoredResourceDescriptors/{type}'.format(
+            project=PROJECT, type=TYPE)
+        DISPLAY_NAME = 'GCE Instance'
+        DESCRIPTION = 'A VM instance hosted in Google Compute Engine.'
+        LABEL1 = {'key': 'project_id', 'valueType': 'STRING',
+                  'description': 'The ID of the GCP project...'}
+        LABEL2 = {'key': 'instance_id', 'valueType': 'STRING',
+                  'description': 'The VM instance identifier...'}
+        LABEL3 = {'key': 'zone', 'valueType': 'STRING',
+                  'description': 'The GCE zone...'}
+
+        RESOURCE_DESCRIPTOR = {
+            'name': NAME,
+            'type': TYPE,
+            'displayName': DISPLAY_NAME,
+            'description': DESCRIPTION,
+            'labels': [LABEL1, LABEL2, LABEL3],
+        }
+
+        # This test is identical to TestResourceDescriptor.test_fetch()
+        # except for the following three lines.
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        connection = client.connection = _Connection(RESOURCE_DESCRIPTOR)
+        descriptor = client.fetch_resource_descriptor(TYPE)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.display_name, DISPLAY_NAME)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+        self.assertEqual(len(descriptor.labels), 3)
+        label1, label2, label3 = descriptor.labels
+        self.assertEqual(label1.key, LABEL1['key'])
+        self.assertEqual(label2.key, LABEL2['key'])
+        self.assertEqual(label3.key, LABEL3['key'])
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + NAME}
+        self.assertEqual(request, expected_request)
+
+    def test_list_resource_descriptors(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
+            project=PROJECT)
+
+        TYPE1 = 'custom.googleapis.com/resource-1'
+        DESCRIPTION1 = 'This is the first resource.'
+        NAME1 = PATH + TYPE1
+        RESOURCE_DESCRIPTOR1 = {
+            'name': NAME1,
+            'type': TYPE1,
+            'description': DESCRIPTION1,
+        }
+
+        TYPE2 = 'custom.googleapis.com/resource-2'
+        DESCRIPTION2 = 'This is the second resource.'
+        NAME2 = PATH + TYPE2
+        RESOURCE_DESCRIPTOR2 = {
+            'name': NAME2,
+            'type': TYPE2,
+            'description': DESCRIPTION2,
+        }
+
+        RESPONSE = {
+            'resourceDescriptors':
+                [RESOURCE_DESCRIPTOR1, RESOURCE_DESCRIPTOR2],
+        }
+
+        # This test is identical to TestResourceDescriptor.test_list()
+        # except for the following three lines.
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        connection = client.connection = _Connection(RESPONSE)
+        descriptors = client.list_resource_descriptors()
+
+        self.assertEqual(len(descriptors), 2)
+        descriptor1, descriptor2 = descriptors
+
+        self.assertEqual(descriptor1.name, NAME1)
+        self.assertEqual(descriptor1.type, TYPE1)
+        self.assertEqual(descriptor1.description, DESCRIPTION1)
+
+        self.assertEqual(descriptor2.name, NAME2)
+        self.assertEqual(descriptor2.type, TYPE2)
+        self.assertEqual(descriptor2.description, DESCRIPTION2)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + PATH,
+                            'query_params': {}}
+        self.assertEqual(request, expected_request)
+
+
+class _Credentials(object):
+
+    _scopes = None
+
+    @staticmethod
+    def create_scoped_required():
+        return True
+
+    def create_scoped(self, scope):
+        self._scopes = scope
+        return self
+
+
+class _Connection(object):
+
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self._requested = []
+
+    def api_request(self, **kwargs):
+        from gcloud.exceptions import NotFound
+        self._requested.append(kwargs)
+        try:
+            return self._responses.pop(0)
+        except IndexError:  # pragma: NO COVER
+            raise NotFound('miss')
diff --git a/gcloud/monitoring/test_connection.py b/gcloud/monitoring/test_connection.py
new file mode 100644
index 000000000000..69079cde7870
--- /dev/null
+++ b/gcloud/monitoring/test_connection.py
@@ -0,0 +1,44 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+
+class TestConnection(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.connection import Connection
+        return Connection
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        credentials = _Credentials()
+        connection = self._makeOne(credentials)
+        self.assertEqual(connection.credentials._scopes,
+                         self._getTargetClass().SCOPE)
+
+
+class _Credentials(object):
+
+    _scopes = None
+
+    @staticmethod
+    def create_scoped_required():
+        return True
+
+    def create_scoped(self, scope):
+        self._scopes = scope
+        return self
diff --git a/gcloud/monitoring/test_label.py b/gcloud/monitoring/test_label.py
new file mode 100644
index 000000000000..e85919e9bd80
--- /dev/null
+++ b/gcloud/monitoring/test_label.py
@@ -0,0 +1,56 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+
+class TestLabel(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.label import LabelDescriptor
+        return LabelDescriptor
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        KEY = 'response_code'
+        VALUE_TYPE = 'INT64'
+        DESCRIPTION = 'HTTP status code for the request.'
+        descriptor = self._makeOne(key=KEY, value_type=VALUE_TYPE,
+                                   description=DESCRIPTION)
+        self.assertEqual(descriptor.key, KEY)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+    def test_from_dict(self):
+        KEY = 'response_code'
+        VALUE_TYPE = 'INT64'
+        DESCRIPTION = 'HTTP status code for the request.'
+        info = {
+            'key': KEY,
+            'valueType': VALUE_TYPE,
+            'description': DESCRIPTION,
+        }
+        descriptor = self._getTargetClass()._from_dict(info)
+        self.assertEqual(descriptor.key, KEY)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+    def test_from_dict_defaults(self):
+        info = {}
+        descriptor = self._getTargetClass()._from_dict(info)
+        self.assertEqual(descriptor.key, '')
+        self.assertEqual(descriptor.value_type, 'STRING')
+        self.assertEqual(descriptor.description, '')
diff --git a/gcloud/monitoring/test_metric.py b/gcloud/monitoring/test_metric.py
new file mode 100644
index 000000000000..d1ac313e2c8d
--- /dev/null
+++ b/gcloud/monitoring/test_metric.py
@@ -0,0 +1,345 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+
+class TestMetricDescriptor(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.metric import MetricDescriptor
+        return MetricDescriptor
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        from gcloud.monitoring.label import LabelDescriptor
+
+        TYPE = 'appengine.googleapis.com/http/server/response_count'
+        NAME = 'projects/my-project/metricDescriptors/' + TYPE
+        LABELS = [
+            LabelDescriptor(key='loading', value_type='BOOL',
+                            description='Loaded a new instance?'),
+            LabelDescriptor(key='response_code', value_type='INT64',
+                            description='HTTP status code for the request.'),
+        ]
+
+        METRIC_KIND = 'DELTA'
+        VALUE_TYPE = 'INT64'
+
+        UNIT = '{responses}/s'
+        DESCRIPTION = 'Delta HTTP response count.'
+        DISPLAY_NAME = 'Response count'
+
+        descriptor = self._makeOne(
+            name=NAME,
+            type=TYPE,
+            labels=LABELS,
+            metric_kind=METRIC_KIND,
+            value_type=VALUE_TYPE,
+            unit=UNIT,
+            description=DESCRIPTION,
+            display_name=DISPLAY_NAME,
+        )
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.labels, LABELS)
+
+        self.assertEqual(descriptor.metric_kind, METRIC_KIND)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+
+        self.assertEqual(descriptor.unit, UNIT)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+        self.assertEqual(descriptor.display_name, DISPLAY_NAME)
+
+    def test_from_dict(self):
+        TYPE = 'appengine.googleapis.com/http/server/response_count'
+        NAME = 'projects/my-project/metricDescriptors/' + TYPE
+        LABEL1 = {'key': 'loading', 'valueType': 'BOOL',
+                  'description': 'Loaded a new instance?'}
+        LABEL2 = {'key': 'response_code', 'valueType': 'INT64',
+                  'description': 'HTTP status code for the request.'}
+
+        METRIC_KIND = 'DELTA'
+        VALUE_TYPE = 'INT64'
+
+        UNIT = '{responses}/s'
+        DESCRIPTION = 'Delta HTTP response count.'
+        DISPLAY_NAME = 'Response count'
+
+        info = {
+            'name': NAME,
+            'type': TYPE,
+            'labels': [LABEL1, LABEL2],
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'unit': UNIT,
+            'description': DESCRIPTION,
+            'displayName': DISPLAY_NAME,
+        }
+        descriptor = self._getTargetClass()._from_dict(info)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+
+        self.assertEqual(len(descriptor.labels), 2)
+        label1, label2 = descriptor.labels
+        self.assertEqual(label1.key, LABEL1['key'])
+        self.assertEqual(label2.key, LABEL2['key'])
+
+        self.assertEqual(descriptor.metric_kind, METRIC_KIND)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+
+        self.assertEqual(descriptor.unit, UNIT)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+        self.assertEqual(descriptor.display_name, DISPLAY_NAME)
+
+    def test_from_dict_defaults(self):
+        METRIC_KIND = 'CUMULATIVE'
+        VALUE_TYPE = 'DOUBLE'
+
+        info = {
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+        descriptor = self._getTargetClass()._from_dict(info)
+
+        self.assertEqual(descriptor.name, '')
+        self.assertEqual(descriptor.type, '')
+        self.assertEqual(descriptor.labels, ())
+        self.assertEqual(descriptor.metric_kind, METRIC_KIND)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+        self.assertEqual(descriptor.unit, '')
+        self.assertEqual(descriptor.description, '')
+        self.assertEqual(descriptor.display_name, '')
+
+    def test_fetch(self):
+        PROJECT = 'my-project'
+        TYPE = 'custom.googleapis.com/my-metric'
+        NAME = 'projects/{project}/metricDescriptors/{type}'.format(
+            project=PROJECT, type=TYPE)
+        DESCRIPTION = 'This is my metric.'
+
+        METRIC_DESCRIPTOR = {
+            'name': NAME,
+            'type': TYPE,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION,
+        }
+
+        connection = _Connection(METRIC_DESCRIPTOR)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptor = self._getTargetClass()._fetch(client, TYPE)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + NAME}
+        self.assertEqual(request, expected_request)
+
+    def test_list(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
+
+        TYPE1 = 'custom.googleapis.com/my-metric-1'
+        DESCRIPTION1 = 'This is my first metric.'
+        NAME1 = PATH + TYPE1
+        METRIC_DESCRIPTOR1 = {
+            'name': NAME1,
+            'type': TYPE1,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION1,
+        }
+
+        TYPE2 = 'custom.googleapis.com/my-metric-2'
+        DESCRIPTION2 = 'This is my second metric.'
+        NAME2 = PATH + TYPE2
+        METRIC_DESCRIPTOR2 = {
+            'name': NAME2,
+            'type': TYPE2,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION2,
+        }
+
+        RESPONSE = {
+            'metricDescriptors': [METRIC_DESCRIPTOR1, METRIC_DESCRIPTOR2],
+        }
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptors = self._getTargetClass()._list(client)
+
+        self.assertEqual(len(descriptors), 2)
+        descriptor1, descriptor2 = descriptors
+
+        self.assertEqual(descriptor1.name, NAME1)
+        self.assertEqual(descriptor1.type, TYPE1)
+        self.assertEqual(descriptor1.description, DESCRIPTION1)
+
+        self.assertEqual(descriptor2.name, NAME2)
+        self.assertEqual(descriptor2.type, TYPE2)
+        self.assertEqual(descriptor2.description, DESCRIPTION2)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + PATH,
+                            'query_params': {}}
+        self.assertEqual(request, expected_request)
+
+    def test_list_paged(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
+
+        TYPE1 = 'custom.googleapis.com/my-metric-1'
+        DESCRIPTION1 = 'This is my first metric.'
+        NAME1 = PATH + TYPE1
+        METRIC_DESCRIPTOR1 = {
+            'name': NAME1,
+            'type': TYPE1,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION1,
+        }
+
+        TYPE2 = 'custom.googleapis.com/my-metric-2'
+        DESCRIPTION2 = 'This is my second metric.'
+        NAME2 = PATH + TYPE2
+        METRIC_DESCRIPTOR2 = {
+            'name': NAME2,
+            'type': TYPE2,
+            'metricKind': 'GAUGE',
+            'valueType': 'DOUBLE',
+            'description': DESCRIPTION2,
+        }
+
+        TOKEN = 'second-page-please'
+        RESPONSE1 = {
+            'metricDescriptors': [METRIC_DESCRIPTOR1],
+            'nextPageToken': TOKEN,
+        }
+        RESPONSE2 = {
+            'metricDescriptors': [METRIC_DESCRIPTOR2],
+        }
+
+        connection = _Connection(RESPONSE1, RESPONSE2)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptors = self._getTargetClass()._list(client)
+
+        self.assertEqual(len(descriptors), 2)
+        descriptor1, descriptor2 = descriptors
+
+        self.assertEqual(descriptor1.name, NAME1)
+        self.assertEqual(descriptor1.type, TYPE1)
+        self.assertEqual(descriptor1.description, DESCRIPTION1)
+
+        self.assertEqual(descriptor2.name, NAME2)
+        self.assertEqual(descriptor2.type, TYPE2)
+        self.assertEqual(descriptor2.description, DESCRIPTION2)
+
+        request1, request2 = connection._requested
+        expected_request1 = {'method': 'GET', 'path': '/' + PATH,
+                             'query_params': {}}
+        expected_request2 = {'method': 'GET', 'path': '/' + PATH,
+                             'query_params': {'pageToken': TOKEN}}
+        self.assertEqual(request1, expected_request1)
+        self.assertEqual(request2, expected_request2)
+
+    def test_list_filtered(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
+
+        # Request only custom metrics.
+        FILTER = 'metric.type = starts_with("custom.googleapis.com/")'
+
+        # But let's say there are no custom metrics.
+        RESPONSE = {'metricDescriptors': []}
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptors = self._getTargetClass()._list(client, filter=FILTER)
+
+        self.assertEqual(len(descriptors), 0)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + PATH,
+                            'query_params': {'filter': FILTER}}
+        self.assertEqual(request, expected_request)
+
+
+class TestMetric(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.metric import Metric
+        return Metric
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        TYPE = 'appengine.googleapis.com/http/server/response_count'
+        LABELS = {
+            'response_code': 200,
+            'loading': False,
+        }
+        metric = self._makeOne(type=TYPE, labels=LABELS)
+        self.assertEqual(metric.type, TYPE)
+        self.assertEqual(metric.labels, LABELS)
+
+    def test_from_dict(self):
+        TYPE = 'appengine.googleapis.com/http/server/response_count'
+        LABELS = {
+            'response_code': 200,
+            'loading': False,
+        }
+        info = {
+            'type': TYPE,
+            'labels': LABELS,
+        }
+        metric = self._getTargetClass()._from_dict(info)
+        self.assertEqual(metric.type, TYPE)
+        self.assertEqual(metric.labels, LABELS)
+
+    def test_from_dict_defaults(self):
+        info = {}
+        metric = self._getTargetClass()._from_dict(info)
+        self.assertEqual(metric.type, '')
+        self.assertEqual(metric.labels, {})
+
+
+class _Connection(object):
+
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self._requested = []
+
+    def api_request(self, **kwargs):
+        from gcloud.exceptions import NotFound
+        self._requested.append(kwargs)
+        try:
+            return self._responses.pop(0)
+        except IndexError:  # pragma: NO COVER
+            raise NotFound('miss')
+
+
+class _Client(object):
+
+    def __init__(self, project, connection):
+        self.project = project
+        self.connection = connection
diff --git a/gcloud/monitoring/test_resource.py b/gcloud/monitoring/test_resource.py
new file mode 100644
index 000000000000..c027c63fbb47
--- /dev/null
+++ b/gcloud/monitoring/test_resource.py
@@ -0,0 +1,325 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+
+class TestResourceDescriptor(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.resource import ResourceDescriptor
+        return ResourceDescriptor
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        from gcloud.monitoring.label import LabelDescriptor
+
+        TYPE = 'gce_instance'
+        NAME = 'projects/my-project/monitoredResourceDescriptors/' + TYPE
+        DISPLAY_NAME = 'GCE Instance'
+        DESCRIPTION = 'A VM instance hosted in Google Compute Engine.'
+        LABELS = [
+            LabelDescriptor(key='project_id', value_type='STRING',
+                            description='The ID of the GCP project...'),
+            LabelDescriptor(key='instance_id', value_type='STRING',
+                            description='The VM instance identifier...'),
+            LabelDescriptor(key='zone', value_type='STRING',
+                            description='The GCE zone...'),
+        ]
+
+        descriptor = self._makeOne(
+            name=NAME,
+            type=TYPE,
+            display_name=DISPLAY_NAME,
+            description=DESCRIPTION,
+            labels=LABELS,
+        )
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.display_name, DISPLAY_NAME)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+        self.assertEqual(descriptor.labels, LABELS)
+
+    def test_from_dict(self):
+        TYPE = 'gce_instance'
+        NAME = 'projects/my-project/monitoredResourceDescriptors/' + TYPE
+        DISPLAY_NAME = 'GCE Instance'
+        DESCRIPTION = 'A VM instance hosted in Google Compute Engine.'
+        LABEL1 = {'key': 'project_id', 'valueType': 'STRING',
+                  'description': 'The ID of the GCP project...'}
+        LABEL2 = {'key': 'instance_id', 'valueType': 'STRING',
+                  'description': 'The VM instance identifier...'}
+        LABEL3 = {'key': 'zone', 'valueType': 'STRING',
+                  'description': 'The GCE zone...'}
+
+        info = {
+            'name': NAME,
+            'type': TYPE,
+            'displayName': DISPLAY_NAME,
+            'description': DESCRIPTION,
+            'labels': [LABEL1, LABEL2, LABEL3],
+        }
+        descriptor = self._getTargetClass()._from_dict(info)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.display_name, DISPLAY_NAME)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+        self.assertEqual(len(descriptor.labels), 3)
+        label1, label2, label3 = descriptor.labels
+        self.assertEqual(label1.key, LABEL1['key'])
+        self.assertEqual(label2.key, LABEL2['key'])
+        self.assertEqual(label3.key, LABEL3['key'])
+
+    def test_from_dict_defaults(self):
+        descriptor = self._getTargetClass()._from_dict({})
+        self.assertEqual(descriptor.name, '')
+        self.assertEqual(descriptor.type, '')
+        self.assertEqual(descriptor.display_name, '')
+        self.assertEqual(descriptor.description, '')
+        self.assertEqual(descriptor.labels, ())
+
+    def test_fetch(self):
+        PROJECT = 'my-project'
+        TYPE = 'gce_instance'
+        NAME = 'projects/{project}/monitoredResourceDescriptors/{type}'.format(
+            project=PROJECT, type=TYPE)
+        DISPLAY_NAME = 'GCE Instance'
+        DESCRIPTION = 'A VM instance hosted in Google Compute Engine.'
+        LABEL1 = {'key': 'project_id', 'valueType': 'STRING',
+                  'description': 'The ID of the GCP project...'}
+        LABEL2 = {'key': 'instance_id', 'valueType': 'STRING',
+                  'description': 'The VM instance identifier...'}
+        LABEL3 = {'key': 'zone', 'valueType': 'STRING',
+                  'description': 'The GCE zone...'}
+
+        RESOURCE_DESCRIPTOR = {
+            'name': NAME,
+            'type': TYPE,
+            'displayName': DISPLAY_NAME,
+            'description': DESCRIPTION,
+            'labels': [LABEL1, LABEL2, LABEL3],
+        }
+
+        connection = _Connection(RESOURCE_DESCRIPTOR)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptor = self._getTargetClass()._fetch(client, TYPE)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
+        self.assertEqual(descriptor.display_name, DISPLAY_NAME)
+        self.assertEqual(descriptor.description, DESCRIPTION)
+
+        self.assertEqual(len(descriptor.labels), 3)
+        label1, label2, label3 = descriptor.labels
+        self.assertEqual(label1.key, LABEL1['key'])
+        self.assertEqual(label2.key, LABEL2['key'])
+        self.assertEqual(label3.key, LABEL3['key'])
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + NAME}
+        self.assertEqual(request, expected_request)
+
+    def test_list(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
+            project=PROJECT)
+
+        TYPE1 = 'custom.googleapis.com/resource-1'
+        DESCRIPTION1 = 'This is the first resource.'
+        NAME1 = PATH + TYPE1
+        RESOURCE_DESCRIPTOR1 = {
+            'name': NAME1,
+            'type': TYPE1,
+            'description': DESCRIPTION1,
+        }
+
+        TYPE2 = 'custom.googleapis.com/resource-2'
+        DESCRIPTION2 = 'This is the second resource.'
+        NAME2 = PATH + TYPE2
+        RESOURCE_DESCRIPTOR2 = {
+            'name': NAME2,
+            'type': TYPE2,
+            'description': DESCRIPTION2,
+        }
+
+        RESPONSE = {
+            'resourceDescriptors':
+                [RESOURCE_DESCRIPTOR1, RESOURCE_DESCRIPTOR2],
+        }
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptors = self._getTargetClass()._list(client)
+
+        self.assertEqual(len(descriptors), 2)
+        descriptor1, descriptor2 = descriptors
+
+        self.assertEqual(descriptor1.name, NAME1)
+        self.assertEqual(descriptor1.type, TYPE1)
+        self.assertEqual(descriptor1.description, DESCRIPTION1)
+
+        self.assertEqual(descriptor2.name, NAME2)
+        self.assertEqual(descriptor2.type, TYPE2)
+        self.assertEqual(descriptor2.description, DESCRIPTION2)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + PATH,
+                            'query_params': {}}
+        self.assertEqual(request, expected_request)
+
+    def test_list_paged(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
+            project=PROJECT)
+
+        TYPE1 = 'custom.googleapis.com/resource-1'
+        DESCRIPTION1 = 'This is the first resource.'
+        NAME1 = PATH + TYPE1
+        RESOURCE_DESCRIPTOR1 = {
+            'name': NAME1,
+            'type': TYPE1,
+            'description': DESCRIPTION1,
+        }
+
+        TYPE2 = 'custom.googleapis.com/resource-2'
+        DESCRIPTION2 = 'This is the second resource.'
+        NAME2 = PATH + TYPE2
+        RESOURCE_DESCRIPTOR2 = {
+            'name': NAME2,
+            'type': TYPE2,
+            'description': DESCRIPTION2,
+        }
+
+        TOKEN = 'second-page-please'
+        RESPONSE1 = {
+            'resourceDescriptors': [RESOURCE_DESCRIPTOR1],
+            'nextPageToken': TOKEN,
+        }
+        RESPONSE2 = {
+            'resourceDescriptors': [RESOURCE_DESCRIPTOR2],
+        }
+
+        connection = _Connection(RESPONSE1, RESPONSE2)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptors = self._getTargetClass()._list(client)
+
+        self.assertEqual(len(descriptors), 2)
+        descriptor1, descriptor2 = descriptors
+
+        self.assertEqual(descriptor1.name, NAME1)
+        self.assertEqual(descriptor1.type, TYPE1)
+        self.assertEqual(descriptor1.description, DESCRIPTION1)
+
+        self.assertEqual(descriptor2.name, NAME2)
+        self.assertEqual(descriptor2.type, TYPE2)
+        self.assertEqual(descriptor2.description, DESCRIPTION2)
+
+        request1, request2 = connection._requested
+        expected_request1 = {'method': 'GET', 'path': '/' + PATH,
+                             'query_params': {}}
+        expected_request2 = {'method': 'GET', 'path': '/' + PATH,
+                             'query_params': {'pageToken': TOKEN}}
+        self.assertEqual(request1, expected_request1)
+        self.assertEqual(request2, expected_request2)
+
+    def test_list_filtered(self):
+        PROJECT = 'my-project'
+        PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
+            project=PROJECT)
+
+        # Request only resources with type names that start with "foobar_".
+        FILTER = 'resource.type = starts_with("foobar_")'
+
+        # But there are none.
+        RESPONSE = {'resourceDescriptors': []}
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        descriptors = self._getTargetClass()._list(client, filter=FILTER)
+
+        self.assertEqual(len(descriptors), 0)
+
+        request, = connection._requested
+        expected_request = {'method': 'GET', 'path': '/' + PATH,
+                            'query_params': {'filter': FILTER}}
+        self.assertEqual(request, expected_request)
+
+
+class TestResource(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.resource import Resource
+        return Resource
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        TYPE = 'gce_instance'
+        LABELS = {
+            'project_id': 'my-project',
+            'instance_id': '1234567890123456789',
+            'zone': 'us-central1-a',
+        }
+        resource = self._makeOne(type=TYPE, labels=LABELS)
+        self.assertEqual(resource.type, TYPE)
+        self.assertEqual(resource.labels, LABELS)
+
+    def test_from_dict(self):
+        TYPE = 'gce_instance'
+        LABELS = {
+            'project_id': 'my-project',
+            'instance_id': '1234567890123456789',
+            'zone': 'us-central1-a',
+        }
+        info = {
+            'type': TYPE,
+            'labels': LABELS,
+        }
+        resource = self._getTargetClass()._from_dict(info)
+        self.assertEqual(resource.type, TYPE)
+        self.assertEqual(resource.labels, LABELS)
+
+    def test_from_dict_defaults(self):
+        info = {}
+        resource = self._getTargetClass()._from_dict(info)
+        self.assertEqual(resource.type, '')
+        self.assertEqual(resource.labels, {})
+
+
+class _Connection(object):
+
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self._requested = []
+
+    def api_request(self, **kwargs):
+        from gcloud.exceptions import NotFound
+        self._requested.append(kwargs)
+        try:
+            return self._responses.pop(0)
+        except IndexError:  # pragma: NO COVER
+            raise NotFound('miss')
+
+
+class _Client(object):
+
+    def __init__(self, project, connection):
+        self.project = project
+        self.connection = connection
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index f9f087c54a67..6f0e0880501a 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -320,7 +320,8 @@ def iter(self, headers_only=False, _page_size=None):
         :returns: Time series objects, containing points ordered from oldest
             to newest.
         """
-        path = '/projects/{}/timeSeries'.format(self._client.project)
+        path = '/projects/{project}/timeSeries'.format(
+            project=self._client.project)
 
         def _fragments():
             page_token = None

From 702f874c2a9cf0ae9bcf6808c147f33481d59422 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Mon, 4 Apr 2016 21:11:49 -0400
Subject: [PATCH 05/61] Added some links to the documentation, and a comment.

---
 gcloud/monitoring/client.py     | 25 ++++++++++++++++-------
 gcloud/monitoring/label.py      |  6 +++++-
 gcloud/monitoring/metric.py     | 12 +++++++++--
 gcloud/monitoring/resource.py   | 12 +++++++++--
 gcloud/monitoring/timeseries.py | 36 ++++++++++++++++++++++++++-------
 5 files changed, 72 insertions(+), 19 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 33062132c38f..4a72b5b9d65d 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Client for interacting with the Google Monitoring API.
+"""Client for interacting with the `Google Monitoring API (V3)`_.
 
 Example::
 
@@ -24,8 +24,7 @@
 At present, the client supports querying of time series, metric descriptors,
 and monitored resource descriptors.
 
-See the documentation for
-`Google Monitoring API V3 <https://cloud.google.com/monitoring/api/>`_.
+.. _Google Monitoring API (V3): https://cloud.google.com/monitoring/api/
 """
 
 from gcloud.client import JSONClient
@@ -73,11 +72,13 @@ def query(self,
         :param metric_type: The metric type name. The default value is
             ``"compute.googleapis.com/instance/cpu/utilization"``, but
             please note that this default value is provided only for
-            demonstration purposes and is subject to change.
+            demonstration purposes and is subject to change. See the
+            `supported metrics`_.
 
         :type resource_type: string
         :param resource_type: An optional resource type to filter by.
-            For example: ``"gce_instance"``
+            For example: ``"gce_instance"``. See the `defined resource
+            types`_.
 
         :type end_time: :class:`datetime.datetime` or string or None
         :param end_time: The end time (inclusive) of the time interval
@@ -107,6 +108,10 @@ def query(self,
 
         :rtype: :class:`~gcloud.monitoring.timeseries.Query`
         :returns: The query object.
+
+        .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
+        .. _defined resource types:
+            https://cloud.google.com/monitoring/api/v3/monitored-resources
         """
         return Query(self, metric_type, resource_type,
                      end_time=end_time, start_time=start_time,
@@ -140,10 +145,13 @@ def list_metric_descriptors(self, filter=None):
 
         :type filter: string or None
         :param filter: An optional filter string describing the metric
-                       descriptors to be returned.
+            descriptors to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`~gcloud.monitoring.metric.MetricDescriptor`
         :returns: A list of metric descriptor instances.
+
+        .. _filter documentation:
+            https://cloud.google.com/monitoring/api/v3/filters
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
         return MetricDescriptor._list(self, filter)
@@ -175,10 +183,13 @@ def list_resource_descriptors(self, filter=None):
 
         :type filter: string or None
         :param filter: An optional filter string describing the resource
-                       descriptors to be returned.
+            descriptors to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`~gcloud.monitoring.resource.ResourceDescriptor`
         :returns: A list of resource descriptor instances.
+
+        .. _filter documentation:
+            https://cloud.google.com/monitoring/api/v3/filters
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
         return ResourceDescriptor._list(self, filter)
diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
index 0439abfa41e2..b25d55d2c4e1 100644
--- a/gcloud/monitoring/label.py
+++ b/gcloud/monitoring/label.py
@@ -12,7 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Label Descriptors for the Google Monitoring API."""
+"""Label Descriptors for the `Google Monitoring API (V3)`_.
+
+.. _Google Monitoring API (V3):
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/LabelDescriptor
+"""
 
 import collections
 
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 3446c87bde86..96c9c0e8fd46 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -12,7 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Metric Descriptors for the Google Monitoring API."""
+"""Metric Descriptors for the `Google Monitoring API (V3)`_.
+
+.. _Google Monitoring API (V3):
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.metricDescriptors
+"""
 
 # Features intentionally omitted from this first version of the client library:
 #   - Creating and deleting metric descriptors.
@@ -91,10 +96,13 @@ def _list(cls, client, filter=None):
 
         :type filter: string or None
         :param filter: An optional filter string describing the metric
-                       descriptors to be returned.
+            descriptors to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`MetricDescriptor`
         :returns: A list of metric descriptor instances.
+
+        .. _filter documentation:
+            https://cloud.google.com/monitoring/api/v3/filters
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
 
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index b5fcd9dc943e..a9170b2ed0ab 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -12,7 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Resource Descriptors for the Google Monitoring API."""
+"""Resource Descriptors for the `Google Monitoring API (V3)`_.
+
+.. _Google Monitoring API (V3):
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.monitoredResourceDescriptors
+"""
 
 import collections
 
@@ -79,10 +84,13 @@ def _list(cls, client, filter=None):
 
         :type filter: string or None
         :param filter: An optional filter string describing the resource
-                       descriptors to be returned.
+            descriptors to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`ResourceDescriptor`
         :returns: A list of resource descriptor instances.
+
+        .. _filter documentation:
+            https://cloud.google.com/monitoring/api/v3/filters
         """
         # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
 
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 6f0e0880501a..b04642c442cf 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -12,7 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Time series in the Google Monitoring API."""
+"""Time series in the `Google Monitoring API (V3)`_.
+
+.. _Google Monitoring API (V3):
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries
+"""
 
 # Features intentionally omitted from this first version of the client library:
 #   - Creating time series.
@@ -51,11 +55,13 @@ class Query(object):
     :param metric_type: The metric type name. The default value is
         ``"compute.googleapis.com/instance/cpu/utilization"``, but
         please note that this default value is provided only for
-        demonstration purposes and is subject to change.
+        demonstration purposes and is subject to change. See the
+        `supported metrics`_.
 
     :type resource_type: string
     :param resource_type: An optional resource type to filter by.
-        For example: ``"gce_instance"``
+        For example: ``"gce_instance"``. See the `defined resource
+        types`_.
 
     :type end_time: :class:`datetime.datetime` or string or None
     :param end_time: The end time (inclusive) of the time interval
@@ -82,6 +88,10 @@ class Query(object):
 
     :type minutes: integer
     :param minutes: The number of minutes in the time interval.
+
+    .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
+    .. _defined resource types:
+        https://cloud.google.com/monitoring/api/v3/monitored-resources
     """
 
     DEFAULT_METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
@@ -252,8 +262,9 @@ def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
             query = query.align('ALIGN_MEAN', minutes=5)
 
         :type per_series_aligner: string
-        :param per_series_aligner: The approach to be used to align individual
-            time series. For example: ``"ALIGN_MEAN"``
+        :param per_series_aligner: The approach to be used to align
+            individual time series. For example: ``"ALIGN_MEAN"``.
+            See the `supported aligners`_.
 
         :type seconds: integer
         :param seconds: The number of seconds in the alignment period.
@@ -266,6 +277,10 @@ def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
 
         :rtype: :class:`Query`
         :returns: The new query object.
+
+        .. _supported aligners:
+            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+            projects.timeSeries/list#Aligner
         """
         new_query = self.copy()
         new_query._per_series_aligner = per_series_aligner
@@ -277,8 +292,9 @@ def reduce(self, cross_series_reducer, group_by_fields=()):
         """Copy the query and add cross-series reduction.
 
         :type cross_series_reducer: string
-        :param cross_series_reducer: The approach to be used to combine time
-            series. For example: ``"REDUCE_MEAN"``
+        :param cross_series_reducer: The approach to be used to combine
+            time series. For example: ``"REDUCE_MEAN"``.
+            See the `supported reducers`_.
 
         :type group_by_fields: string or list of strings
         :param group_by_fields: An optional field or set of fields
@@ -288,6 +304,10 @@ def reduce(self, cross_series_reducer, group_by_fields=()):
 
         :rtype: :class:`Query`
         :returns: The new query object.
+
+        .. _supported reducers:
+            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+            projects.timeSeries/list#Reducer
         """
         if isinstance(group_by_fields, six.string_types):
             group_by_fields = [group_by_fields]
@@ -499,6 +519,8 @@ def copy(self):
         :rtype: :class:`Query`
         :returns: The new query object.
         """
+        # Using copy.deepcopy() would be appropriate, except that we want
+        # to copy self._client only as a reference.
         new_query = copy.copy(self)
         new_query._filter = copy.copy(self._filter)
         return new_query

From 80843b09c7d51614054bc547b43c2aef4e377ed8 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 5 Apr 2016 18:43:17 -0400
Subject: [PATCH 06/61] Dropped two nested generators.

---
 gcloud/monitoring/metric.py   | 33 +++++++++++++++++----------------
 gcloud/monitoring/resource.py | 33 +++++++++++++++++----------------
 2 files changed, 34 insertions(+), 32 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 96c9c0e8fd46..bec29cde3e2e 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -109,27 +109,28 @@ def _list(cls, client, filter=None):
         path = '/projects/{project}/metricDescriptors/'.format(
             project=client.project)
 
-        def _descriptors():
-            page_token = None
-            while True:
-                params = {}
+        descriptors = []
 
-                if filter is not None:
-                    params['filter'] = filter
+        page_token = None
+        while True:
+            params = {}
 
-                if page_token is not None:
-                    params['pageToken'] = page_token
+            if filter is not None:
+                params['filter'] = filter
 
-                response = client.connection.api_request(
-                    method='GET', path=path, query_params=params)
-                for info in response.get('metricDescriptors', []):
-                    yield cls._from_dict(info)
+            if page_token is not None:
+                params['pageToken'] = page_token
 
-                page_token = response.get('nextPageToken')
-                if not page_token:
-                    break
+            response = client.connection.api_request(
+                method='GET', path=path, query_params=params)
+            for info in response.get('metricDescriptors', []):
+                descriptors.append(cls._from_dict(info))
 
-        return list(_descriptors())
+            page_token = response.get('nextPageToken')
+            if not page_token:
+                break
+
+        return descriptors
 
     @classmethod
     def _from_dict(cls, info):
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index a9170b2ed0ab..9441253e71f6 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -97,27 +97,28 @@ def _list(cls, client, filter=None):
         path = '/projects/{project}/monitoredResourceDescriptors/'.format(
             project=client.project)
 
-        def _descriptors():
-            page_token = None
-            while True:
-                params = {}
+        descriptors = []
 
-                if filter is not None:
-                    params['filter'] = filter
+        page_token = None
+        while True:
+            params = {}
 
-                if page_token is not None:
-                    params['pageToken'] = page_token
+            if filter is not None:
+                params['filter'] = filter
 
-                response = client.connection.api_request(
-                    method='GET', path=path, query_params=params)
-                for info in response.get('resourceDescriptors', []):
-                    yield cls._from_dict(info)
+            if page_token is not None:
+                params['pageToken'] = page_token
 
-                page_token = response.get('nextPageToken')
-                if not page_token:
-                    break
+            response = client.connection.api_request(
+                method='GET', path=path, query_params=params)
+            for info in response.get('resourceDescriptors', []):
+                descriptors.append(cls._from_dict(info))
 
-        return list(_descriptors())
+            page_token = response.get('nextPageToken')
+            if not page_token:
+                break
+
+        return descriptors
 
     @classmethod
     def _from_dict(cls, info):

From 1d4fcaa376959e153f8e3a367429350fc009c332 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 5 Apr 2016 19:01:32 -0400
Subject: [PATCH 07/61] Require start time and end time to be datetimes rather
 than strings.

---
 gcloud/monitoring/client.py     | 20 ++++++++------------
 gcloud/monitoring/timeseries.py | 28 ++++++++++------------------
 2 files changed, 18 insertions(+), 30 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 4a72b5b9d65d..6ca03c075b4c 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -80,22 +80,18 @@ def query(self,
             For example: ``"gce_instance"``. See the `defined resource
             types`_.
 
-        :type end_time: :class:`datetime.datetime` or string or None
+        :type end_time: :class:`datetime.datetime` or None
         :param end_time: The end time (inclusive) of the time interval
             for which results should be returned, as a datetime object.
-            The default is the start of the current minute. If the
-            ``days``/``hours``/``minutes`` parameters are not used, the
-            end time can alternatively be provided as a timestamp string
-            in RFC3339 UTC "Zulu" format.
+            The default is the start of the current minute.
 
-        :type start_time: :class:`datetime.datetime` or string or None
+        :type start_time: :class:`datetime.datetime` or None
         :param start_time: An optional start time (exclusive) of the time
-            interval for which results should be returned, as either a
-            datetime object or a timestamp string. If omitted and no
-            non-zero duration is specified, the interval is a point in
-            time. If any of ``days``, ``hours``, or ``minutes`` is non-zero,
-            these are combined and subtracted from the end time to determine
-            the start time.
+            interval for which results should be returned, as a datetime
+            object. If omitted and no non-zero duration is specified, the
+            interval is a point in time. If any of ``days``, ``hours``,
+            or ``minutes`` is non-zero, these are combined and subtracted
+            from the end time to determine the start time.
 
         :type days: integer
         :param days: The number of days in the time interval.
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index b04642c442cf..aab8036946c6 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -63,22 +63,18 @@ class Query(object):
         For example: ``"gce_instance"``. See the `defined resource
         types`_.
 
-    :type end_time: :class:`datetime.datetime` or string or None
+    :type end_time: :class:`datetime.datetime` or None
     :param end_time: The end time (inclusive) of the time interval
         for which results should be returned, as a datetime object.
-        The default is the start of the current minute. If the
-        ``days``/``hours``/``minutes`` parameters are not used, the
-        end time can alternatively be provided as a timestamp string
-        in RFC3339 UTC "Zulu" format.
+        The default is the start of the current minute.
 
-    :type start_time: :class:`datetime.datetime` or string or None
+    :type start_time: :class:`datetime.datetime` or None
     :param start_time: An optional start time (exclusive) of the time
-        interval for which results should be returned, as either a
-        datetime object or a timestamp string. If omitted and no
-        non-zero duration is specified, the interval is a point in
-        time. If any of ``days``, ``hours``, or ``minutes`` is non-zero,
-        these are combined and subtracted from the end time to determine
-        the start time.
+        interval for which results should be returned, as a datetime
+        object. If omitted and no non-zero duration is specified, the
+        interval is a point in time. If any of ``days``, ``hours``,
+        or ``minutes`` is non-zero, these are combined and subtracted
+        from the end time to determine the start time.
 
     :type days: integer
     :param days: The number of days in the time interval.
@@ -711,17 +707,13 @@ def _sorted_resource_labels(labels):
 def _format_timestamp(timestamp):
     """Convert a datetime object to a string as required by the API.
 
-    :type timestamp: :class:`datetime.datetime` or string
-    :param timestamp: A :class:`~datetime.datetime` or a timestamp string
-        in RFC3339 UTC "Zulu" format.
+    :type timestamp: :class:`datetime.datetime`
+    :param timestamp: A datetime object.
 
     :rtype: string
     :returns: The formatted timestamp. For example:
         ``"2016-02-17T19:18:01.763000Z"``
     """
-    if isinstance(timestamp, six.string_types):
-        return timestamp
-
     if timestamp.tzinfo is not None:
         # Convert to UTC and remove the time zone info.
         timestamp = timestamp.replace(tzinfo=None) - timestamp.utcoffset()

From a5bab4474cfeb4bc6f8f13dcdd54715c0f85a98c Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 5 Apr 2016 22:18:25 -0400
Subject: [PATCH 08/61] Change how query intervals are specified.

1. Removed start_time from the query constructor/factory.
2. Added a select_interval() method for when you actually
   do have a start time in your hands, or for when you want
   to set the time interval on an existing query object.
---
 gcloud/monitoring/client.py     | 24 ++++++++-----
 gcloud/monitoring/timeseries.py | 60 ++++++++++++++++++++++++---------
 2 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 6ca03c075b4c..6b607ecbfcdc 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -59,7 +59,7 @@ class Client(JSONClient):
     def query(self,
               metric_type=Query.DEFAULT_METRIC_TYPE,
               resource_type=None,
-              end_time=None, start_time=None,
+              end_time=None,
               days=0, hours=0, minutes=0):
         """Construct a query object for listing time series.
 
@@ -85,13 +85,14 @@ def query(self,
             for which results should be returned, as a datetime object.
             The default is the start of the current minute.
 
-        :type start_time: :class:`datetime.datetime` or None
-        :param start_time: An optional start time (exclusive) of the time
-            interval for which results should be returned, as a datetime
-            object. If omitted and no non-zero duration is specified, the
-            interval is a point in time. If any of ``days``, ``hours``,
-            or ``minutes`` is non-zero, these are combined and subtracted
-            from the end time to determine the start time.
+            The start time (exclusive) is determined by combining the
+            values of  ``days``, ``hours``, and ``minutes``, and
+            subtracting the resulting duration from the end time.
+
+            It is also allowed to omit the end time and duration here,
+            in which case
+            :meth:`~gcloud.monitoring.timeseries.Query.select_interval`
+            must be called before the query is executed.
 
         :type days: integer
         :param days: The number of days in the time interval.
@@ -105,12 +106,17 @@ def query(self,
         :rtype: :class:`~gcloud.monitoring.timeseries.Query`
         :returns: The query object.
 
+        :raises: :exc:`ValueError` if ``end_time`` is specified but
+            ``days``, ``hours``, and ``minutes`` are all zero.
+            If you really want to specify a point in time, use
+            :meth:`~gcloud.monitoring.timeseries.Query.select_interval`.
+
         .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
         .. _defined resource types:
             https://cloud.google.com/monitoring/api/v3/monitored-resources
         """
         return Query(self, metric_type, resource_type,
-                     end_time=end_time, start_time=start_time,
+                     end_time=end_time,
                      days=days, hours=hours, minutes=minutes)
 
     def fetch_metric_descriptor(self, metric_type):
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index aab8036946c6..8c5b8c738c55 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -68,13 +68,14 @@ class Query(object):
         for which results should be returned, as a datetime object.
         The default is the start of the current minute.
 
-    :type start_time: :class:`datetime.datetime` or None
-    :param start_time: An optional start time (exclusive) of the time
-        interval for which results should be returned, as a datetime
-        object. If omitted and no non-zero duration is specified, the
-        interval is a point in time. If any of ``days``, ``hours``,
-        or ``minutes`` is non-zero, these are combined and subtracted
-        from the end time to determine the start time.
+        The start time (exclusive) is determined by combining the
+        values of  ``days``, ``hours``, and ``minutes``, and
+        subtracting the resulting duration from the end time.
+
+        It is also allowed to omit the end time and duration here,
+        in which case
+        :meth:`~gcloud.monitoring.timeseries.Query.select_interval`
+        must be called before the query is executed.
 
     :type days: integer
     :param days: The number of days in the time interval.
@@ -85,6 +86,11 @@ class Query(object):
     :type minutes: integer
     :param minutes: The number of minutes in the time interval.
 
+    :raises: :exc:`ValueError` if ``end_time`` is specified but
+        ``days``, ``hours``, and ``minutes`` are all zero.
+        If you really want to specify a point in time, use
+        :meth:`~gcloud.monitoring.timeseries.Query.select_interval`.
+
     .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
     .. _defined resource types:
         https://cloud.google.com/monitoring/api/v3/monitored-resources
@@ -94,18 +100,17 @@ class Query(object):
 
     def __init__(self, client,
                  metric_type=DEFAULT_METRIC_TYPE, resource_type=None,
-                 end_time=None, start_time=None,
-                 days=0, hours=0, minutes=0):
-        if end_time is None:
-            end_time = datetime.datetime.utcnow().replace(second=0,
-                                                          microsecond=0)
-
+                 end_time=None, days=0, hours=0, minutes=0):
+        start_time = None
         if days or hours or minutes:
-            if start_time is not None:
-                raise ValueError('Duration and start time both specified.')
+            if end_time is None:
+                end_time = datetime.datetime.utcnow().replace(second=0,
+                                                              microsecond=0)
             start_time = end_time - datetime.timedelta(days=days,
                                                        hours=hours,
                                                        minutes=minutes)
+        elif end_time is not None:
+            raise ValueError('Non-zero duration required for time interval.')
 
         self._client = client
         self._end_time = end_time
@@ -130,6 +135,26 @@ def filter(self):
         """
         return str(self._filter)
 
+    def select_interval(self, end_time, start_time=None):
+        """Copy the query and set the query time interval.
+
+        :type end_time: :class:`datetime.datetime`
+        :param end_time: The end time (inclusive) of the time interval
+            for which results should be returned, as a datetime object.
+
+        :type start_time: :class:`datetime.datetime` or None
+        :param start_time: The start time (exclusive) of the time interval
+            for which results should be returned, as a datetime object.
+            If not specified, the interval is a point in time.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._end_time = end_time
+        new_query._start_time = start_time
+        return new_query
+
     def select_group(self, group_id):
         """Copy the query and add filtering by group.
 
@@ -335,7 +360,12 @@ def iter(self, headers_only=False, _page_size=None):
         :rtype: iterator over :class:`TimeSeries`
         :returns: Time series objects, containing points ordered from oldest
             to newest.
+        :raises: :exc:`ValueError` if the query time interval has not been
+            specified.
         """
+        if self._end_time is None:
+            raise ValueError('Query time interval not specified.')
+
         path = '/projects/{project}/timeSeries'.format(
             project=self._client.project)
 

From 3b88363f9b3224df062ca52a752cd1e2b51432c6 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Wed, 6 Apr 2016 01:11:05 -0400
Subject: [PATCH 09/61] Change how one filters on the resource type.

Several related changes:

 - Removed resource_type from the constructor/factory parameters.
 - Added support for filtering on "resource_type" as a pseudo-label.
 - Renamed select_resource_labels() to select_resources() and
   select_metric_labels() to select_metrics().
---
 gcloud/monitoring/client.py     |  10 +---
 gcloud/monitoring/timeseries.py | 101 ++++++++++++++++----------------
 2 files changed, 53 insertions(+), 58 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 6b607ecbfcdc..5a9054c94ca7 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -58,7 +58,6 @@ class Client(JSONClient):
 
     def query(self,
               metric_type=Query.DEFAULT_METRIC_TYPE,
-              resource_type=None,
               end_time=None,
               days=0, hours=0, minutes=0):
         """Construct a query object for listing time series.
@@ -75,11 +74,6 @@ def query(self,
             demonstration purposes and is subject to change. See the
             `supported metrics`_.
 
-        :type resource_type: string
-        :param resource_type: An optional resource type to filter by.
-            For example: ``"gce_instance"``. See the `defined resource
-            types`_.
-
         :type end_time: :class:`datetime.datetime` or None
         :param end_time: The end time (inclusive) of the time interval
             for which results should be returned, as a datetime object.
@@ -112,10 +106,8 @@ def query(self,
             :meth:`~gcloud.monitoring.timeseries.Query.select_interval`.
 
         .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
-        .. _defined resource types:
-            https://cloud.google.com/monitoring/api/v3/monitored-resources
         """
-        return Query(self, metric_type, resource_type,
+        return Query(self, metric_type,
                      end_time=end_time,
                      days=days, hours=hours, minutes=minutes)
 
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 8c5b8c738c55..74af9e592b2a 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -58,11 +58,6 @@ class Query(object):
         demonstration purposes and is subject to change. See the
         `supported metrics`_.
 
-    :type resource_type: string
-    :param resource_type: An optional resource type to filter by.
-        For example: ``"gce_instance"``. See the `defined resource
-        types`_.
-
     :type end_time: :class:`datetime.datetime` or None
     :param end_time: The end time (inclusive) of the time interval
         for which results should be returned, as a datetime object.
@@ -92,14 +87,12 @@ class Query(object):
         :meth:`~gcloud.monitoring.timeseries.Query.select_interval`.
 
     .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
-    .. _defined resource types:
-        https://cloud.google.com/monitoring/api/v3/monitored-resources
     """
 
     DEFAULT_METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
 
     def __init__(self, client,
-                 metric_type=DEFAULT_METRIC_TYPE, resource_type=None,
+                 metric_type=DEFAULT_METRIC_TYPE,
                  end_time=None, days=0, hours=0, minutes=0):
         start_time = None
         if days or hours or minutes:
@@ -115,7 +108,7 @@ def __init__(self, client,
         self._client = client
         self._end_time = end_time
         self._start_time = start_time
-        self._filter = _Filter(metric_type, resource_type)
+        self._filter = _Filter(metric_type)
 
         self._per_series_aligner = None
         self._alignment_period_seconds = None
@@ -189,13 +182,14 @@ def select_projects(self, *args):
         new_query._filter.projects = args
         return new_query
 
-    def select_resource_labels(self, *args, **kwargs):
+    def select_resources(self, *args, **kwargs):
         """Copy the query and add filtering by resource labels.
 
         Examples::
 
-            query = query.select_resource_labels(zone='us-central1-a')
-            query = query.select_resource_labels(zone_prefix='europe-')
+            query = query.select_resources(zone='us-central1-a')
+            query = query.select_resources(zone_prefix='europe-')
+            query = query.select_resources(resource_type='gce_instance')
 
         A keyword argument ``<label>=<value>`` ordinarily generates a filter
         expression of the form::
@@ -213,11 +207,19 @@ def select_resource_labels(self, *args, **kwargs):
 
             resource.label.<label> = ends_with("<value>")
 
+        As a special case, ``"resource_type"`` is treated as a special
+        pseudo-label corresponding to the filter object ``resource.type``.
+        For example, ``resource_type=<value>`` generates::
+
+            resource.type = "<value>"
+
+        See the `defined resource types`_.
+
         .. note::
 
-            The label ``"instance_name"`` is a metric label, not a
-            resource label. Use ``select_metric_labels(instance_name=...)``,
-            not this method.
+            The label ``"instance_name"`` is a metric label,
+            not a resource label. You would filter on it using
+            ``select_metrics(instance_name=...)``.
 
         :param args: Raw filter expression strings to include in the
             conjunction. If just one is provided and no keyword arguments
@@ -228,19 +230,21 @@ def select_resource_labels(self, *args, **kwargs):
 
         :rtype: :class:`Query`
         :returns: The new query object.
+
+        .. _defined resource types:
+            https://cloud.google.com/monitoring/api/v3/monitored-resources
         """
         new_query = self.copy()
-        new_query._filter.select_resource_labels(*args, **kwargs)
+        new_query._filter.select_resources(*args, **kwargs)
         return new_query
 
-    def select_metric_labels(self, *args, **kwargs):
+    def select_metrics(self, *args, **kwargs):
         """Copy the query and add filtering by metric labels.
 
         Examples::
 
-            query = query.select_metric_labels(instance_name='myinstance')
-            query = query.select_metric_labels(
-                instance_name_prefix='mycluster-')
+            query = query.select_metrics(instance_name='myinstance')
+            query = query.select_metrics(instance_name_prefix='mycluster-')
 
         A keyword argument ``<label>=<value>`` ordinarily generates a filter
         expression of the form::
@@ -269,7 +273,7 @@ def select_metric_labels(self, *args, **kwargs):
         :returns: The new query object.
         """
         new_query = self.copy()
-        new_query._filter.select_metric_labels(*args, **kwargs)
+        new_query._filter.select_metrics(*args, **kwargs)
         return new_query
 
     def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
@@ -656,34 +660,31 @@ def _from_dict(cls, info):
 class _Filter(object):
     """Helper for assembling a filter string."""
 
-    def __init__(self, metric_type, resource_type=None):
+    def __init__(self, metric_type):
         self.metric_type = metric_type
-        self.resource_type = resource_type
         self.group_id = None
         self.projects = ()
         self.resource_label_filter = None
         self.metric_label_filter = None
 
-    def select_resource_labels(self, *args, **kwargs):
+    def select_resources(self, *args, **kwargs):
         """Select by resource labels.
 
-        See :meth:`Query.select_resource_labels`.
+        See :meth:`Query.select_resources`.
         """
         self.resource_label_filter = _build_label_filter('resource',
                                                          *args, **kwargs)
 
-    def select_metric_labels(self, *args, **kwargs):
+    def select_metrics(self, *args, **kwargs):
         """Select by metric labels.
 
-        See :meth:`Query.select_metric_labels`.
+        See :meth:`Query.select_metrics`.
         """
         self.metric_label_filter = _build_label_filter('metric',
                                                        *args, **kwargs)
 
     def __str__(self):
         filters = ['metric.type = "{}"'.format(self.metric_type)]
-        if self.resource_type is not None:
-            filters.append('resource.type = "{}"'.format(self.resource_type))
         if self.group_id is not None:
             filters.append('group.id = "{}"'.format(self.group_id))
         if self.projects:
@@ -701,29 +702,31 @@ def __str__(self):
 
 def _build_label_filter(category, *args, **kwargs):
     """Construct a filter string to filter on metric or resource labels."""
-    def _strip_suffix(key):
-        return key.rsplit('_', 1)[0]
+    terms = list(args)
+    for key in kwargs:
+        value = kwargs[key]
+        if value is None:
+            continue
+
+        suffix = None
+        if key.endswith('_prefix') or key.endswith('_suffix'):
+            key, suffix = key.rsplit('_', 1)
+
+        if category == 'resource' and key == 'resource_type':
+            key = 'resource.type'
+        else:
+            key = '.'.join((category, 'label', key))
 
-    def _terms():
-        for arg in args:
-            yield arg
+        if suffix == 'prefix':
+            term = '{} = starts_with("{}")'
+        elif suffix == 'suffix':
+            term = '{} = ends_with("{}")'
+        else:
+            term = '{} = "{}"'
 
-        for key in kwargs:
-            value = kwargs[key]
-            if value is None:
-                continue
+        terms.append(term.format(key, value))
 
-            key = '.'.join((category, 'label', key))
-            if key.endswith('_prefix'):
-                yield '{} = starts_with("{}")'.format(
-                    _strip_suffix(key), value)
-            elif key.endswith('_suffix'):
-                yield '{} = ends_with("{}")'.format(
-                    _strip_suffix(key), value)
-            else:
-                yield '{} = "{}"'.format(key, value)
-
-    return ' AND '.join(sorted(_terms()))
+    return ' AND '.join(sorted(terms))
 
 
 def _sorted_resource_labels(labels):

From a1959b3906932c532230c722732b44974ca3c48d Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Wed, 6 Apr 2016 13:38:23 -0400
Subject: [PATCH 10/61] Add some pseudo-enums providing constants you can use
 if you wish.

---
 gcloud/monitoring/label.py       | 15 ++++++++++++-
 gcloud/monitoring/metric.py      | 29 +++++++++++++++++++++++++
 gcloud/monitoring/test_label.py  | 17 ++++++++++++++-
 gcloud/monitoring/test_metric.py | 30 ++++++++++++++++++++++++++
 gcloud/monitoring/timeseries.py  | 36 ++++++++++++++++++++++++++++++++
 5 files changed, 125 insertions(+), 2 deletions(-)

diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
index b25d55d2c4e1..58327d1f05a8 100644
--- a/gcloud/monitoring/label.py
+++ b/gcloud/monitoring/label.py
@@ -21,6 +21,19 @@
 import collections
 
 
+class LabelValueType(object):
+    """Allowed values for the `type of a label`_.
+
+    .. _type of a label:
+        https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+        LabelDescriptor#ValueType
+    """
+
+    STRING = 'STRING'
+    BOOL = 'BOOL'
+    INT64 = 'INT64'
+
+
 class LabelDescriptor(collections.namedtuple('LabelDescriptor',
                                              'key value_type description')):
     """Schema specification and documentation for a single label.
@@ -50,6 +63,6 @@ def _from_dict(cls, info):
         """
         return cls(
             info.get('key', ''),
-            info.get('valueType', 'STRING'),
+            info.get('valueType', LabelValueType.STRING),
             info.get('description', ''),
         )
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index bec29cde3e2e..9413e15d5d09 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -27,6 +27,35 @@
 from gcloud.monitoring.label import LabelDescriptor
 
 
+class MetricKind(object):
+    """Allowed values for the `kind of measurement`_.
+
+    .. _kind of measurement:
+        https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+        projects.metricDescriptors#MetricKind
+    """
+
+    GAUGE = 'GAUGE'
+    DELTA = 'DELTA'
+    CUMULATIVE = 'CUMULATIVE'
+
+
+class ValueType(object):
+    """Allowed values for the `metric value type`_.
+
+    .. _metric value type:
+        https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+        projects.metricDescriptors#ValueType
+    """
+
+    BOOL = 'BOOL'
+    INT64 = 'INT64'
+    DOUBLE = 'DOUBLE'
+    STRING = 'STRING'
+    DISTRIBUTION = 'DISTRIBUTION'
+    MONEY = 'MONEY'
+
+
 class MetricDescriptor(collections.namedtuple(
         'MetricDescriptor', ('name type labels metric_kind value_type unit'
                              ' description display_name'))):
diff --git a/gcloud/monitoring/test_label.py b/gcloud/monitoring/test_label.py
index e85919e9bd80..ede78ce9748e 100644
--- a/gcloud/monitoring/test_label.py
+++ b/gcloud/monitoring/test_label.py
@@ -15,7 +15,22 @@
 import unittest2
 
 
-class TestLabel(unittest2.TestCase):
+class TestLabelValueType(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.label import LabelValueType
+        return LabelValueType
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(), 'STRING'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
+class TestLabelDescriptor(unittest2.TestCase):
 
     def _getTargetClass(self):
         from gcloud.monitoring.label import LabelDescriptor
diff --git a/gcloud/monitoring/test_metric.py b/gcloud/monitoring/test_metric.py
index d1ac313e2c8d..bbff3c215dbd 100644
--- a/gcloud/monitoring/test_metric.py
+++ b/gcloud/monitoring/test_metric.py
@@ -15,6 +15,36 @@
 import unittest2
 
 
+class TestMetricKind(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.metric import MetricKind
+        return MetricKind
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(), 'GAUGE'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
+class TestValueType(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.metric import ValueType
+        return ValueType
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(), 'DISTRIBUTION'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
 class TestMetricDescriptor(unittest2.TestCase):
 
     def _getTargetClass(self):
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 74af9e592b2a..d7f8400bee86 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -41,6 +41,42 @@
 ]
 
 
+class Aligner(object):
+    """Allowed values for the `supported aligners`_."""
+
+    ALIGN_NONE = 'ALIGN_NONE'
+    ALIGN_DELTA = 'ALIGN_DELTA'
+    ALIGN_RATE = 'ALIGN_RATE'
+    ALIGN_INTERPOLATE = 'ALIGN_INTERPOLATE'
+    ALIGN_NEXT_OLDER = 'ALIGN_NEXT_OLDER'
+    ALIGN_MIN = 'ALIGN_MIN'
+    ALIGN_MAX = 'ALIGN_MAX'
+    ALIGN_MEAN = 'ALIGN_MEAN'
+    ALIGN_COUNT = 'ALIGN_COUNT'
+    ALIGN_SUM = 'ALIGN_SUM'
+    ALIGN_STDDEV = 'ALIGN_STDDEV'
+    ALIGN_COUNT_TRUE = 'ALIGN_COUNT_TRUE'
+    ALIGN_FRACTION_TRUE = 'ALIGN_FRACTION_TRUE'
+
+
+class Reducer(object):
+    """Allowed values for the `supported reducers`_."""
+
+    REDUCE_NONE = 'REDUCE_NONE'
+    REDUCE_MEAN = 'REDUCE_MEAN'
+    REDUCE_MIN = 'REDUCE_MIN'
+    REDUCE_MAX = 'REDUCE_MAX'
+    REDUCE_SUM = 'REDUCE_SUM'
+    REDUCE_STDDEV = 'REDUCE_STDDEV'
+    REDUCE_COUNT = 'REDUCE_COUNT'
+    REDUCE_COUNT_TRUE = 'REDUCE_COUNT_TRUE'
+    REDUCE_FRACTION_TRUE = 'REDUCE_FRACTION_TRUE'
+    REDUCE_PERCENTILE_99 = 'REDUCE_PERCENTILE_99'
+    REDUCE_PERCENTILE_95 = 'REDUCE_PERCENTILE_95'
+    REDUCE_PERCENTILE_50 = 'REDUCE_PERCENTILE_50'
+    REDUCE_PERCENTILE_05 = 'REDUCE_PERCENTILE_05'
+
+
 class Query(object):
     """Query object for listing time series.
 

From ac12ade21d7caa512aa49efb2bb87a9cb96f3abd Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 7 Apr 2016 14:17:45 -0400
Subject: [PATCH 11/61] More unit tests, and a few related changes.

The signature of the reduce() method is now as follows:

    reduce(self, cross_series_reducer, *group_by_fields)
---
 gcloud/monitoring/test_client.py     | 106 +++-
 gcloud/monitoring/test_timeseries.py | 812 +++++++++++++++++++++++++++
 gcloud/monitoring/timeseries.py      | 115 ++--
 3 files changed, 973 insertions(+), 60 deletions(-)
 create mode 100644 gcloud/monitoring/test_timeseries.py

diff --git a/gcloud/monitoring/test_client.py b/gcloud/monitoring/test_client.py
index 14514222dff8..6c1c27fd14e6 100644
--- a/gcloud/monitoring/test_client.py
+++ b/gcloud/monitoring/test_client.py
@@ -14,6 +14,8 @@
 
 import unittest2
 
+PROJECT = 'my-project'
+
 
 class TestClient(unittest2.TestCase):
 
@@ -24,8 +26,107 @@ def _getTargetClass(self):
     def _makeOne(self, *args, **kwargs):
         return self._getTargetClass()(*args, **kwargs)
 
+    def test_query(self):
+        import datetime
+
+        START_TIME = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        END_TIME = datetime.datetime(2016, 4, 6, 22, 10, 0)
+        MINUTES = 5
+
+        METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
+        METRIC_LABELS = {'instance_name': 'instance-1'}
+        METRIC_LABELS2 = {'instance_name': 'instance-2'}
+
+        RESOURCE_TYPE = 'gce_instance'
+        RESOURCE_LABELS = {
+            'project_id': 'my-project',
+            'zone': 'us-east1-a',
+            'instance_id': '1234567890123456789',
+        }
+        RESOURCE_LABELS2 = {
+            'project_id': 'my-project',
+            'zone': 'us-east1-b',
+            'instance_id': '9876543210987654321',
+        }
+
+        METRIC_KIND = 'GAUGE'
+        VALUE_TYPE = 'DOUBLE'
+
+        TS1 = '2016-04-06T22:05:00.042Z'
+        TS2 = '2016-04-06T22:05:01.042Z'
+        TS3 = '2016-04-06T22:05:02.042Z'
+
+        VAL1 = 0.1
+        VAL2 = 0.2
+
+        def P(timestamp, value):
+            return {
+                'interval': {'startTime': timestamp, 'endTime': timestamp},
+                'value': {'doubleValue': value},
+            }
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [P(TS3, VAL1), P(TS2, VAL1), P(TS1, VAL1)],
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [P(TS3, VAL2), P(TS2, VAL2), P(TS1, VAL2)],
+        }
+
+        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
+
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        connection = client.connection = _Connection(RESPONSE)
+
+        # A simple query. In practice, it can be very convenient to let the
+        # end time default to the start of the current minute.
+        query = client.query(METRIC_TYPE, end_time=END_TIME, minutes=MINUTES)
+        response = list(query)
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.type, METRIC_TYPE)
+        self.assertEqual(series2.metric.type, METRIC_TYPE)
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+
+        self.assertEqual(series1.resource.type, RESOURCE_TYPE)
+        self.assertEqual(series2.resource.type, RESOURCE_TYPE)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual(series1.metric_kind, METRIC_KIND)
+        self.assertEqual(series2.metric_kind, METRIC_KIND)
+        self.assertEqual(series1.value_type, VALUE_TYPE)
+        self.assertEqual(series2.value_type, VALUE_TYPE)
+
+        self.assertEqual([p.value for p in series1.points], [VAL1, VAL1, VAL1])
+        self.assertEqual([p.value for p in series2.points], [VAL2, VAL2, VAL2])
+        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2, TS3])
+        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2, TS3])
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', END_TIME.isoformat() + 'Z'),
+                ('interval.startTime', START_TIME.isoformat() + 'Z'),
+            ],
+        }
+
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
     def test_fetch_metric_descriptor(self):
-        PROJECT = 'my-project'
         TYPE = 'custom.googleapis.com/my-metric'
         NAME = 'projects/{project}/metricDescriptors/{type}'.format(
             project=PROJECT, type=TYPE)
@@ -54,7 +155,6 @@ def test_fetch_metric_descriptor(self):
         self.assertEqual(request, expected_request)
 
     def test_list_metric_descriptors(self):
-        PROJECT = 'my-project'
         PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
 
         TYPE1 = 'custom.googleapis.com/my-metric-1'
@@ -106,7 +206,6 @@ def test_list_metric_descriptors(self):
         self.assertEqual(request, expected_request)
 
     def test_fetch_resource_descriptor(self):
-        PROJECT = 'my-project'
         TYPE = 'gce_instance'
         NAME = 'projects/{project}/monitoredResourceDescriptors/{type}'.format(
             project=PROJECT, type=TYPE)
@@ -149,7 +248,6 @@ def test_fetch_resource_descriptor(self):
         self.assertEqual(request, expected_request)
 
     def test_list_resource_descriptors(self):
-        PROJECT = 'my-project'
         PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
             project=PROJECT)
 
diff --git a/gcloud/monitoring/test_timeseries.py b/gcloud/monitoring/test_timeseries.py
new file mode 100644
index 000000000000..2ea9eafd4cca
--- /dev/null
+++ b/gcloud/monitoring/test_timeseries.py
@@ -0,0 +1,812 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+PROJECT = 'my-project'
+
+METRIC_TYPE = 'compute.googleapis.com/instance/uptime'
+METRIC_LABELS = {'instance_name': 'instance-1'}
+METRIC_LABELS2 = {'instance_name': 'instance-2'}
+
+RESOURCE_TYPE = 'gce_instance'
+RESOURCE_LABELS = {
+    'project_id': 'my-project',
+    'zone': 'us-east1-a',
+    'instance_id': '1234567890123456789',
+}
+RESOURCE_LABELS2 = {
+    'project_id': 'my-project',
+    'zone': 'us-east1-b',
+    'instance_id': '9876543210987654321',
+}
+
+METRIC_KIND = 'DELTA'
+VALUE_TYPE = 'DOUBLE'
+
+TS0 = '2016-04-06T22:05:00.042Z'
+TS1 = '2016-04-06T22:05:01.042Z'
+TS2 = '2016-04-06T22:05:02.042Z'
+
+
+class TestAligner(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.timeseries import Aligner
+        return Aligner
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(), 'ALIGN_RATE'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
+class TestReducer(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.timeseries import Reducer
+        return Reducer
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(),
+                                'REDUCE_PERCENTILE_99'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
+class TestQuery(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.timeseries import Query
+        return Query
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor_minimal(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client)
+
+        self.assertEqual(query._client, client)
+        self.assertEqual(query._filter.metric_type,
+                         self._getTargetClass().DEFAULT_METRIC_TYPE)
+
+        self.assertIsNone(query._start_time)
+        self.assertIsNone(query._end_time)
+
+        self.assertIsNone(query._per_series_aligner)
+        self.assertIsNone(query._alignment_period_seconds)
+        self.assertIsNone(query._cross_series_reducer)
+        self.assertEqual(query._group_by_fields, ())
+
+    def test_constructor_maximal(self):
+        import datetime
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
+        DAYS, HOURS, MINUTES = 1, 2, 3
+        T0 = T1 - datetime.timedelta(days=DAYS, hours=HOURS, minutes=MINUTES)
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE,
+                              end_time=T1,
+                              days=DAYS, hours=HOURS, minutes=MINUTES)
+
+        self.assertEqual(query._client, client)
+        self.assertEqual(query._filter.metric_type, METRIC_TYPE)
+
+        self.assertEqual(query._start_time, T0)
+        self.assertEqual(query._end_time, T1)
+
+        self.assertIsNone(query._per_series_aligner)
+        self.assertIsNone(query._alignment_period_seconds)
+        self.assertIsNone(query._cross_series_reducer)
+        self.assertEqual(query._group_by_fields, ())
+
+    def test_constructor_default_end_time(self):
+        import datetime
+        from gcloud._testing import _Monkey
+        from gcloud.monitoring import timeseries as MUT
+
+        MINUTES = 5
+        NOW, T0, T1 = [
+            datetime.datetime(2016, 4, 7, 2, 30, 30),
+            datetime.datetime(2016, 4, 7, 2, 25, 0),
+            datetime.datetime(2016, 4, 7, 2, 30, 0),
+        ]
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        with _Monkey(MUT, _NOW=lambda: NOW):
+            query = self._makeOne(client, METRIC_TYPE, minutes=MINUTES)
+
+        self.assertEqual(query._start_time, T0)
+        self.assertEqual(query._end_time, T1)
+
+    def test_constructor_nonzero_duration_illegal(self):
+        import datetime
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
+        client = _Client(project=PROJECT, connection=_Connection())
+        with self.assertRaises(ValueError):
+            self._makeOne(client, METRIC_TYPE, end_time=T1)
+
+    def test_execution_without_interval_illegal(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        with self.assertRaises(ValueError):
+            list(query)
+
+    def test_filter(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_group(self):
+        GROUP = '1234567'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_group(GROUP)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND group.id = "{group}"'
+        ).format(type=METRIC_TYPE, group=GROUP)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_projects(self):
+        PROJECT1, PROJECT2 = 'project-1', 'project-2'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_projects(PROJECT1, PROJECT2)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND project = "{project1}" OR project = "{project2}"'
+        ).format(type=METRIC_TYPE, project1=PROJECT1, project2=PROJECT2)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_resources(self):
+        ZONE_PREFIX = 'europe-'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_resources(zone_prefix=ZONE_PREFIX)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND resource.label.zone = starts_with("{prefix}")'
+        ).format(type=METRIC_TYPE, prefix=ZONE_PREFIX)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_metrics(self):
+        INSTANCE = 'my-instance'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_metrics(instance_name=INSTANCE)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND metric.label.instance_name = "{instance}"'
+        ).format(type=METRIC_TYPE, instance=INSTANCE)
+        self.assertEqual(query.filter, expected)
+
+    def test_request_parameters_minimal(self):
+        import datetime
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(end_time=T1)
+        expected = [
+            ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+            ('interval.endTime', T1.isoformat() + 'Z'),
+        ]
+        self.assertEqual(query._build_query_params(), expected)
+
+    def test_request_parameters_maximal(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 7, 2, 0, 0)
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
+
+        ALIGNER = 'ALIGN_DELTA'
+        MINUTES, SECONDS, PERIOD = 1, 30, '90s'
+
+        REDUCER = 'REDUCE_MEAN'
+        FIELD1, FIELD2 = 'resource.zone', 'metric.instance_name'
+
+        PAGE_SIZE = 100
+        PAGE_TOKEN = 'second-page-please'
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        query = query.align(ALIGNER, minutes=MINUTES, seconds=SECONDS)
+        query = query.reduce(REDUCER, FIELD1, FIELD2)
+        actual = query._build_query_params(headers_only=True,
+                                           page_size=PAGE_SIZE,
+                                           page_token=PAGE_TOKEN)
+        expected = [
+            ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+            ('interval.endTime', T1.isoformat() + 'Z'),
+            ('interval.startTime', T0.isoformat() + 'Z'),
+            ('aggregation.perSeriesAligner', ALIGNER),
+            ('aggregation.alignmentPeriod', PERIOD),
+            ('aggregation.crossSeriesReducer', REDUCER),
+            ('aggregation.groupByFields', FIELD1),
+            ('aggregation.groupByFields', FIELD2),
+            ('view', 'HEADERS'),
+            ('pageSize', PAGE_SIZE),
+            ('pageToken', PAGE_TOKEN),
+        ]
+        self.assertEqual(actual, expected)
+
+    def test_iteration(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        INTERVAL1 = {'startTime': TS0, 'endTime': TS1}
+        INTERVAL2 = {'startTime': TS1, 'endTime': TS2}
+
+        VALUE1 = 60  # seconds
+        VALUE2 = 60.001  # seconds
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE1}},
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE1}},
+            ],
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE2}},
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE2}},
+            ],
+        }
+
+        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual([p.value for p in series1.points], [VALUE1, VALUE1])
+        self.assertEqual([p.value for p in series2.points], [VALUE2, VALUE2])
+        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2])
+        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2])
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+            ],
+        }
+
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
+    def test_iteration_paged(self):
+        import copy
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        INTERVAL1 = {'startTime': TS0, 'endTime': TS1}
+        INTERVAL2 = {'startTime': TS1, 'endTime': TS2}
+
+        VALUE1 = 60  # seconds
+        VALUE2 = 60.001  # seconds
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE1}},
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE1}},
+            ],
+        }
+        SERIES2_PART1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE2}},
+            ],
+        }
+        SERIES2_PART2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE2}},
+            ],
+        }
+
+        TOKEN = 'second-page-please'
+        RESPONSE1 = {'timeSeries': [SERIES1, SERIES2_PART1],
+                     'nextPageToken': TOKEN}
+        RESPONSE2 = {'timeSeries': [SERIES2_PART2]}
+
+        connection = _Connection(RESPONSE1, RESPONSE2)
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual([p.value for p in series1.points], [VALUE1, VALUE1])
+        self.assertEqual([p.value for p in series2.points], [VALUE2, VALUE2])
+        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2])
+        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2])
+
+        expected_request1 = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+            ],
+        }
+
+        expected_request2 = copy.deepcopy(expected_request1)
+        expected_request2['query_params'].append(('pageToken', TOKEN))
+
+        request1, request2 = connection._requested
+        self.assertEqual(request1, expected_request1)
+        self.assertEqual(request2, expected_request2)
+
+    def test_iteration_empty(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        connection = _Connection({})
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 0)
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+            ],
+        }
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
+    def test_iteration_headers_only(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+
+        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query.iter(headers_only=True))
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual(series1.points, [])
+        self.assertEqual(series2.points, [])
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+                ('view', 'HEADERS'),
+            ],
+        }
+
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
+
+class TestTimeSeries(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.timeseries import TimeSeries
+        return TimeSeries
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        from gcloud.monitoring.metric import Metric
+        from gcloud.monitoring.resource import Resource
+        from gcloud.monitoring.timeseries import Point
+
+        VALUE = 60  # seconds
+
+        METRIC = Metric(type=METRIC_TYPE, labels=METRIC_LABELS)
+        RESOURCE = Resource(type=RESOURCE_TYPE, labels=RESOURCE_LABELS)
+        POINTS = [
+            Point(start_time=TS0, end_time=TS1, value=VALUE),
+            Point(start_time=TS1, end_time=TS2, value=VALUE),
+        ]
+
+        series = self._makeOne(metric=METRIC,
+                               resource=RESOURCE,
+                               metric_kind=METRIC_KIND,
+                               value_type=VALUE_TYPE,
+                               points=POINTS)
+
+        self.assertEqual(series.metric, METRIC)
+        self.assertEqual(series.resource, RESOURCE)
+        self.assertEqual(series.metric_kind, METRIC_KIND)
+        self.assertEqual(series.value_type, VALUE_TYPE)
+        self.assertEqual(series.points, POINTS)
+
+    def test_from_dict(self):
+        VALUE = 60  # seconds
+
+        info = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {
+                    'interval': {'startTime': TS0, 'endTime': TS1},
+                    'value': {'doubleValue': VALUE},
+                },
+                {
+                    'interval': {'startTime': TS1, 'endTime': TS2},
+                    'value': {'doubleValue': VALUE},
+                },
+            ],
+        }
+
+        series = self._getTargetClass()._from_dict(info)
+
+        self.assertEqual(series.metric.type, METRIC_TYPE)
+        self.assertEqual(series.metric.labels, METRIC_LABELS)
+        self.assertEqual(series.resource.type, RESOURCE_TYPE)
+        self.assertEqual(series.resource.labels, RESOURCE_LABELS)
+
+        self.assertEqual(series.metric_kind, METRIC_KIND)
+        self.assertEqual(series.value_type, VALUE_TYPE)
+
+        self.assertEqual(len(series.points), 2)
+        point1, point2 = series.points
+
+        self.assertEqual(point1.start_time, TS0)
+        self.assertEqual(point1.end_time, TS1)
+        self.assertEqual(point1.value, VALUE)
+
+        self.assertEqual(point2.start_time, TS1)
+        self.assertEqual(point2.end_time, TS2)
+        self.assertEqual(point2.value, VALUE)
+
+    def test_from_dict_no_points(self):
+        info = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+
+        series = self._getTargetClass()._from_dict(info)
+
+        self.assertEqual(series.metric.type, METRIC_TYPE)
+        self.assertEqual(series.metric.labels, METRIC_LABELS)
+        self.assertEqual(series.resource.type, RESOURCE_TYPE)
+        self.assertEqual(series.resource.labels, RESOURCE_LABELS)
+
+        self.assertEqual(series.metric_kind, METRIC_KIND)
+        self.assertEqual(series.value_type, VALUE_TYPE)
+
+        self.assertEqual(series.points, [])
+
+    def test_labels(self):
+        info = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+
+        series = self._getTargetClass()._from_dict(info)
+
+        labels = {'resource_type': RESOURCE_TYPE}
+        labels.update(RESOURCE_LABELS)
+        labels.update(METRIC_LABELS)
+
+        self.assertEqual(series.labels, labels)
+
+
+class TestPoint(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.timeseries import Point
+        return Point
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor(self):
+        VALUE = 3.14
+        point = self._makeOne(start_time=TS0, end_time=TS1, value=VALUE)
+        self.assertEqual(point.start_time, TS0)
+        self.assertEqual(point.end_time, TS1)
+        self.assertEqual(point.value, VALUE)
+
+    def test_from_dict(self):
+        VALUE = 3.14
+        info = {
+            'interval': {'startTime': TS0, 'endTime': TS1},
+            'value': {'doubleValue': VALUE},
+        }
+        point = self._getTargetClass()._from_dict(info)
+        self.assertEqual(point.start_time, TS0)
+        self.assertEqual(point.end_time, TS1)
+        self.assertEqual(point.value, VALUE)
+
+    def test_from_dict_defaults(self):
+        VALUE = 3.14
+        info = {
+            'interval': {'endTime': TS1},
+            'value': {'doubleValue': VALUE},
+        }
+        point = self._getTargetClass()._from_dict(info)
+        self.assertIsNone(point.start_time)
+        self.assertEqual(point.end_time, TS1)
+        self.assertEqual(point.value, VALUE)
+
+    def test_from_dict_int64(self):
+        VALUE = 2 ** 63 - 1
+        info = {
+            'interval': {'endTime': TS1},
+            'value': {'int64Value': str(VALUE)},
+        }
+        point = self._getTargetClass()._from_dict(info)
+        self.assertIsNone(point.start_time)
+        self.assertEqual(point.end_time, TS1)
+        self.assertEqual(point.value, VALUE)
+
+
+class Test_Filter(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.timeseries import _Filter
+        return _Filter
+
+    def _makeOne(self, metric_type):
+        return self._getTargetClass()(metric_type)
+
+    def test_minimal(self):
+        obj = self._makeOne(METRIC_TYPE)
+        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
+        self.assertEqual(str(obj), expected)
+
+    def test_maximal(self):
+        obj = self._makeOne(METRIC_TYPE)
+        obj.group_id = '1234567'
+        obj.projects = 'project-1', 'project-2'
+        obj.select_resources(resource_type='some-resource',
+                             resource_label='foo')
+        obj.select_metrics(metric_label_prefix='bar-')
+
+        expected = (
+            'metric.type = "{type}"'
+            ' AND group.id = "1234567"'
+            ' AND project = "project-1" OR project = "project-2"'
+            ' AND resource.label.resource_label = "foo"'
+            ' AND resource.type = "some-resource"'
+            ' AND metric.label.metric_label = starts_with("bar-")'
+        ).format(type=METRIC_TYPE)
+
+        self.assertEqual(str(obj), expected)
+
+
+class Test__build_label_filter(unittest2.TestCase):
+
+    def _callFUT(self, *args, **kwargs):
+        from gcloud.monitoring.timeseries import _build_label_filter
+        return _build_label_filter(*args, **kwargs)
+
+    def test_no_labels(self):
+        self.assertEqual(self._callFUT('resource'), '')
+
+    def test_label_is_none(self):
+        self.assertEqual(self._callFUT('resource', foo=None), '')
+
+    def test_metric_labels(self):
+        actual = self._callFUT(
+            'metric',
+            alpha_prefix='a-',
+            beta_gamma_suffix='-b',
+            delta_epsilon='xyz',
+        )
+        expected = (
+            'metric.label.alpha = starts_with("a-")'
+            ' AND metric.label.beta_gamma = ends_with("-b")'
+            ' AND metric.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_resource_labels(self):
+        actual = self._callFUT(
+            'resource',
+            alpha_prefix='a-',
+            beta_gamma_suffix='-b',
+            delta_epsilon='xyz',
+        )
+        expected = (
+            'resource.label.alpha = starts_with("a-")'
+            ' AND resource.label.beta_gamma = ends_with("-b")'
+            ' AND resource.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_raw_label_filters(self):
+        actual = self._callFUT(
+            'resource',
+            'resource.label.alpha = starts_with("a-")',
+            'resource.label.beta_gamma = ends_with("-b")',
+            'resource.label.delta_epsilon = "xyz"',
+        )
+        expected = (
+            'resource.label.alpha = starts_with("a-")'
+            ' AND resource.label.beta_gamma = ends_with("-b")'
+            ' AND resource.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_resource_type(self):
+        actual = self._callFUT('resource', resource_type='foo')
+        expected = 'resource.type = "foo"'
+        self.assertEqual(actual, expected)
+
+    def test_resource_type_prefix(self):
+        actual = self._callFUT('resource', resource_type_prefix='foo-')
+        expected = 'resource.type = starts_with("foo-")'
+        self.assertEqual(actual, expected)
+
+    def test_resource_type_suffix(self):
+        actual = self._callFUT('resource', resource_type_suffix='-foo')
+        expected = 'resource.type = ends_with("-foo")'
+        self.assertEqual(actual, expected)
+
+
+class Test__sorted_resource_labels(unittest2.TestCase):
+
+    def _callFUT(self, labels):
+        from gcloud.monitoring.timeseries import _sorted_resource_labels
+        return _sorted_resource_labels(labels)
+
+    def test_empty(self):
+        self.assertEqual(self._callFUT([]), [])
+
+    def test_sorted(self):
+        from gcloud.monitoring.timeseries import TOP_RESOURCE_LABELS
+        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        self.assertEqual(self._callFUT(EXPECTED), EXPECTED)
+
+    def test_reversed(self):
+        from gcloud.monitoring.timeseries import TOP_RESOURCE_LABELS
+        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        INPUT = list(reversed(EXPECTED))
+        self.assertEqual(self._callFUT(INPUT), EXPECTED)
+
+
+class Test__format_timestamp(unittest2.TestCase):
+
+    def _callFUT(self, timestamp):
+        from gcloud.monitoring.timeseries import _format_timestamp
+        return _format_timestamp(timestamp)
+
+    def test_naive(self):
+        from datetime import datetime
+        TIMESTAMP = datetime(2016, 4, 5, 13, 30, 0)
+        timestamp = self._callFUT(TIMESTAMP)
+        self.assertEqual(timestamp, '2016-04-05T13:30:00Z')
+
+    def test_with_timezone(self):
+        from datetime import datetime
+        from gcloud._helpers import UTC
+        TIMESTAMP = datetime(2016, 4, 5, 13, 30, 0, tzinfo=UTC)
+        timestamp = self._callFUT(TIMESTAMP)
+        self.assertEqual(timestamp, '2016-04-05T13:30:00Z')
+
+
+class _Connection(object):
+
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self._requested = []
+
+    def api_request(self, **kwargs):
+        from gcloud.exceptions import NotFound
+        self._requested.append(kwargs)
+        try:
+            return self._responses.pop(0)
+        except IndexError:  # pragma: NO COVER
+            raise NotFound('miss')
+
+
+class _Client(object):
+
+    def __init__(self, project, connection):
+        self.project = project
+        self.connection = connection
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index d7f8400bee86..030f17e344c0 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -40,6 +40,8 @@
     'zone',
 ]
 
+_NOW = datetime.datetime.utcnow  # To be replaced by tests.
+
 
 class Aligner(object):
     """Allowed values for the `supported aligners`_."""
@@ -133,8 +135,7 @@ def __init__(self, client,
         start_time = None
         if days or hours or minutes:
             if end_time is None:
-                end_time = datetime.datetime.utcnow().replace(second=0,
-                                                              microsecond=0)
+                end_time = _NOW().replace(second=0, microsecond=0)
             start_time = end_time - datetime.timedelta(days=days,
                                                        hours=hours,
                                                        minutes=minutes)
@@ -349,18 +350,18 @@ def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
                                                               60 * hours)
         return new_query
 
-    def reduce(self, cross_series_reducer, group_by_fields=()):
+    def reduce(self, cross_series_reducer, *group_by_fields):
         """Copy the query and add cross-series reduction.
 
         :type cross_series_reducer: string
-        :param cross_series_reducer: The approach to be used to combine
-            time series. For example: ``"REDUCE_MEAN"``.
-            See the `supported reducers`_.
-
-        :type group_by_fields: string or list of strings
-        :param group_by_fields: An optional field or set of fields
-            to be preserved by the reduction. For example, a value of
-            ``"resource.zone"`` will result in one time series per zone.
+        :param cross_series_reducer:
+            The approach to be used to combine time series. For example:
+            ``"REDUCE_MEAN"``. See the `supported reducers`_.
+
+        :type group_by_fields: strings
+        :param group_by_fields:
+            Fields to be preserved by the reduction. For example, specifying
+            just ``"resource.zone"`` will result in one time series per zone.
             The default is to aggregate all of the time series into just one.
 
         :rtype: :class:`Query`
@@ -370,9 +371,6 @@ def reduce(self, cross_series_reducer, group_by_fields=()):
             https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
             projects.timeSeries/list#Reducer
         """
-        if isinstance(group_by_fields, six.string_types):
-            group_by_fields = [group_by_fields]
-
         new_query = self.copy()
         new_query._cross_series_reducer = cross_series_reducer
         new_query._group_by_fields = group_by_fields
@@ -406,7 +404,7 @@ def iter(self, headers_only=False, _page_size=None):
         if self._end_time is None:
             raise ValueError('Query time interval not specified.')
 
-        path = '/projects/{project}/timeSeries'.format(
+        path = '/projects/{project}/timeSeries/'.format(
             project=self._client.project)
 
         def _fragments():
@@ -437,7 +435,8 @@ def _fragments():
             points.reverse()  # Order from oldest to newest.
             yield timeseries._replace(points=points)
 
-    def _build_query_params(self, headers_only, page_size, page_token):
+    def _build_query_params(self, headers_only=False,
+                            page_size=None, page_token=None):
         """Assemble the list of key-value pairs for the URL query string.
 
         We use a list of key-value pairs instead of a ``dict`` to allow for
@@ -457,40 +456,38 @@ def _build_query_params(self, headers_only, page_size, page_token):
         :returns:
             A list of key-value pairs suitable for passing to ``urlencode``.
         """
-        params = {'filter': self.filter}
-
-        params['interval.endTime'] = _format_timestamp(self._end_time)
-        if self._start_time is not None:
-            params['interval.startTime'] = _format_timestamp(self._start_time)
+        def _pairs():
+            yield 'filter', self.filter
 
-        if self._per_series_aligner is not None:
-            params['aggregation.perSeriesAligner'] = self._per_series_aligner
+            yield 'interval.endTime', _format_timestamp(self._end_time)
+            if self._start_time is not None:
+                yield 'interval.startTime', _format_timestamp(self._start_time)
 
-        if self._alignment_period_seconds is not None:
-            alignment_period = '{}s'.format(self._alignment_period_seconds)
-            params['aggregation.alignmentPeriod'] = alignment_period
+            if self._per_series_aligner is not None:
+                yield 'aggregation.perSeriesAligner', self._per_series_aligner
 
-        if self._cross_series_reducer is not None:
-            params['aggregation.crossSeriesReducer'] = \
-                self._cross_series_reducer
+            if self._alignment_period_seconds is not None:
+                alignment_period = '{period}s'.format(
+                    period=self._alignment_period_seconds)
+                yield 'aggregation.alignmentPeriod', alignment_period
 
-        if headers_only:
-            params['view'] = 'HEADERS'
+            if self._cross_series_reducer is not None:
+                yield ('aggregation.crossSeriesReducer',
+                       self._cross_series_reducer)
 
-        if page_size is not None:
-            params['pageSize'] = page_size
+            for field in self._group_by_fields:
+                yield 'aggregation.groupByFields', field
 
-        if page_token is not None:
-            params['pageToken'] = page_token
+            if headers_only:
+                yield 'view', 'HEADERS'
 
-        # Convert to a list of tuples before adding repeated fields.
-        params = list(six.iteritems(params))
+            if page_size is not None:
+                yield 'pageSize', page_size
 
-        if self._group_by_fields:
-            params.extend(('aggregation.groupByFields', field)
-                          for field in self._group_by_fields)
+            if page_token is not None:
+                yield 'pageToken', page_token
 
-        return sorted(params)
+        return list(_pairs())
 
     def as_dataframe(self, label=None, labels=None):
         """Return all the selected time series as a ``pandas`` dataframe.
@@ -651,13 +648,18 @@ def labels(self):
 
     def __repr__(self):
         """Return a representation string with the points elided."""
-        return '\n'.join([
-            'TimeSeries(',
-            '    {},'.format(self.metric),
-            '    {},'.format(self.resource),
-            '    {}, {}, Number of points={})'.format(
-                self.metric_kind, self.value_type, len(self.points)),
-        ])
+        return (
+            '<TimeSeries with {num} points:\n'
+            '    metric={metric},\n'
+            '    resource={resource},\n'
+            '    metric_kind={kind}, value_type={type}>'
+        ).format(
+            num=len(self.points),
+            metric=self.metric,
+            resource=self.resource,
+            kind=self.metric_kind,
+            type=self.value_type,
+        )
 
 
 class Point(collections.namedtuple('Point', 'end_time start_time value')):
@@ -720,12 +722,13 @@ def select_metrics(self, *args, **kwargs):
                                                        *args, **kwargs)
 
     def __str__(self):
-        filters = ['metric.type = "{}"'.format(self.metric_type)]
+        filters = ['metric.type = "{type}"'.format(type=self.metric_type)]
         if self.group_id is not None:
-            filters.append('group.id = "{}"'.format(self.group_id))
+            filters.append('group.id = "{id}"'.format(id=self.group_id))
         if self.projects:
-            filters.append(' OR '.join('project = "{}"'.format(project)
-                                       for project in self.projects))
+            filters.append(
+                ' OR '.join('project = "{project}"'.format(project=project)
+                            for project in self.projects))
         if self.resource_label_filter:
             filters.append(self.resource_label_filter)
         if self.metric_label_filter:
@@ -754,13 +757,13 @@ def _build_label_filter(category, *args, **kwargs):
             key = '.'.join((category, 'label', key))
 
         if suffix == 'prefix':
-            term = '{} = starts_with("{}")'
+            term = '{key} = starts_with("{value}")'
         elif suffix == 'suffix':
-            term = '{} = ends_with("{}")'
+            term = '{key} = ends_with("{value}")'
         else:
-            term = '{} = "{}"'
+            term = '{key} = "{value}"'
 
-        terms.append(term.format(key, value))
+        terms.append(term.format(key=key, value=value))
 
     return ' AND '.join(sorted(terms))
 

From 380e7e4509c96db4dcf524dc0b09c8affbc374ad Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 7 Apr 2016 15:42:37 -0400
Subject: [PATCH 12/61] Added a metric_type property.

I had dropped this, but I think we want it.
---
 gcloud/monitoring/test_timeseries.py | 5 +++++
 gcloud/monitoring/timeseries.py      | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/gcloud/monitoring/test_timeseries.py b/gcloud/monitoring/test_timeseries.py
index 2ea9eafd4cca..4999c38be90b 100644
--- a/gcloud/monitoring/test_timeseries.py
+++ b/gcloud/monitoring/test_timeseries.py
@@ -151,6 +151,11 @@ def test_execution_without_interval_illegal(self):
         with self.assertRaises(ValueError):
             list(query)
 
+    def test_metric_type(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        self.assertEqual(query.metric_type, METRIC_TYPE)
+
     def test_filter(self):
         client = _Client(project=PROJECT, connection=_Connection())
         query = self._makeOne(client, METRIC_TYPE)
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 030f17e344c0..8512c7c2a31a 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -155,6 +155,11 @@ def __init__(self, client,
     def __iter__(self):
         return self.iter()
 
+    @property
+    def metric_type(self):
+        """The metric type name."""
+        return self._filter.metric_type
+
     @property
     def filter(self):
         """The filter string.

From 451f419cc2bfdb3956258bdae0aefb528256e7e3 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 7 Apr 2016 20:45:05 -0400
Subject: [PATCH 13/61] The descriptor classes are no longer named tuples.

    MetricDescriptor
    ResourceDescriptor
    LabelDescriptor
---
 gcloud/monitoring/label.py      | 22 +++++++----
 gcloud/monitoring/metric.py     | 63 ++++++++++++++++++++----------
 gcloud/monitoring/resource.py   | 24 +++++++++---
 gcloud/monitoring/timeseries.py | 69 ++++++++++++++++++++-------------
 4 files changed, 119 insertions(+), 59 deletions(-)

diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
index 58327d1f05a8..ec4480e8b1be 100644
--- a/gcloud/monitoring/label.py
+++ b/gcloud/monitoring/label.py
@@ -18,8 +18,6 @@
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/LabelDescriptor
 """
 
-import collections
-
 
 class LabelValueType(object):
     """Allowed values for the `type of a label`_.
@@ -34,21 +32,25 @@ class LabelValueType(object):
     INT64 = 'INT64'
 
 
-class LabelDescriptor(collections.namedtuple('LabelDescriptor',
-                                             'key value_type description')):
+class LabelDescriptor(object):
     """Schema specification and documentation for a single label.
 
     :type key: string
     :param key: The name of the label.
 
     :type value_type: string
-    :param value_type: The type of the label. It must be one of ``"STRING"``,
-                       ``"BOOL"``, or ``"INT64"``.
+    :param value_type:
+        The type of the label. It must be one of ``"STRING"``, ``"BOOL"``,
+        or ``"INT64"``.
 
     :type description: string
     :param description: A human-readable description for the label.
     """
-    __slots__ = ()
+
+    def __init__(self, key, value_type, description):
+        self.key = key
+        self.value_type = value_type
+        self.description = description
 
     @classmethod
     def _from_dict(cls, info):
@@ -66,3 +68,9 @@ def _from_dict(cls, info):
             info.get('valueType', LabelValueType.STRING),
             info.get('description', ''),
         )
+
+    def __repr__(self):
+        return (
+            'LabelDescriptor(key={key!r}, value_type={value_type!r},'
+            ' description={description!r})'
+        ).format(**self.__dict__)
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 9413e15d5d09..f628e65c96da 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -56,33 +56,34 @@ class ValueType(object):
     MONEY = 'MONEY'
 
 
-class MetricDescriptor(collections.namedtuple(
-        'MetricDescriptor', ('name type labels metric_kind value_type unit'
-                             ' description display_name'))):
+class MetricDescriptor(object):
     """Specification of a metric type and its schema.
 
-    Metric descriptor instances are immutable.
-
     :type name: string
-    :param name: The "resource name" of the metric descriptor. For example:
-                 ``"projects/<project_id>/metricDescriptors/<type>"``
+    :param name:
+        The "resource name" of the metric descriptor. For example:
+        ``"projects/<project_id>/metricDescriptors/<type>"``
 
     :type type: string
-    :param type: The metric type including a DNS name prefix. For example:
-                 ``"compute.googleapis.com/instance/cpu/utilization"``
+    :param type:
+        The metric type including a DNS name prefix. For example:
+        ``"compute.googleapis.com/instance/cpu/utilization"``
 
     :type labels: list of :class:`~gcloud.monitoring.label.LabelDescriptor`
-    :param labels: A sequence of label descriptors specifying the labels used
-                   to identify a specific instance of this metric.
+    :param labels:
+        A sequence of label descriptors specifying the labels used to
+        identify a specific instance of this metric.
 
     :type metric_kind: string
-    :param metric_kind: The kind of measurement. It must be one of ``"GAUGE"``,
-                        ``"DELTA"``, or ``"CUMULATIVE"``.
+    :param metric_kind:
+        The kind of measurement. It must be one of ``"GAUGE"``, ``"DELTA"``,
+        or ``"CUMULATIVE"``.
 
     :type value_type: string
-    :param value_type: The value type of the metric. It must be one of
-                       ``"BOOL"``, ``"INT64"``, ``"DOUBLE"``, ``"STRING"``,
-                       ``"DISTRIBUTION"``, or ``"MONEY"``.
+    :param value_type:
+        The value type of the metric. It must be one of ``"BOOL"``,
+        ``"INT64"``, ``"DOUBLE"``, ``"STRING"``, ``"DISTRIBUTION"``,
+        or ``"MONEY"``.
 
     :type unit: string
     :param unit: The unit in which the metric value is reported.
@@ -93,7 +94,18 @@ class MetricDescriptor(collections.namedtuple(
     :type display_name: string
     :param display_name: A concise name for the metric.
     """
-    __slots__ = ()
+
+    def __init__(self, name, type, labels, metric_kind, value_type,
+                 unit, description, display_name):
+        # Allow "type" as a parameter name: pylint: disable=redefined-builtin
+        self.name = name
+        self.type = type
+        self.labels = labels
+        self.metric_kind = metric_kind
+        self.value_type = value_type
+        self.unit = unit
+        self.description = description
+        self.display_name = display_name
 
     @classmethod
     def _fetch(cls, client, metric_type):
@@ -173,17 +185,28 @@ def _from_dict(cls, info):
         :returns: A metric descriptor.
         """
         return cls(
-            type=info.get('type', ''),
             name=info.get('name', ''),
-            description=info.get('description', ''),
-            display_name=info.get('displayName', ''),
+            type=info.get('type', ''),
             labels=tuple(LabelDescriptor._from_dict(label)
                          for label in info.get('labels', [])),
             metric_kind=info['metricKind'],
             value_type=info['valueType'],
             unit=info.get('unit', ''),
+            description=info.get('description', ''),
+            display_name=info.get('displayName', ''),
         )
 
+    def __repr__(self):
+        return (
+            'MetricDescriptor(\n'
+            ' name={name!r},\n'
+            ' type={type!r},\n'
+            ' metric_kind={metric_kind!r}, value_type={value_type!r},\n'
+            ' labels={labels!r},\n'
+            ' display_name={display_name!r}, unit={unit!r},\n'
+            ' description={description!r})'
+        ).format(**self.__dict__)
+
 
 class Metric(collections.namedtuple('Metric', 'type labels')):
     """A specific metric identified by specifying values for all labels.
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 9441253e71f6..c24117a6bda7 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -24,12 +24,9 @@
 from gcloud.monitoring.label import LabelDescriptor
 
 
-class ResourceDescriptor(collections.namedtuple(
-        'ResourceDescriptor', ('name type display_name description labels'))):
+class ResourceDescriptor(object):
     """Specification of a monitored resource type and its schema.
 
-    Resource descriptor instances are immutable.
-
     :type name: string
     :param name:
         The "resource name" of the monitored resource descriptor:
@@ -52,7 +49,14 @@ class ResourceDescriptor(collections.namedtuple(
         A sequence of label descriptors specifying the labels used
         to identify a specific instance of this monitored resource.
     """
-    __slots__ = ()
+
+    def __init__(self, name, type, display_name, description, labels):
+        # Allow "type" as a parameter name: pylint: disable=redefined-builtin
+        self.name = name
+        self.type = type
+        self.display_name = display_name
+        self.description = description
+        self.labels = labels
 
     @classmethod
     def _fetch(cls, client, resource_type):
@@ -140,6 +144,16 @@ def _from_dict(cls, info):
                          for label in info.get('labels', [])),
         )
 
+    def __repr__(self):
+        return (
+            'ResourceDescriptor(\n'
+            ' name={name!r},\n'
+            ' type={type!r},\n'
+            ' labels={labels!r},\n'
+            ' display_name={display_name!r},\n'
+            ' description={description!r})'
+        ).format(**self.__dict__)
+
 
 class Resource(collections.namedtuple('Resource', 'type labels')):
     """A monitored resource identified by specifying values for all labels.
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 8512c7c2a31a..00aa473035fa 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -432,13 +432,15 @@ def _fragments():
                 if not page_token:
                     break
 
+        # The following use of groupby() relies on equality comparison
+        # of time series as (named) tuples.
         for timeseries, fragments in itertools.groupby(
                 _fragments(),
-                lambda fragment: fragment._replace(points=None)):
+                lambda fragment: fragment.header()):
             points = list(itertools.chain.from_iterable(
                 fragment.points for fragment in fragments))
             points.reverse()  # Order from oldest to newest.
-            yield timeseries._replace(points=points)
+            yield timeseries.header(points=points)
 
     def _build_query_params(self, headers_only=False,
                             page_size=None, page_token=None):
@@ -549,7 +551,7 @@ def as_dataframe(self, label=None, labels=None):
                 index=[p.end_time for p in time_series.points],
             )
             columns.append(pandas_series)
-            headers.append(time_series._replace(points=None))
+            headers.append(time_series.header())
 
         # Implement a smart default of using all available labels.
         if label is None and labels is None:
@@ -605,17 +607,47 @@ class TimeSeries(collections.namedtuple(
     :param resource: A resource object.
 
     :type metric_kind: string
-    :param metric_kind: The kind of measurement: ``"GAUGE"``, ``"DELTA"``,
-        or ``"CUMULATIVE"``.
+    :param metric_kind:
+        The kind of measurement: ``"GAUGE"``. ``"DELTA"``, or ``"CUMULATIVE"``.
 
     :type value_type: string
-    :param value_type: The value type of the metric: ``"BOOL"``, ``"INT64"``,
-        ``"DOUBLE"``, ``"STRING"``, ``"DISTRIBUTION"``, or ``"MONEY"``.
+    :param value_type:
+        The value type of the metric: ``"BOOL"``, ``"INT64"``, ``"DOUBLE"``,
+        ``"STRING"``, ``"DISTRIBUTION"``, or ``"MONEY"``.
 
     :type points: list of :class:`Point`
     :param points: A list of point objects.
     """
 
+    @property
+    def labels(self):
+        """A single dictionary with values for all the labels.
+
+        This combines ``resource.labels`` and ``metric.labels`` and also
+        adds ``"resource_type"``.
+        """
+        # pylint: disable=attribute-defined-outside-init
+        try:
+            return self._labels
+        except AttributeError:
+            labels = {'resource_type': self.resource.type}
+            labels.update(self.resource.labels)
+            labels.update(self.metric.labels)
+            self._labels = labels
+            return self._labels
+
+    def header(self, points=None):
+        """Copy everything but the point data.
+
+        :type points: list of :class:`Point`, or None
+        :param points: An optional point list.
+
+        :rtype: :class:`TimeSeries`
+        :returns: The new time series object.
+        """
+        points = list(points) if points else []
+        return self._replace(points=points)
+
     @classmethod
     def _from_dict(cls, info):
         """Construct a time series from the parsed JSON representation.
@@ -634,30 +666,13 @@ def _from_dict(cls, info):
         points = [Point._from_dict(p) for p in info.get('points', [])]
         return cls(metric, resource, metric_kind, value_type, points)
 
-    @property
-    def labels(self):
-        """A single dictionary with values for all the labels.
-
-        This combines ``resource.labels`` and ``metric.labels`` and also
-        adds ``"resource_type"``.
-        """
-        # pylint: disable=attribute-defined-outside-init
-        try:
-            return self._labels
-        except AttributeError:
-            labels = {'resource_type': self.resource.type}
-            labels.update(self.resource.labels)
-            labels.update(self.metric.labels)
-            self._labels = labels
-            return self._labels
-
     def __repr__(self):
         """Return a representation string with the points elided."""
         return (
             '<TimeSeries with {num} points:\n'
-            '    metric={metric},\n'
-            '    resource={resource},\n'
-            '    metric_kind={kind}, value_type={type}>'
+            ' metric={metric!r},\n'
+            ' resource={resource!r},\n'
+            ' metric_kind={kind!r}, value_type={type!r}>'
         ).format(
             num=len(self.points),
             metric=self.metric,

From 70366de3a618a3b0c5030e3c0fe89d33f79aad2e Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 7 Apr 2016 21:50:50 -0400
Subject: [PATCH 14/61] Move Query into a new query.py file.

---
 docs/index.rst                       |   3 +-
 docs/monitoring-query.rst            |   7 +
 gcloud/monitoring/__init__.py        |   2 +-
 gcloud/monitoring/client.py          |   8 +-
 gcloud/monitoring/metric.py          |   2 +
 gcloud/monitoring/query.py           | 688 +++++++++++++++++++++++++++
 gcloud/monitoring/resource.py        |   2 +
 gcloud/monitoring/test_query.py      | 654 +++++++++++++++++++++++++
 gcloud/monitoring/test_timeseries.py | 622 ------------------------
 gcloud/monitoring/timeseries.py      | 672 +-------------------------
 10 files changed, 1366 insertions(+), 1294 deletions(-)
 create mode 100644 docs/monitoring-query.rst
 create mode 100644 gcloud/monitoring/query.py
 create mode 100644 gcloud/monitoring/test_query.py

diff --git a/docs/index.rst b/docs/index.rst
index cd77db13620d..dafc38daf4fe 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -125,9 +125,10 @@
   :caption: Cloud Monitoring
 
   Client <monitoring-client>
-  monitoring-timeseries
   monitoring-metric
   monitoring-resource
+  monitoring-query
+  monitoring-timeseries
   monitoring-label
 
 .. toctree::
diff --git a/docs/monitoring-query.rst b/docs/monitoring-query.rst
new file mode 100644
index 000000000000..0a1e64982e48
--- /dev/null
+++ b/docs/monitoring-query.rst
@@ -0,0 +1,7 @@
+Time Series Query
+=================
+
+.. automodule:: gcloud.monitoring.query
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/gcloud/monitoring/__init__.py b/gcloud/monitoring/__init__.py
index 823c143fcd07..c626b955a4c2 100644
--- a/gcloud/monitoring/__init__.py
+++ b/gcloud/monitoring/__init__.py
@@ -19,11 +19,11 @@
 from gcloud.monitoring.label import LabelDescriptor
 from gcloud.monitoring.metric import Metric
 from gcloud.monitoring.metric import MetricDescriptor
+from gcloud.monitoring.query import Query
 from gcloud.monitoring.resource import Resource
 from gcloud.monitoring.resource import ResourceDescriptor
 from gcloud.monitoring.timeseries import Point
 from gcloud.monitoring.timeseries import TimeSeries
-from gcloud.monitoring.timeseries import Query
 
 
 SCOPE = Connection.SCOPE
diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 5a9054c94ca7..06703f0681f6 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -30,8 +30,8 @@
 from gcloud.client import JSONClient
 from gcloud.monitoring.connection import Connection
 from gcloud.monitoring.metric import MetricDescriptor
+from gcloud.monitoring.query import Query
 from gcloud.monitoring.resource import ResourceDescriptor
-from gcloud.monitoring.timeseries import Query
 
 
 class Client(JSONClient):
@@ -85,7 +85,7 @@ def query(self,
 
             It is also allowed to omit the end time and duration here,
             in which case
-            :meth:`~gcloud.monitoring.timeseries.Query.select_interval`
+            :meth:`~gcloud.monitoring.query.Query.select_interval`
             must be called before the query is executed.
 
         :type days: integer
@@ -97,13 +97,13 @@ def query(self,
         :type minutes: integer
         :param minutes: The number of minutes in the time interval.
 
-        :rtype: :class:`~gcloud.monitoring.timeseries.Query`
+        :rtype: :class:`~gcloud.monitoring.query.Query`
         :returns: The query object.
 
         :raises: :exc:`ValueError` if ``end_time`` is specified but
             ``days``, ``hours``, and ``minutes`` are all zero.
             If you really want to specify a point in time, use
-            :meth:`~gcloud.monitoring.timeseries.Query.select_interval`.
+            :meth:`~gcloud.monitoring.query.Query.select_interval`.
 
         .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
         """
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index f628e65c96da..cd22aa1b4d12 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -211,6 +211,8 @@ def __repr__(self):
 class Metric(collections.namedtuple('Metric', 'type labels')):
     """A specific metric identified by specifying values for all labels.
 
+    This is a named tuple. See :func:`collections.namedtuple`.
+
     :type type: string
     :param type: The metric type name.
 
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
new file mode 100644
index 000000000000..aa9d5f9e69cb
--- /dev/null
+++ b/gcloud/monitoring/query.py
@@ -0,0 +1,688 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Time series query for the `Google Monitoring API (V3)`_.
+
+.. _Google Monitoring API (V3):
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.timeSeries/list
+"""
+
+import copy
+import datetime
+import itertools
+
+from gcloud.monitoring.timeseries import TimeSeries
+
+TOP_RESOURCE_LABELS = [
+    'project_id',
+    'aws_account',
+    'location',
+    'region',
+    'zone',
+]
+
+_NOW = datetime.datetime.utcnow  # To be replaced by tests.
+
+
+class Aligner(object):
+    """Allowed values for the `supported aligners`_."""
+
+    ALIGN_NONE = 'ALIGN_NONE'
+    ALIGN_DELTA = 'ALIGN_DELTA'
+    ALIGN_RATE = 'ALIGN_RATE'
+    ALIGN_INTERPOLATE = 'ALIGN_INTERPOLATE'
+    ALIGN_NEXT_OLDER = 'ALIGN_NEXT_OLDER'
+    ALIGN_MIN = 'ALIGN_MIN'
+    ALIGN_MAX = 'ALIGN_MAX'
+    ALIGN_MEAN = 'ALIGN_MEAN'
+    ALIGN_COUNT = 'ALIGN_COUNT'
+    ALIGN_SUM = 'ALIGN_SUM'
+    ALIGN_STDDEV = 'ALIGN_STDDEV'
+    ALIGN_COUNT_TRUE = 'ALIGN_COUNT_TRUE'
+    ALIGN_FRACTION_TRUE = 'ALIGN_FRACTION_TRUE'
+
+
+class Reducer(object):
+    """Allowed values for the `supported reducers`_."""
+
+    REDUCE_NONE = 'REDUCE_NONE'
+    REDUCE_MEAN = 'REDUCE_MEAN'
+    REDUCE_MIN = 'REDUCE_MIN'
+    REDUCE_MAX = 'REDUCE_MAX'
+    REDUCE_SUM = 'REDUCE_SUM'
+    REDUCE_STDDEV = 'REDUCE_STDDEV'
+    REDUCE_COUNT = 'REDUCE_COUNT'
+    REDUCE_COUNT_TRUE = 'REDUCE_COUNT_TRUE'
+    REDUCE_FRACTION_TRUE = 'REDUCE_FRACTION_TRUE'
+    REDUCE_PERCENTILE_99 = 'REDUCE_PERCENTILE_99'
+    REDUCE_PERCENTILE_95 = 'REDUCE_PERCENTILE_95'
+    REDUCE_PERCENTILE_50 = 'REDUCE_PERCENTILE_50'
+    REDUCE_PERCENTILE_05 = 'REDUCE_PERCENTILE_05'
+
+
+class Query(object):
+    """Query object for listing time series.
+
+    The preferred way to construct a query object is using the
+    :meth:`~gcloud.monitoring.client.Client.query` method
+    of the :class:`~gcloud.monitoring.client.Client` class.
+
+    :type client: :class:`gcloud.monitoring.client.Client`
+    :param client: The client to use.
+
+    :type metric_type: string
+    :param metric_type: The metric type name. The default value is
+        ``"compute.googleapis.com/instance/cpu/utilization"``, but
+        please note that this default value is provided only for
+        demonstration purposes and is subject to change. See the
+        `supported metrics`_.
+
+    :type end_time: :class:`datetime.datetime` or None
+    :param end_time: The end time (inclusive) of the time interval
+        for which results should be returned, as a datetime object.
+        The default is the start of the current minute.
+
+        The start time (exclusive) is determined by combining the
+        values of  ``days``, ``hours``, and ``minutes``, and
+        subtracting the resulting duration from the end time.
+
+        It is also allowed to omit the end time and duration here,
+        in which case
+        :meth:`~gcloud.monitoring.query.Query.select_interval`
+        must be called before the query is executed.
+
+    :type days: integer
+    :param days: The number of days in the time interval.
+
+    :type hours: integer
+    :param hours: The number of hours in the time interval.
+
+    :type minutes: integer
+    :param minutes: The number of minutes in the time interval.
+
+    :raises: :exc:`ValueError` if ``end_time`` is specified but
+        ``days``, ``hours``, and ``minutes`` are all zero.
+        If you really want to specify a point in time, use
+        :meth:`~gcloud.monitoring.query.Query.select_interval`.
+
+    .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
+    """
+
+    DEFAULT_METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
+
+    def __init__(self, client,
+                 metric_type=DEFAULT_METRIC_TYPE,
+                 end_time=None, days=0, hours=0, minutes=0):
+        start_time = None
+        if days or hours or minutes:
+            if end_time is None:
+                end_time = _NOW().replace(second=0, microsecond=0)
+            start_time = end_time - datetime.timedelta(days=days,
+                                                       hours=hours,
+                                                       minutes=minutes)
+        elif end_time is not None:
+            raise ValueError('Non-zero duration required for time interval.')
+
+        self._client = client
+        self._end_time = end_time
+        self._start_time = start_time
+        self._filter = _Filter(metric_type)
+
+        self._per_series_aligner = None
+        self._alignment_period_seconds = None
+        self._cross_series_reducer = None
+        self._group_by_fields = ()
+
+    def __iter__(self):
+        return self.iter()
+
+    @property
+    def metric_type(self):
+        """The metric type name."""
+        return self._filter.metric_type
+
+    @property
+    def filter(self):
+        """The filter string.
+
+        This is constructed from the metric type, the resource type, and
+        selectors for the group ID, monitored projects, resource labels,
+        and metric labels.
+        """
+        return str(self._filter)
+
+    def select_interval(self, end_time, start_time=None):
+        """Copy the query and set the query time interval.
+
+        :type end_time: :class:`datetime.datetime`
+        :param end_time: The end time (inclusive) of the time interval
+            for which results should be returned, as a datetime object.
+
+        :type start_time: :class:`datetime.datetime` or None
+        :param start_time: The start time (exclusive) of the time interval
+            for which results should be returned, as a datetime object.
+            If not specified, the interval is a point in time.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._end_time = end_time
+        new_query._start_time = start_time
+        return new_query
+
+    def select_group(self, group_id):
+        """Copy the query and add filtering by group.
+
+        :type group_id: string
+        :param group_id: The ID of a group to filter by.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.group_id = group_id
+        return new_query
+
+    def select_projects(self, *args):
+        """Copy the query and add filtering by monitored projects.
+
+        This is only useful if the target project represents a Stackdriver
+        account containing the specified monitored projects.
+
+        Examples::
+
+            query = query.select_projects('project-1')
+            query = query.select_projects('project-1', 'project-2')
+
+        :param args: Project IDs limiting the resources to be included
+            in the query.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.projects = args
+        return new_query
+
+    def select_resources(self, *args, **kwargs):
+        """Copy the query and add filtering by resource labels.
+
+        Examples::
+
+            query = query.select_resources(zone='us-central1-a')
+            query = query.select_resources(zone_prefix='europe-')
+            query = query.select_resources(resource_type='gce_instance')
+
+        A keyword argument ``<label>=<value>`` ordinarily generates a filter
+        expression of the form::
+
+            resource.label.<label> = "<value>"
+
+        However, by adding ``"_prefix"`` or ``"_suffix"`` to the keyword,
+        you can specify a partial match.
+
+        ``<label>_prefix=<value>`` generates::
+
+            resource.label.<label> = starts_with("<value>")
+
+        ``<label>_suffix=<value>`` generates::
+
+            resource.label.<label> = ends_with("<value>")
+
+        As a special case, ``"resource_type"`` is treated as a special
+        pseudo-label corresponding to the filter object ``resource.type``.
+        For example, ``resource_type=<value>`` generates::
+
+            resource.type = "<value>"
+
+        See the `defined resource types`_.
+
+        .. note::
+
+            The label ``"instance_name"`` is a metric label,
+            not a resource label. You would filter on it using
+            ``select_metrics(instance_name=...)``.
+
+        :param args: Raw filter expression strings to include in the
+            conjunction. If just one is provided and no keyword arguments
+            are provided, it can be a disjunction.
+
+        :param kwargs: Label filters to include in the conjunction as
+            described above.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+
+        .. _defined resource types:
+            https://cloud.google.com/monitoring/api/v3/monitored-resources
+        """
+        new_query = self.copy()
+        new_query._filter.select_resources(*args, **kwargs)
+        return new_query
+
+    def select_metrics(self, *args, **kwargs):
+        """Copy the query and add filtering by metric labels.
+
+        Examples::
+
+            query = query.select_metrics(instance_name='myinstance')
+            query = query.select_metrics(instance_name_prefix='mycluster-')
+
+        A keyword argument ``<label>=<value>`` ordinarily generates a filter
+        expression of the form::
+
+            metric.label.<label> = "<value>"
+
+        However, by adding ``"_prefix"`` or ``"_suffix"`` to the keyword,
+        you can specify a partial match.
+
+        ``<label>_prefix=<value>`` generates::
+
+            metric.label.<label> = starts_with("<value>")
+
+        ``<label>_suffix=<value>`` generates::
+
+            metric.label.<label> = ends_with("<value>")
+
+        :param args: Raw filter expression strings to include in the
+            conjunction. If just one is provided and no keyword arguments
+            are provided, it can be a disjunction.
+
+        :param kwargs: Label filters to include in the conjunction as
+            described above.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.select_metrics(*args, **kwargs)
+        return new_query
+
+    def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
+        """Copy the query and add temporal alignment.
+
+        If ``per_series_aligner`` is not ``"ALIGN_NONE"``, each time series
+        will contain data points only on the period boundaries.
+
+        Example::
+
+            query = query.align('ALIGN_MEAN', minutes=5)
+
+        :type per_series_aligner: string
+        :param per_series_aligner: The approach to be used to align
+            individual time series. For example: ``"ALIGN_MEAN"``.
+            See the `supported aligners`_.
+
+        :type seconds: integer
+        :param seconds: The number of seconds in the alignment period.
+
+        :type minutes: integer
+        :param minutes: The number of minutes in the alignment period.
+
+        :type hours: integer
+        :param hours: The number of hours in the alignment period.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+
+        .. _supported aligners:
+            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+            projects.timeSeries/list#Aligner
+        """
+        new_query = self.copy()
+        new_query._per_series_aligner = per_series_aligner
+        new_query._alignment_period_seconds = seconds + 60 * (minutes +
+                                                              60 * hours)
+        return new_query
+
+    def reduce(self, cross_series_reducer, *group_by_fields):
+        """Copy the query and add cross-series reduction.
+
+        :type cross_series_reducer: string
+        :param cross_series_reducer:
+            The approach to be used to combine time series. For example:
+            ``"REDUCE_MEAN"``. See the `supported reducers`_.
+
+        :type group_by_fields: strings
+        :param group_by_fields:
+            Fields to be preserved by the reduction. For example, specifying
+            just ``"resource.zone"`` will result in one time series per zone.
+            The default is to aggregate all of the time series into just one.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+
+        .. _supported reducers:
+            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+            projects.timeSeries/list#Reducer
+        """
+        new_query = self.copy()
+        new_query._cross_series_reducer = cross_series_reducer
+        new_query._group_by_fields = group_by_fields
+        return new_query
+
+    def iter(self, headers_only=False, _page_size=None):
+        """Yield all time series objects selected by the query.
+
+        Note that the :class:`Query` object itself is an iterable, such that
+        the following are equivalent::
+
+            for timeseries in query: ...
+            for timeseries in query.iter(): ...
+
+        :type headers_only: boolean
+        :param headers_only:
+             Whether to omit the point data from the time series objects.
+
+        :type _page_size: integer or None
+        :param _page_size:
+            An optional positive number specifying the maximum number of
+            points to return per page. This can be used to control how far
+            the iterator reads ahead.
+
+        :rtype: iterator over :class:`~gcloud.monitoring.timeseries.TimeSeries`
+        :returns: Time series objects, containing points ordered from oldest
+            to newest.
+        :raises: :exc:`ValueError` if the query time interval has not been
+            specified.
+        """
+        if self._end_time is None:
+            raise ValueError('Query time interval not specified.')
+
+        path = '/projects/{project}/timeSeries/'.format(
+            project=self._client.project)
+
+        def _fragments():
+            page_token = None
+            while True:
+                params = self._build_query_params(
+                    headers_only=headers_only,
+                    page_size=_page_size,
+                    page_token=page_token,
+                )
+                response = self._client.connection.api_request(
+                    method='GET',
+                    path=path,
+                    query_params=params,
+                )
+                for info in response.get('timeSeries', []):
+                    yield TimeSeries._from_dict(info)
+
+                page_token = response.get('nextPageToken')
+                if not page_token:
+                    break
+
+        # The following use of groupby() relies on equality comparison
+        # of time series as (named) tuples.
+        for timeseries, fragments in itertools.groupby(
+                _fragments(),
+                lambda fragment: fragment.header()):
+            points = list(itertools.chain.from_iterable(
+                fragment.points for fragment in fragments))
+            points.reverse()  # Order from oldest to newest.
+            yield timeseries.header(points=points)
+
+    def _build_query_params(self, headers_only=False,
+                            page_size=None, page_token=None):
+        """Assemble the list of key-value pairs for the URL query string.
+
+        We use a list of key-value pairs instead of a ``dict`` to allow for
+        repeated fields.
+
+        :type headers_only: boolean
+        :param headers_only:
+             Whether to omit the point data from the
+             :class:`~gcloud.monitoring.timeseries.TimeSeries` objects.
+
+        :type page_size: integer or None
+        :param page_size: A limit on the number of points to return per page.
+
+        :type page_token: string or None
+        :param page_token: A token to continue the retrieval.
+
+        :rtype: list of tuples
+        :returns:
+            A list of key-value pairs suitable for passing to ``urlencode``.
+        """
+        def _pairs():
+            yield 'filter', self.filter
+
+            yield 'interval.endTime', _format_timestamp(self._end_time)
+            if self._start_time is not None:
+                yield 'interval.startTime', _format_timestamp(self._start_time)
+
+            if self._per_series_aligner is not None:
+                yield 'aggregation.perSeriesAligner', self._per_series_aligner
+
+            if self._alignment_period_seconds is not None:
+                alignment_period = '{period}s'.format(
+                    period=self._alignment_period_seconds)
+                yield 'aggregation.alignmentPeriod', alignment_period
+
+            if self._cross_series_reducer is not None:
+                yield ('aggregation.crossSeriesReducer',
+                       self._cross_series_reducer)
+
+            for field in self._group_by_fields:
+                yield 'aggregation.groupByFields', field
+
+            if headers_only:
+                yield 'view', 'HEADERS'
+
+            if page_size is not None:
+                yield 'pageSize', page_size
+
+            if page_token is not None:
+                yield 'pageToken', page_token
+
+        return list(_pairs())
+
+    def as_dataframe(self, label=None, labels=None):
+        """Return all the selected time series as a ``pandas`` dataframe.
+
+        .. note::
+
+            Use of this method requires that you have ``pandas`` installed.
+
+        Examples::
+
+            # Generate a dataframe with a multi-level column header including
+            # the resource type and all available resource and metric labels.
+            # This can be useful for seeing what labels are available.
+            dataframe = query.as_dataframe()
+
+            # Generate a dataframe using a particular label for the column
+            # names.
+            dataframe = query.as_dataframe(label='instance_name')
+
+            # Generate a dataframe with a multi-level column header.
+            dataframe = query.as_dataframe(labels=['zone', 'instance_name'])
+
+            # Generate a dataframe with a multi-level column header, assuming
+            # the metric is issued by more than one type of resource.
+            dataframe = query.as_dataframe(
+                labels=['resource_type', 'instance_id'])
+
+        :type label: string or None
+        :param label: The label name to use for the dataframe header.
+            This can be the name of a resource label or metric label
+            (e.g., ``"instance_name"``), or the string ``"resource_type"``.
+
+        :type labels: list of strings, or None
+        :param labels: A list or tuple of label names to use for the dataframe
+            header. If more than one label name is provided, the resulting
+            dataframe will have a multi-level column header. Providing values
+            for both ``label`` and ``labels`` is an error.
+
+        :rtype: :class:`pandas.DataFrame`
+        :returns: A dataframe where each column represents one time series.
+        """
+        import pandas   # pylint: disable=import-error
+
+        if label is not None and labels is not None:
+            raise ValueError('Cannot specify both "label" and "labels".')
+        elif not (labels or labels is None):
+            raise ValueError('"labels" must be non-empty or None.')
+
+        columns = []
+        headers = []
+        for time_series in self:
+            pandas_series = pandas.Series(
+                data=[p.value for p in time_series.points],
+                index=[p.end_time for p in time_series.points],
+            )
+            columns.append(pandas_series)
+            headers.append(time_series.header())
+
+        # Implement a smart default of using all available labels.
+        if label is None and labels is None:
+            resource_labels = set(itertools.chain.from_iterable(
+                header.resource.labels for header in headers))
+            metric_labels = set(itertools.chain.from_iterable(
+                header.metric.labels for header in headers))
+            labels = (['resource_type'] +
+                      _sorted_resource_labels(resource_labels) +
+                      sorted(metric_labels))
+
+        # Assemble the columns into a DataFrame.
+        dataframe = pandas.DataFrame(columns).T
+
+        # Convert the timestamp strings into a DatetimeIndex.
+        dataframe.index = pandas.to_datetime(dataframe.index)
+
+        # Build a column Index or MultiIndex from the label values. Do not
+        # include level names in the column header if the user requested a
+        # single-level header by specifying "label".
+        level_names = labels or None
+        label_keys = labels or [label]
+        dataframe.columns = pandas.MultiIndex.from_arrays(
+            [[header.labels.get(key, '') for header in headers]
+             for key in label_keys],
+            names=level_names)
+
+        # Sort the rows just in case (since the API doesn't guarantee the
+        # ordering), and sort the columns lexicographically.
+        return dataframe.sort_index(axis=0).sort_index(axis=1)
+
+    def copy(self):
+        """Copy the query object.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        # Using copy.deepcopy() would be appropriate, except that we want
+        # to copy self._client only as a reference.
+        new_query = copy.copy(self)
+        new_query._filter = copy.copy(self._filter)
+        return new_query
+
+
+class _Filter(object):
+    """Helper for assembling a filter string."""
+
+    def __init__(self, metric_type):
+        self.metric_type = metric_type
+        self.group_id = None
+        self.projects = ()
+        self.resource_label_filter = None
+        self.metric_label_filter = None
+
+    def select_resources(self, *args, **kwargs):
+        """Select by resource labels.
+
+        See :meth:`Query.select_resources`.
+        """
+        self.resource_label_filter = _build_label_filter('resource',
+                                                         *args, **kwargs)
+
+    def select_metrics(self, *args, **kwargs):
+        """Select by metric labels.
+
+        See :meth:`Query.select_metrics`.
+        """
+        self.metric_label_filter = _build_label_filter('metric',
+                                                       *args, **kwargs)
+
+    def __str__(self):
+        filters = ['metric.type = "{type}"'.format(type=self.metric_type)]
+        if self.group_id is not None:
+            filters.append('group.id = "{id}"'.format(id=self.group_id))
+        if self.projects:
+            filters.append(
+                ' OR '.join('project = "{project}"'.format(project=project)
+                            for project in self.projects))
+        if self.resource_label_filter:
+            filters.append(self.resource_label_filter)
+        if self.metric_label_filter:
+            filters.append(self.metric_label_filter)
+
+        # Parentheses are never actually required, because OR binds more
+        # tightly than AND in the Monitoring API's filter syntax.
+        return ' AND '.join(filters)
+
+
+def _build_label_filter(category, *args, **kwargs):
+    """Construct a filter string to filter on metric or resource labels."""
+    terms = list(args)
+    for key in kwargs:
+        value = kwargs[key]
+        if value is None:
+            continue
+
+        suffix = None
+        if key.endswith('_prefix') or key.endswith('_suffix'):
+            key, suffix = key.rsplit('_', 1)
+
+        if category == 'resource' and key == 'resource_type':
+            key = 'resource.type'
+        else:
+            key = '.'.join((category, 'label', key))
+
+        if suffix == 'prefix':
+            term = '{key} = starts_with("{value}")'
+        elif suffix == 'suffix':
+            term = '{key} = ends_with("{value}")'
+        else:
+            term = '{key} = "{value}"'
+
+        terms.append(term.format(key=key, value=value))
+
+    return ' AND '.join(sorted(terms))
+
+
+def _sorted_resource_labels(labels):
+    """Sort label names, putting well-known resource labels first."""
+    head = [label for label in TOP_RESOURCE_LABELS if label in labels]
+    tail = sorted(label for label in labels
+                  if label not in TOP_RESOURCE_LABELS)
+    return head + tail
+
+
+def _format_timestamp(timestamp):
+    """Convert a datetime object to a string as required by the API.
+
+    :type timestamp: :class:`datetime.datetime`
+    :param timestamp: A datetime object.
+
+    :rtype: string
+    :returns: The formatted timestamp. For example:
+        ``"2016-02-17T19:18:01.763000Z"``
+    """
+    if timestamp.tzinfo is not None:
+        # Convert to UTC and remove the time zone info.
+        timestamp = timestamp.replace(tzinfo=None) - timestamp.utcoffset()
+
+    return timestamp.isoformat() + 'Z'
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index c24117a6bda7..ae9702a0565d 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -158,6 +158,8 @@ def __repr__(self):
 class Resource(collections.namedtuple('Resource', 'type labels')):
     """A monitored resource identified by specifying values for all labels.
 
+    This is a named tuple. See :func:`collections.namedtuple`.
+
     :type type: string
     :param type: The resource type name.
 
diff --git a/gcloud/monitoring/test_query.py b/gcloud/monitoring/test_query.py
new file mode 100644
index 000000000000..eaf84094f710
--- /dev/null
+++ b/gcloud/monitoring/test_query.py
@@ -0,0 +1,654 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+PROJECT = 'my-project'
+
+METRIC_TYPE = 'compute.googleapis.com/instance/uptime'
+METRIC_LABELS = {'instance_name': 'instance-1'}
+METRIC_LABELS2 = {'instance_name': 'instance-2'}
+
+RESOURCE_TYPE = 'gce_instance'
+RESOURCE_LABELS = {
+    'project_id': 'my-project',
+    'zone': 'us-east1-a',
+    'instance_id': '1234567890123456789',
+}
+RESOURCE_LABELS2 = {
+    'project_id': 'my-project',
+    'zone': 'us-east1-b',
+    'instance_id': '9876543210987654321',
+}
+
+METRIC_KIND = 'DELTA'
+VALUE_TYPE = 'DOUBLE'
+
+TS0 = '2016-04-06T22:05:00.042Z'
+TS1 = '2016-04-06T22:05:01.042Z'
+TS2 = '2016-04-06T22:05:02.042Z'
+
+
+class TestAligner(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.query import Aligner
+        return Aligner
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(), 'ALIGN_RATE'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
+class TestReducer(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.query import Reducer
+        return Reducer
+
+    def test_one(self):
+        self.assertTrue(hasattr(self._getTargetClass(),
+                                'REDUCE_PERCENTILE_99'))
+
+    def test_names(self):
+        for name in self._getTargetClass().__dict__:
+            if not name.startswith('_'):
+                self.assertEqual(getattr(self._getTargetClass(), name), name)
+
+
+class TestQuery(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.query import Query
+        return Query
+
+    def _makeOne(self, *args, **kwargs):
+        return self._getTargetClass()(*args, **kwargs)
+
+    def test_constructor_minimal(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client)
+
+        self.assertEqual(query._client, client)
+        self.assertEqual(query._filter.metric_type,
+                         self._getTargetClass().DEFAULT_METRIC_TYPE)
+
+        self.assertIsNone(query._start_time)
+        self.assertIsNone(query._end_time)
+
+        self.assertIsNone(query._per_series_aligner)
+        self.assertIsNone(query._alignment_period_seconds)
+        self.assertIsNone(query._cross_series_reducer)
+        self.assertEqual(query._group_by_fields, ())
+
+    def test_constructor_maximal(self):
+        import datetime
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
+        DAYS, HOURS, MINUTES = 1, 2, 3
+        T0 = T1 - datetime.timedelta(days=DAYS, hours=HOURS, minutes=MINUTES)
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE,
+                              end_time=T1,
+                              days=DAYS, hours=HOURS, minutes=MINUTES)
+
+        self.assertEqual(query._client, client)
+        self.assertEqual(query._filter.metric_type, METRIC_TYPE)
+
+        self.assertEqual(query._start_time, T0)
+        self.assertEqual(query._end_time, T1)
+
+        self.assertIsNone(query._per_series_aligner)
+        self.assertIsNone(query._alignment_period_seconds)
+        self.assertIsNone(query._cross_series_reducer)
+        self.assertEqual(query._group_by_fields, ())
+
+    def test_constructor_default_end_time(self):
+        import datetime
+        from gcloud._testing import _Monkey
+        from gcloud.monitoring import query as MUT
+
+        MINUTES = 5
+        NOW, T0, T1 = [
+            datetime.datetime(2016, 4, 7, 2, 30, 30),
+            datetime.datetime(2016, 4, 7, 2, 25, 0),
+            datetime.datetime(2016, 4, 7, 2, 30, 0),
+        ]
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        with _Monkey(MUT, _NOW=lambda: NOW):
+            query = self._makeOne(client, METRIC_TYPE, minutes=MINUTES)
+
+        self.assertEqual(query._start_time, T0)
+        self.assertEqual(query._end_time, T1)
+
+    def test_constructor_nonzero_duration_illegal(self):
+        import datetime
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
+        client = _Client(project=PROJECT, connection=_Connection())
+        with self.assertRaises(ValueError):
+            self._makeOne(client, METRIC_TYPE, end_time=T1)
+
+    def test_execution_without_interval_illegal(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        with self.assertRaises(ValueError):
+            list(query)
+
+    def test_metric_type(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        self.assertEqual(query.metric_type, METRIC_TYPE)
+
+    def test_filter(self):
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_group(self):
+        GROUP = '1234567'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_group(GROUP)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND group.id = "{group}"'
+        ).format(type=METRIC_TYPE, group=GROUP)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_projects(self):
+        PROJECT1, PROJECT2 = 'project-1', 'project-2'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_projects(PROJECT1, PROJECT2)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND project = "{project1}" OR project = "{project2}"'
+        ).format(type=METRIC_TYPE, project1=PROJECT1, project2=PROJECT2)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_resources(self):
+        ZONE_PREFIX = 'europe-'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_resources(zone_prefix=ZONE_PREFIX)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND resource.label.zone = starts_with("{prefix}")'
+        ).format(type=METRIC_TYPE, prefix=ZONE_PREFIX)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_metrics(self):
+        INSTANCE = 'my-instance'
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_metrics(instance_name=INSTANCE)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND metric.label.instance_name = "{instance}"'
+        ).format(type=METRIC_TYPE, instance=INSTANCE)
+        self.assertEqual(query.filter, expected)
+
+    def test_request_parameters_minimal(self):
+        import datetime
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(end_time=T1)
+        expected = [
+            ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+            ('interval.endTime', T1.isoformat() + 'Z'),
+        ]
+        self.assertEqual(query._build_query_params(), expected)
+
+    def test_request_parameters_maximal(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 7, 2, 0, 0)
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
+
+        ALIGNER = 'ALIGN_DELTA'
+        MINUTES, SECONDS, PERIOD = 1, 30, '90s'
+
+        REDUCER = 'REDUCE_MEAN'
+        FIELD1, FIELD2 = 'resource.zone', 'metric.instance_name'
+
+        PAGE_SIZE = 100
+        PAGE_TOKEN = 'second-page-please'
+
+        client = _Client(project=PROJECT, connection=_Connection())
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        query = query.align(ALIGNER, minutes=MINUTES, seconds=SECONDS)
+        query = query.reduce(REDUCER, FIELD1, FIELD2)
+        actual = query._build_query_params(headers_only=True,
+                                           page_size=PAGE_SIZE,
+                                           page_token=PAGE_TOKEN)
+        expected = [
+            ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+            ('interval.endTime', T1.isoformat() + 'Z'),
+            ('interval.startTime', T0.isoformat() + 'Z'),
+            ('aggregation.perSeriesAligner', ALIGNER),
+            ('aggregation.alignmentPeriod', PERIOD),
+            ('aggregation.crossSeriesReducer', REDUCER),
+            ('aggregation.groupByFields', FIELD1),
+            ('aggregation.groupByFields', FIELD2),
+            ('view', 'HEADERS'),
+            ('pageSize', PAGE_SIZE),
+            ('pageToken', PAGE_TOKEN),
+        ]
+        self.assertEqual(actual, expected)
+
+    def test_iteration(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        INTERVAL1 = {'startTime': TS0, 'endTime': TS1}
+        INTERVAL2 = {'startTime': TS1, 'endTime': TS2}
+
+        VALUE1 = 60  # seconds
+        VALUE2 = 60.001  # seconds
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE1}},
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE1}},
+            ],
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE2}},
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE2}},
+            ],
+        }
+
+        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual([p.value for p in series1.points], [VALUE1, VALUE1])
+        self.assertEqual([p.value for p in series2.points], [VALUE2, VALUE2])
+        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2])
+        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2])
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+            ],
+        }
+
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
+    def test_iteration_paged(self):
+        import copy
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        INTERVAL1 = {'startTime': TS0, 'endTime': TS1}
+        INTERVAL2 = {'startTime': TS1, 'endTime': TS2}
+
+        VALUE1 = 60  # seconds
+        VALUE2 = 60.001  # seconds
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE1}},
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE1}},
+            ],
+        }
+        SERIES2_PART1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE2}},
+            ],
+        }
+        SERIES2_PART2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE2}},
+            ],
+        }
+
+        TOKEN = 'second-page-please'
+        RESPONSE1 = {'timeSeries': [SERIES1, SERIES2_PART1],
+                     'nextPageToken': TOKEN}
+        RESPONSE2 = {'timeSeries': [SERIES2_PART2]}
+
+        connection = _Connection(RESPONSE1, RESPONSE2)
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual([p.value for p in series1.points], [VALUE1, VALUE1])
+        self.assertEqual([p.value for p in series2.points], [VALUE2, VALUE2])
+        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2])
+        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2])
+
+        expected_request1 = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+            ],
+        }
+
+        expected_request2 = copy.deepcopy(expected_request1)
+        expected_request2['query_params'].append(('pageToken', TOKEN))
+
+        request1, request2 = connection._requested
+        self.assertEqual(request1, expected_request1)
+        self.assertEqual(request2, expected_request2)
+
+    def test_iteration_empty(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        connection = _Connection({})
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 0)
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+            ],
+        }
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
+    def test_iteration_headers_only(self):
+        import datetime
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metricKind': METRIC_KIND,
+            'valueType': VALUE_TYPE,
+        }
+
+        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
+
+        connection = _Connection(RESPONSE)
+        client = _Client(project=PROJECT, connection=connection)
+        query = self._makeOne(client, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query.iter(headers_only=True))
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual(series1.points, [])
+        self.assertEqual(series2.points, [])
+
+        expected_request = {
+            'method': 'GET',
+            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
+            'query_params': [
+                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
+                ('interval.endTime', T1.isoformat() + 'Z'),
+                ('interval.startTime', T0.isoformat() + 'Z'),
+                ('view', 'HEADERS'),
+            ],
+        }
+
+        request, = connection._requested
+        self.assertEqual(request, expected_request)
+
+
+class Test_Filter(unittest2.TestCase):
+
+    def _getTargetClass(self):
+        from gcloud.monitoring.query import _Filter
+        return _Filter
+
+    def _makeOne(self, metric_type):
+        return self._getTargetClass()(metric_type)
+
+    def test_minimal(self):
+        obj = self._makeOne(METRIC_TYPE)
+        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
+        self.assertEqual(str(obj), expected)
+
+    def test_maximal(self):
+        obj = self._makeOne(METRIC_TYPE)
+        obj.group_id = '1234567'
+        obj.projects = 'project-1', 'project-2'
+        obj.select_resources(resource_type='some-resource',
+                             resource_label='foo')
+        obj.select_metrics(metric_label_prefix='bar-')
+
+        expected = (
+            'metric.type = "{type}"'
+            ' AND group.id = "1234567"'
+            ' AND project = "project-1" OR project = "project-2"'
+            ' AND resource.label.resource_label = "foo"'
+            ' AND resource.type = "some-resource"'
+            ' AND metric.label.metric_label = starts_with("bar-")'
+        ).format(type=METRIC_TYPE)
+
+        self.assertEqual(str(obj), expected)
+
+
+class Test__build_label_filter(unittest2.TestCase):
+
+    def _callFUT(self, *args, **kwargs):
+        from gcloud.monitoring.query import _build_label_filter
+        return _build_label_filter(*args, **kwargs)
+
+    def test_no_labels(self):
+        self.assertEqual(self._callFUT('resource'), '')
+
+    def test_label_is_none(self):
+        self.assertEqual(self._callFUT('resource', foo=None), '')
+
+    def test_metric_labels(self):
+        actual = self._callFUT(
+            'metric',
+            alpha_prefix='a-',
+            beta_gamma_suffix='-b',
+            delta_epsilon='xyz',
+        )
+        expected = (
+            'metric.label.alpha = starts_with("a-")'
+            ' AND metric.label.beta_gamma = ends_with("-b")'
+            ' AND metric.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_resource_labels(self):
+        actual = self._callFUT(
+            'resource',
+            alpha_prefix='a-',
+            beta_gamma_suffix='-b',
+            delta_epsilon='xyz',
+        )
+        expected = (
+            'resource.label.alpha = starts_with("a-")'
+            ' AND resource.label.beta_gamma = ends_with("-b")'
+            ' AND resource.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_raw_label_filters(self):
+        actual = self._callFUT(
+            'resource',
+            'resource.label.alpha = starts_with("a-")',
+            'resource.label.beta_gamma = ends_with("-b")',
+            'resource.label.delta_epsilon = "xyz"',
+        )
+        expected = (
+            'resource.label.alpha = starts_with("a-")'
+            ' AND resource.label.beta_gamma = ends_with("-b")'
+            ' AND resource.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_resource_type(self):
+        actual = self._callFUT('resource', resource_type='foo')
+        expected = 'resource.type = "foo"'
+        self.assertEqual(actual, expected)
+
+    def test_resource_type_prefix(self):
+        actual = self._callFUT('resource', resource_type_prefix='foo-')
+        expected = 'resource.type = starts_with("foo-")'
+        self.assertEqual(actual, expected)
+
+    def test_resource_type_suffix(self):
+        actual = self._callFUT('resource', resource_type_suffix='-foo')
+        expected = 'resource.type = ends_with("-foo")'
+        self.assertEqual(actual, expected)
+
+
+class Test__sorted_resource_labels(unittest2.TestCase):
+
+    def _callFUT(self, labels):
+        from gcloud.monitoring.query import _sorted_resource_labels
+        return _sorted_resource_labels(labels)
+
+    def test_empty(self):
+        self.assertEqual(self._callFUT([]), [])
+
+    def test_sorted(self):
+        from gcloud.monitoring.query import TOP_RESOURCE_LABELS
+        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        self.assertEqual(self._callFUT(EXPECTED), EXPECTED)
+
+    def test_reversed(self):
+        from gcloud.monitoring.query import TOP_RESOURCE_LABELS
+        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        INPUT = list(reversed(EXPECTED))
+        self.assertEqual(self._callFUT(INPUT), EXPECTED)
+
+
+class Test__format_timestamp(unittest2.TestCase):
+
+    def _callFUT(self, timestamp):
+        from gcloud.monitoring.query import _format_timestamp
+        return _format_timestamp(timestamp)
+
+    def test_naive(self):
+        from datetime import datetime
+        TIMESTAMP = datetime(2016, 4, 5, 13, 30, 0)
+        timestamp = self._callFUT(TIMESTAMP)
+        self.assertEqual(timestamp, '2016-04-05T13:30:00Z')
+
+    def test_with_timezone(self):
+        from datetime import datetime
+        from gcloud._helpers import UTC
+        TIMESTAMP = datetime(2016, 4, 5, 13, 30, 0, tzinfo=UTC)
+        timestamp = self._callFUT(TIMESTAMP)
+        self.assertEqual(timestamp, '2016-04-05T13:30:00Z')
+
+
+class _Connection(object):
+
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self._requested = []
+
+    def api_request(self, **kwargs):
+        from gcloud.exceptions import NotFound
+        self._requested.append(kwargs)
+        try:
+            return self._responses.pop(0)
+        except IndexError:  # pragma: NO COVER
+            raise NotFound('miss')
+
+
+class _Client(object):
+
+    def __init__(self, project, connection):
+        self.project = project
+        self.connection = connection
diff --git a/gcloud/monitoring/test_timeseries.py b/gcloud/monitoring/test_timeseries.py
index 4999c38be90b..ae2609641d5c 100644
--- a/gcloud/monitoring/test_timeseries.py
+++ b/gcloud/monitoring/test_timeseries.py
@@ -14,11 +14,8 @@
 
 import unittest2
 
-PROJECT = 'my-project'
-
 METRIC_TYPE = 'compute.googleapis.com/instance/uptime'
 METRIC_LABELS = {'instance_name': 'instance-1'}
-METRIC_LABELS2 = {'instance_name': 'instance-2'}
 
 RESOURCE_TYPE = 'gce_instance'
 RESOURCE_LABELS = {
@@ -26,11 +23,6 @@
     'zone': 'us-east1-a',
     'instance_id': '1234567890123456789',
 }
-RESOURCE_LABELS2 = {
-    'project_id': 'my-project',
-    'zone': 'us-east1-b',
-    'instance_id': '9876543210987654321',
-}
 
 METRIC_KIND = 'DELTA'
 VALUE_TYPE = 'DOUBLE'
@@ -40,453 +32,6 @@
 TS2 = '2016-04-06T22:05:02.042Z'
 
 
-class TestAligner(unittest2.TestCase):
-
-    def _getTargetClass(self):
-        from gcloud.monitoring.timeseries import Aligner
-        return Aligner
-
-    def test_one(self):
-        self.assertTrue(hasattr(self._getTargetClass(), 'ALIGN_RATE'))
-
-    def test_names(self):
-        for name in self._getTargetClass().__dict__:
-            if not name.startswith('_'):
-                self.assertEqual(getattr(self._getTargetClass(), name), name)
-
-
-class TestReducer(unittest2.TestCase):
-
-    def _getTargetClass(self):
-        from gcloud.monitoring.timeseries import Reducer
-        return Reducer
-
-    def test_one(self):
-        self.assertTrue(hasattr(self._getTargetClass(),
-                                'REDUCE_PERCENTILE_99'))
-
-    def test_names(self):
-        for name in self._getTargetClass().__dict__:
-            if not name.startswith('_'):
-                self.assertEqual(getattr(self._getTargetClass(), name), name)
-
-
-class TestQuery(unittest2.TestCase):
-
-    def _getTargetClass(self):
-        from gcloud.monitoring.timeseries import Query
-        return Query
-
-    def _makeOne(self, *args, **kwargs):
-        return self._getTargetClass()(*args, **kwargs)
-
-    def test_constructor_minimal(self):
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client)
-
-        self.assertEqual(query._client, client)
-        self.assertEqual(query._filter.metric_type,
-                         self._getTargetClass().DEFAULT_METRIC_TYPE)
-
-        self.assertIsNone(query._start_time)
-        self.assertIsNone(query._end_time)
-
-        self.assertIsNone(query._per_series_aligner)
-        self.assertIsNone(query._alignment_period_seconds)
-        self.assertIsNone(query._cross_series_reducer)
-        self.assertEqual(query._group_by_fields, ())
-
-    def test_constructor_maximal(self):
-        import datetime
-
-        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
-        DAYS, HOURS, MINUTES = 1, 2, 3
-        T0 = T1 - datetime.timedelta(days=DAYS, hours=HOURS, minutes=MINUTES)
-
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE,
-                              end_time=T1,
-                              days=DAYS, hours=HOURS, minutes=MINUTES)
-
-        self.assertEqual(query._client, client)
-        self.assertEqual(query._filter.metric_type, METRIC_TYPE)
-
-        self.assertEqual(query._start_time, T0)
-        self.assertEqual(query._end_time, T1)
-
-        self.assertIsNone(query._per_series_aligner)
-        self.assertIsNone(query._alignment_period_seconds)
-        self.assertIsNone(query._cross_series_reducer)
-        self.assertEqual(query._group_by_fields, ())
-
-    def test_constructor_default_end_time(self):
-        import datetime
-        from gcloud._testing import _Monkey
-        from gcloud.monitoring import timeseries as MUT
-
-        MINUTES = 5
-        NOW, T0, T1 = [
-            datetime.datetime(2016, 4, 7, 2, 30, 30),
-            datetime.datetime(2016, 4, 7, 2, 25, 0),
-            datetime.datetime(2016, 4, 7, 2, 30, 0),
-        ]
-
-        client = _Client(project=PROJECT, connection=_Connection())
-        with _Monkey(MUT, _NOW=lambda: NOW):
-            query = self._makeOne(client, METRIC_TYPE, minutes=MINUTES)
-
-        self.assertEqual(query._start_time, T0)
-        self.assertEqual(query._end_time, T1)
-
-    def test_constructor_nonzero_duration_illegal(self):
-        import datetime
-        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
-        client = _Client(project=PROJECT, connection=_Connection())
-        with self.assertRaises(ValueError):
-            self._makeOne(client, METRIC_TYPE, end_time=T1)
-
-    def test_execution_without_interval_illegal(self):
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        with self.assertRaises(ValueError):
-            list(query)
-
-    def test_metric_type(self):
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        self.assertEqual(query.metric_type, METRIC_TYPE)
-
-    def test_filter(self):
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
-        self.assertEqual(query.filter, expected)
-
-    def test_filter_by_group(self):
-        GROUP = '1234567'
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_group(GROUP)
-        expected = (
-            'metric.type = "{type}"'
-            ' AND group.id = "{group}"'
-        ).format(type=METRIC_TYPE, group=GROUP)
-        self.assertEqual(query.filter, expected)
-
-    def test_filter_by_projects(self):
-        PROJECT1, PROJECT2 = 'project-1', 'project-2'
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_projects(PROJECT1, PROJECT2)
-        expected = (
-            'metric.type = "{type}"'
-            ' AND project = "{project1}" OR project = "{project2}"'
-        ).format(type=METRIC_TYPE, project1=PROJECT1, project2=PROJECT2)
-        self.assertEqual(query.filter, expected)
-
-    def test_filter_by_resources(self):
-        ZONE_PREFIX = 'europe-'
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_resources(zone_prefix=ZONE_PREFIX)
-        expected = (
-            'metric.type = "{type}"'
-            ' AND resource.label.zone = starts_with("{prefix}")'
-        ).format(type=METRIC_TYPE, prefix=ZONE_PREFIX)
-        self.assertEqual(query.filter, expected)
-
-    def test_filter_by_metrics(self):
-        INSTANCE = 'my-instance'
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_metrics(instance_name=INSTANCE)
-        expected = (
-            'metric.type = "{type}"'
-            ' AND metric.label.instance_name = "{instance}"'
-        ).format(type=METRIC_TYPE, instance=INSTANCE)
-        self.assertEqual(query.filter, expected)
-
-    def test_request_parameters_minimal(self):
-        import datetime
-
-        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
-
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_interval(end_time=T1)
-        expected = [
-            ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
-            ('interval.endTime', T1.isoformat() + 'Z'),
-        ]
-        self.assertEqual(query._build_query_params(), expected)
-
-    def test_request_parameters_maximal(self):
-        import datetime
-
-        T0 = datetime.datetime(2016, 4, 7, 2, 0, 0)
-        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
-
-        ALIGNER = 'ALIGN_DELTA'
-        MINUTES, SECONDS, PERIOD = 1, 30, '90s'
-
-        REDUCER = 'REDUCE_MEAN'
-        FIELD1, FIELD2 = 'resource.zone', 'metric.instance_name'
-
-        PAGE_SIZE = 100
-        PAGE_TOKEN = 'second-page-please'
-
-        client = _Client(project=PROJECT, connection=_Connection())
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_interval(start_time=T0, end_time=T1)
-        query = query.align(ALIGNER, minutes=MINUTES, seconds=SECONDS)
-        query = query.reduce(REDUCER, FIELD1, FIELD2)
-        actual = query._build_query_params(headers_only=True,
-                                           page_size=PAGE_SIZE,
-                                           page_token=PAGE_TOKEN)
-        expected = [
-            ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
-            ('interval.endTime', T1.isoformat() + 'Z'),
-            ('interval.startTime', T0.isoformat() + 'Z'),
-            ('aggregation.perSeriesAligner', ALIGNER),
-            ('aggregation.alignmentPeriod', PERIOD),
-            ('aggregation.crossSeriesReducer', REDUCER),
-            ('aggregation.groupByFields', FIELD1),
-            ('aggregation.groupByFields', FIELD2),
-            ('view', 'HEADERS'),
-            ('pageSize', PAGE_SIZE),
-            ('pageToken', PAGE_TOKEN),
-        ]
-        self.assertEqual(actual, expected)
-
-    def test_iteration(self):
-        import datetime
-
-        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
-        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
-
-        INTERVAL1 = {'startTime': TS0, 'endTime': TS1}
-        INTERVAL2 = {'startTime': TS1, 'endTime': TS2}
-
-        VALUE1 = 60  # seconds
-        VALUE2 = 60.001  # seconds
-
-        SERIES1 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-            'points': [
-                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE1}},
-                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE1}},
-            ],
-        }
-        SERIES2 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-            'points': [
-                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE2}},
-                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE2}},
-            ],
-        }
-
-        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
-
-        connection = _Connection(RESPONSE)
-        client = _Client(project=PROJECT, connection=connection)
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_interval(start_time=T0, end_time=T1)
-        response = list(query)
-
-        self.assertEqual(len(response), 2)
-        series1, series2 = response
-
-        self.assertEqual(series1.metric.labels, METRIC_LABELS)
-        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
-        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
-        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
-
-        self.assertEqual([p.value for p in series1.points], [VALUE1, VALUE1])
-        self.assertEqual([p.value for p in series2.points], [VALUE2, VALUE2])
-        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2])
-        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2])
-
-        expected_request = {
-            'method': 'GET',
-            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
-            'query_params': [
-                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
-                ('interval.endTime', T1.isoformat() + 'Z'),
-                ('interval.startTime', T0.isoformat() + 'Z'),
-            ],
-        }
-
-        request, = connection._requested
-        self.assertEqual(request, expected_request)
-
-    def test_iteration_paged(self):
-        import copy
-        import datetime
-
-        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
-        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
-
-        INTERVAL1 = {'startTime': TS0, 'endTime': TS1}
-        INTERVAL2 = {'startTime': TS1, 'endTime': TS2}
-
-        VALUE1 = 60  # seconds
-        VALUE2 = 60.001  # seconds
-
-        SERIES1 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-            'points': [
-                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE1}},
-                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE1}},
-            ],
-        }
-        SERIES2_PART1 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-            'points': [
-                {'interval': INTERVAL2, 'value': {'doubleValue': VALUE2}},
-            ],
-        }
-        SERIES2_PART2 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-            'points': [
-                {'interval': INTERVAL1, 'value': {'doubleValue': VALUE2}},
-            ],
-        }
-
-        TOKEN = 'second-page-please'
-        RESPONSE1 = {'timeSeries': [SERIES1, SERIES2_PART1],
-                     'nextPageToken': TOKEN}
-        RESPONSE2 = {'timeSeries': [SERIES2_PART2]}
-
-        connection = _Connection(RESPONSE1, RESPONSE2)
-        client = _Client(project=PROJECT, connection=connection)
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_interval(start_time=T0, end_time=T1)
-        response = list(query)
-
-        self.assertEqual(len(response), 2)
-        series1, series2 = response
-
-        self.assertEqual(series1.metric.labels, METRIC_LABELS)
-        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
-        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
-        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
-
-        self.assertEqual([p.value for p in series1.points], [VALUE1, VALUE1])
-        self.assertEqual([p.value for p in series2.points], [VALUE2, VALUE2])
-        self.assertEqual([p.end_time for p in series1.points], [TS1, TS2])
-        self.assertEqual([p.end_time for p in series2.points], [TS1, TS2])
-
-        expected_request1 = {
-            'method': 'GET',
-            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
-            'query_params': [
-                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
-                ('interval.endTime', T1.isoformat() + 'Z'),
-                ('interval.startTime', T0.isoformat() + 'Z'),
-            ],
-        }
-
-        expected_request2 = copy.deepcopy(expected_request1)
-        expected_request2['query_params'].append(('pageToken', TOKEN))
-
-        request1, request2 = connection._requested
-        self.assertEqual(request1, expected_request1)
-        self.assertEqual(request2, expected_request2)
-
-    def test_iteration_empty(self):
-        import datetime
-
-        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
-        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
-
-        connection = _Connection({})
-        client = _Client(project=PROJECT, connection=connection)
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_interval(start_time=T0, end_time=T1)
-        response = list(query)
-
-        self.assertEqual(len(response), 0)
-
-        expected_request = {
-            'method': 'GET',
-            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
-            'query_params': [
-                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
-                ('interval.endTime', T1.isoformat() + 'Z'),
-                ('interval.startTime', T0.isoformat() + 'Z'),
-            ],
-        }
-        request, = connection._requested
-        self.assertEqual(request, expected_request)
-
-    def test_iteration_headers_only(self):
-        import datetime
-
-        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
-        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
-
-        SERIES1 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-        }
-        SERIES2 = {
-            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
-            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
-            'metricKind': METRIC_KIND,
-            'valueType': VALUE_TYPE,
-        }
-
-        RESPONSE = {'timeSeries': [SERIES1, SERIES2]}
-
-        connection = _Connection(RESPONSE)
-        client = _Client(project=PROJECT, connection=connection)
-        query = self._makeOne(client, METRIC_TYPE)
-        query = query.select_interval(start_time=T0, end_time=T1)
-        response = list(query.iter(headers_only=True))
-
-        self.assertEqual(len(response), 2)
-        series1, series2 = response
-
-        self.assertEqual(series1.metric.labels, METRIC_LABELS)
-        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
-        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
-        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
-
-        self.assertEqual(series1.points, [])
-        self.assertEqual(series2.points, [])
-
-        expected_request = {
-            'method': 'GET',
-            'path': '/projects/{project}/timeSeries/'.format(project=PROJECT),
-            'query_params': [
-                ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
-                ('interval.endTime', T1.isoformat() + 'Z'),
-                ('interval.startTime', T0.isoformat() + 'Z'),
-                ('view', 'HEADERS'),
-            ],
-        }
-
-        request, = connection._requested
-        self.assertEqual(request, expected_request)
-
-
 class TestTimeSeries(unittest2.TestCase):
 
     def _getTargetClass(self):
@@ -648,170 +193,3 @@ def test_from_dict_int64(self):
         self.assertIsNone(point.start_time)
         self.assertEqual(point.end_time, TS1)
         self.assertEqual(point.value, VALUE)
-
-
-class Test_Filter(unittest2.TestCase):
-
-    def _getTargetClass(self):
-        from gcloud.monitoring.timeseries import _Filter
-        return _Filter
-
-    def _makeOne(self, metric_type):
-        return self._getTargetClass()(metric_type)
-
-    def test_minimal(self):
-        obj = self._makeOne(METRIC_TYPE)
-        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
-        self.assertEqual(str(obj), expected)
-
-    def test_maximal(self):
-        obj = self._makeOne(METRIC_TYPE)
-        obj.group_id = '1234567'
-        obj.projects = 'project-1', 'project-2'
-        obj.select_resources(resource_type='some-resource',
-                             resource_label='foo')
-        obj.select_metrics(metric_label_prefix='bar-')
-
-        expected = (
-            'metric.type = "{type}"'
-            ' AND group.id = "1234567"'
-            ' AND project = "project-1" OR project = "project-2"'
-            ' AND resource.label.resource_label = "foo"'
-            ' AND resource.type = "some-resource"'
-            ' AND metric.label.metric_label = starts_with("bar-")'
-        ).format(type=METRIC_TYPE)
-
-        self.assertEqual(str(obj), expected)
-
-
-class Test__build_label_filter(unittest2.TestCase):
-
-    def _callFUT(self, *args, **kwargs):
-        from gcloud.monitoring.timeseries import _build_label_filter
-        return _build_label_filter(*args, **kwargs)
-
-    def test_no_labels(self):
-        self.assertEqual(self._callFUT('resource'), '')
-
-    def test_label_is_none(self):
-        self.assertEqual(self._callFUT('resource', foo=None), '')
-
-    def test_metric_labels(self):
-        actual = self._callFUT(
-            'metric',
-            alpha_prefix='a-',
-            beta_gamma_suffix='-b',
-            delta_epsilon='xyz',
-        )
-        expected = (
-            'metric.label.alpha = starts_with("a-")'
-            ' AND metric.label.beta_gamma = ends_with("-b")'
-            ' AND metric.label.delta_epsilon = "xyz"'
-        )
-        self.assertEqual(actual, expected)
-
-    def test_resource_labels(self):
-        actual = self._callFUT(
-            'resource',
-            alpha_prefix='a-',
-            beta_gamma_suffix='-b',
-            delta_epsilon='xyz',
-        )
-        expected = (
-            'resource.label.alpha = starts_with("a-")'
-            ' AND resource.label.beta_gamma = ends_with("-b")'
-            ' AND resource.label.delta_epsilon = "xyz"'
-        )
-        self.assertEqual(actual, expected)
-
-    def test_raw_label_filters(self):
-        actual = self._callFUT(
-            'resource',
-            'resource.label.alpha = starts_with("a-")',
-            'resource.label.beta_gamma = ends_with("-b")',
-            'resource.label.delta_epsilon = "xyz"',
-        )
-        expected = (
-            'resource.label.alpha = starts_with("a-")'
-            ' AND resource.label.beta_gamma = ends_with("-b")'
-            ' AND resource.label.delta_epsilon = "xyz"'
-        )
-        self.assertEqual(actual, expected)
-
-    def test_resource_type(self):
-        actual = self._callFUT('resource', resource_type='foo')
-        expected = 'resource.type = "foo"'
-        self.assertEqual(actual, expected)
-
-    def test_resource_type_prefix(self):
-        actual = self._callFUT('resource', resource_type_prefix='foo-')
-        expected = 'resource.type = starts_with("foo-")'
-        self.assertEqual(actual, expected)
-
-    def test_resource_type_suffix(self):
-        actual = self._callFUT('resource', resource_type_suffix='-foo')
-        expected = 'resource.type = ends_with("-foo")'
-        self.assertEqual(actual, expected)
-
-
-class Test__sorted_resource_labels(unittest2.TestCase):
-
-    def _callFUT(self, labels):
-        from gcloud.monitoring.timeseries import _sorted_resource_labels
-        return _sorted_resource_labels(labels)
-
-    def test_empty(self):
-        self.assertEqual(self._callFUT([]), [])
-
-    def test_sorted(self):
-        from gcloud.monitoring.timeseries import TOP_RESOURCE_LABELS
-        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
-        self.assertEqual(self._callFUT(EXPECTED), EXPECTED)
-
-    def test_reversed(self):
-        from gcloud.monitoring.timeseries import TOP_RESOURCE_LABELS
-        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
-        INPUT = list(reversed(EXPECTED))
-        self.assertEqual(self._callFUT(INPUT), EXPECTED)
-
-
-class Test__format_timestamp(unittest2.TestCase):
-
-    def _callFUT(self, timestamp):
-        from gcloud.monitoring.timeseries import _format_timestamp
-        return _format_timestamp(timestamp)
-
-    def test_naive(self):
-        from datetime import datetime
-        TIMESTAMP = datetime(2016, 4, 5, 13, 30, 0)
-        timestamp = self._callFUT(TIMESTAMP)
-        self.assertEqual(timestamp, '2016-04-05T13:30:00Z')
-
-    def test_with_timezone(self):
-        from datetime import datetime
-        from gcloud._helpers import UTC
-        TIMESTAMP = datetime(2016, 4, 5, 13, 30, 0, tzinfo=UTC)
-        timestamp = self._callFUT(TIMESTAMP)
-        self.assertEqual(timestamp, '2016-04-05T13:30:00Z')
-
-
-class _Connection(object):
-
-    def __init__(self, *responses):
-        self._responses = list(responses)
-        self._requested = []
-
-    def api_request(self, **kwargs):
-        from gcloud.exceptions import NotFound
-        self._requested.append(kwargs)
-        try:
-            return self._responses.pop(0)
-        except IndexError:  # pragma: NO COVER
-            raise NotFound('miss')
-
-
-class _Client(object):
-
-    def __init__(self, project, connection):
-        self.project = project
-        self.connection = connection
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 00aa473035fa..79bea6793419 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -12,10 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Time series in the `Google Monitoring API (V3)`_.
+"""Time series for the `Google Monitoring API (V3)`_.
 
 .. _Google Monitoring API (V3):
-    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
 """
 
 # Features intentionally omitted from this first version of the client library:
@@ -23,583 +23,19 @@
 #   - Natural representation of distribution values.
 
 import collections
-import copy
-import datetime
-import itertools
 
 import six
 
 from gcloud.monitoring.metric import Metric
 from gcloud.monitoring.resource import Resource
 
-TOP_RESOURCE_LABELS = [
-    'project_id',
-    'aws_account',
-    'location',
-    'region',
-    'zone',
-]
-
-_NOW = datetime.datetime.utcnow  # To be replaced by tests.
-
-
-class Aligner(object):
-    """Allowed values for the `supported aligners`_."""
-
-    ALIGN_NONE = 'ALIGN_NONE'
-    ALIGN_DELTA = 'ALIGN_DELTA'
-    ALIGN_RATE = 'ALIGN_RATE'
-    ALIGN_INTERPOLATE = 'ALIGN_INTERPOLATE'
-    ALIGN_NEXT_OLDER = 'ALIGN_NEXT_OLDER'
-    ALIGN_MIN = 'ALIGN_MIN'
-    ALIGN_MAX = 'ALIGN_MAX'
-    ALIGN_MEAN = 'ALIGN_MEAN'
-    ALIGN_COUNT = 'ALIGN_COUNT'
-    ALIGN_SUM = 'ALIGN_SUM'
-    ALIGN_STDDEV = 'ALIGN_STDDEV'
-    ALIGN_COUNT_TRUE = 'ALIGN_COUNT_TRUE'
-    ALIGN_FRACTION_TRUE = 'ALIGN_FRACTION_TRUE'
-
-
-class Reducer(object):
-    """Allowed values for the `supported reducers`_."""
-
-    REDUCE_NONE = 'REDUCE_NONE'
-    REDUCE_MEAN = 'REDUCE_MEAN'
-    REDUCE_MIN = 'REDUCE_MIN'
-    REDUCE_MAX = 'REDUCE_MAX'
-    REDUCE_SUM = 'REDUCE_SUM'
-    REDUCE_STDDEV = 'REDUCE_STDDEV'
-    REDUCE_COUNT = 'REDUCE_COUNT'
-    REDUCE_COUNT_TRUE = 'REDUCE_COUNT_TRUE'
-    REDUCE_FRACTION_TRUE = 'REDUCE_FRACTION_TRUE'
-    REDUCE_PERCENTILE_99 = 'REDUCE_PERCENTILE_99'
-    REDUCE_PERCENTILE_95 = 'REDUCE_PERCENTILE_95'
-    REDUCE_PERCENTILE_50 = 'REDUCE_PERCENTILE_50'
-    REDUCE_PERCENTILE_05 = 'REDUCE_PERCENTILE_05'
-
-
-class Query(object):
-    """Query object for listing time series.
-
-    The preferred way to construct a query object is using the
-    :meth:`~gcloud.monitoring.client.Client.query` method
-    of the :class:`~gcloud.monitoring.client.Client` class.
-
-    :type client: :class:`gcloud.monitoring.client.Client`
-    :param client: The client to use.
-
-    :type metric_type: string
-    :param metric_type: The metric type name. The default value is
-        ``"compute.googleapis.com/instance/cpu/utilization"``, but
-        please note that this default value is provided only for
-        demonstration purposes and is subject to change. See the
-        `supported metrics`_.
-
-    :type end_time: :class:`datetime.datetime` or None
-    :param end_time: The end time (inclusive) of the time interval
-        for which results should be returned, as a datetime object.
-        The default is the start of the current minute.
-
-        The start time (exclusive) is determined by combining the
-        values of  ``days``, ``hours``, and ``minutes``, and
-        subtracting the resulting duration from the end time.
-
-        It is also allowed to omit the end time and duration here,
-        in which case
-        :meth:`~gcloud.monitoring.timeseries.Query.select_interval`
-        must be called before the query is executed.
-
-    :type days: integer
-    :param days: The number of days in the time interval.
-
-    :type hours: integer
-    :param hours: The number of hours in the time interval.
-
-    :type minutes: integer
-    :param minutes: The number of minutes in the time interval.
-
-    :raises: :exc:`ValueError` if ``end_time`` is specified but
-        ``days``, ``hours``, and ``minutes`` are all zero.
-        If you really want to specify a point in time, use
-        :meth:`~gcloud.monitoring.timeseries.Query.select_interval`.
-
-    .. _supported metrics: https://cloud.google.com/monitoring/api/metrics
-    """
-
-    DEFAULT_METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
-
-    def __init__(self, client,
-                 metric_type=DEFAULT_METRIC_TYPE,
-                 end_time=None, days=0, hours=0, minutes=0):
-        start_time = None
-        if days or hours or minutes:
-            if end_time is None:
-                end_time = _NOW().replace(second=0, microsecond=0)
-            start_time = end_time - datetime.timedelta(days=days,
-                                                       hours=hours,
-                                                       minutes=minutes)
-        elif end_time is not None:
-            raise ValueError('Non-zero duration required for time interval.')
-
-        self._client = client
-        self._end_time = end_time
-        self._start_time = start_time
-        self._filter = _Filter(metric_type)
-
-        self._per_series_aligner = None
-        self._alignment_period_seconds = None
-        self._cross_series_reducer = None
-        self._group_by_fields = ()
-
-    def __iter__(self):
-        return self.iter()
-
-    @property
-    def metric_type(self):
-        """The metric type name."""
-        return self._filter.metric_type
-
-    @property
-    def filter(self):
-        """The filter string.
-
-        This is constructed from the metric type, the resource type, and
-        selectors for the group ID, monitored projects, resource labels,
-        and metric labels.
-        """
-        return str(self._filter)
-
-    def select_interval(self, end_time, start_time=None):
-        """Copy the query and set the query time interval.
-
-        :type end_time: :class:`datetime.datetime`
-        :param end_time: The end time (inclusive) of the time interval
-            for which results should be returned, as a datetime object.
-
-        :type start_time: :class:`datetime.datetime` or None
-        :param start_time: The start time (exclusive) of the time interval
-            for which results should be returned, as a datetime object.
-            If not specified, the interval is a point in time.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-        """
-        new_query = self.copy()
-        new_query._end_time = end_time
-        new_query._start_time = start_time
-        return new_query
-
-    def select_group(self, group_id):
-        """Copy the query and add filtering by group.
-
-        :type group_id: string
-        :param group_id: The ID of a group to filter by.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-        """
-        new_query = self.copy()
-        new_query._filter.group_id = group_id
-        return new_query
-
-    def select_projects(self, *args):
-        """Copy the query and add filtering by monitored projects.
-
-        This is only useful if the target project represents a Stackdriver
-        account containing the specified monitored projects.
-
-        Examples::
-
-            query = query.select_projects('project-1')
-            query = query.select_projects('project-1', 'project-2')
-
-        :param args: Project IDs limiting the resources to be included
-            in the query.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-        """
-        new_query = self.copy()
-        new_query._filter.projects = args
-        return new_query
-
-    def select_resources(self, *args, **kwargs):
-        """Copy the query and add filtering by resource labels.
-
-        Examples::
-
-            query = query.select_resources(zone='us-central1-a')
-            query = query.select_resources(zone_prefix='europe-')
-            query = query.select_resources(resource_type='gce_instance')
-
-        A keyword argument ``<label>=<value>`` ordinarily generates a filter
-        expression of the form::
-
-            resource.label.<label> = "<value>"
-
-        However, by adding ``"_prefix"`` or ``"_suffix"`` to the keyword,
-        you can specify a partial match.
-
-        ``<label>_prefix=<value>`` generates::
-
-            resource.label.<label> = starts_with("<value>")
-
-        ``<label>_suffix=<value>`` generates::
-
-            resource.label.<label> = ends_with("<value>")
-
-        As a special case, ``"resource_type"`` is treated as a special
-        pseudo-label corresponding to the filter object ``resource.type``.
-        For example, ``resource_type=<value>`` generates::
-
-            resource.type = "<value>"
-
-        See the `defined resource types`_.
-
-        .. note::
-
-            The label ``"instance_name"`` is a metric label,
-            not a resource label. You would filter on it using
-            ``select_metrics(instance_name=...)``.
-
-        :param args: Raw filter expression strings to include in the
-            conjunction. If just one is provided and no keyword arguments
-            are provided, it can be a disjunction.
-
-        :param kwargs: Label filters to include in the conjunction as
-            described above.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-
-        .. _defined resource types:
-            https://cloud.google.com/monitoring/api/v3/monitored-resources
-        """
-        new_query = self.copy()
-        new_query._filter.select_resources(*args, **kwargs)
-        return new_query
-
-    def select_metrics(self, *args, **kwargs):
-        """Copy the query and add filtering by metric labels.
-
-        Examples::
-
-            query = query.select_metrics(instance_name='myinstance')
-            query = query.select_metrics(instance_name_prefix='mycluster-')
-
-        A keyword argument ``<label>=<value>`` ordinarily generates a filter
-        expression of the form::
-
-            metric.label.<label> = "<value>"
-
-        However, by adding ``"_prefix"`` or ``"_suffix"`` to the keyword,
-        you can specify a partial match.
-
-        ``<label>_prefix=<value>`` generates::
-
-            metric.label.<label> = starts_with("<value>")
-
-        ``<label>_suffix=<value>`` generates::
-
-            metric.label.<label> = ends_with("<value>")
-
-        :param args: Raw filter expression strings to include in the
-            conjunction. If just one is provided and no keyword arguments
-            are provided, it can be a disjunction.
-
-        :param kwargs: Label filters to include in the conjunction as
-            described above.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-        """
-        new_query = self.copy()
-        new_query._filter.select_metrics(*args, **kwargs)
-        return new_query
-
-    def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
-        """Copy the query and add temporal alignment.
-
-        If ``per_series_aligner`` is not ``"ALIGN_NONE"``, each time series
-        will contain data points only on the period boundaries.
-
-        Example::
-
-            query = query.align('ALIGN_MEAN', minutes=5)
-
-        :type per_series_aligner: string
-        :param per_series_aligner: The approach to be used to align
-            individual time series. For example: ``"ALIGN_MEAN"``.
-            See the `supported aligners`_.
-
-        :type seconds: integer
-        :param seconds: The number of seconds in the alignment period.
-
-        :type minutes: integer
-        :param minutes: The number of minutes in the alignment period.
-
-        :type hours: integer
-        :param hours: The number of hours in the alignment period.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-
-        .. _supported aligners:
-            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
-            projects.timeSeries/list#Aligner
-        """
-        new_query = self.copy()
-        new_query._per_series_aligner = per_series_aligner
-        new_query._alignment_period_seconds = seconds + 60 * (minutes +
-                                                              60 * hours)
-        return new_query
-
-    def reduce(self, cross_series_reducer, *group_by_fields):
-        """Copy the query and add cross-series reduction.
-
-        :type cross_series_reducer: string
-        :param cross_series_reducer:
-            The approach to be used to combine time series. For example:
-            ``"REDUCE_MEAN"``. See the `supported reducers`_.
-
-        :type group_by_fields: strings
-        :param group_by_fields:
-            Fields to be preserved by the reduction. For example, specifying
-            just ``"resource.zone"`` will result in one time series per zone.
-            The default is to aggregate all of the time series into just one.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-
-        .. _supported reducers:
-            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
-            projects.timeSeries/list#Reducer
-        """
-        new_query = self.copy()
-        new_query._cross_series_reducer = cross_series_reducer
-        new_query._group_by_fields = group_by_fields
-        return new_query
-
-    def iter(self, headers_only=False, _page_size=None):
-        """Yield all time series objects selected by the query.
-
-        Note that the :class:`Query` object itself is an iterable, such that
-        the following are equivalent::
-
-            for timeseries in query: ...
-            for timeseries in query.iter(): ...
-
-        :type headers_only: boolean
-        :param headers_only:
-             Whether to omit the point data from the time series objects.
-
-        :type _page_size: integer or None
-        :param _page_size:
-            An optional positive number specifying the maximum number of
-            points to return per page. This can be used to control how far
-            the iterator reads ahead.
-
-        :rtype: iterator over :class:`TimeSeries`
-        :returns: Time series objects, containing points ordered from oldest
-            to newest.
-        :raises: :exc:`ValueError` if the query time interval has not been
-            specified.
-        """
-        if self._end_time is None:
-            raise ValueError('Query time interval not specified.')
-
-        path = '/projects/{project}/timeSeries/'.format(
-            project=self._client.project)
-
-        def _fragments():
-            page_token = None
-            while True:
-                params = self._build_query_params(
-                    headers_only=headers_only,
-                    page_size=_page_size,
-                    page_token=page_token,
-                )
-                response = self._client.connection.api_request(
-                    method='GET',
-                    path=path,
-                    query_params=params,
-                )
-                for info in response.get('timeSeries', []):
-                    yield TimeSeries._from_dict(info)
-
-                page_token = response.get('nextPageToken')
-                if not page_token:
-                    break
-
-        # The following use of groupby() relies on equality comparison
-        # of time series as (named) tuples.
-        for timeseries, fragments in itertools.groupby(
-                _fragments(),
-                lambda fragment: fragment.header()):
-            points = list(itertools.chain.from_iterable(
-                fragment.points for fragment in fragments))
-            points.reverse()  # Order from oldest to newest.
-            yield timeseries.header(points=points)
-
-    def _build_query_params(self, headers_only=False,
-                            page_size=None, page_token=None):
-        """Assemble the list of key-value pairs for the URL query string.
-
-        We use a list of key-value pairs instead of a ``dict`` to allow for
-        repeated fields.
-
-        :type headers_only: boolean
-        :param headers_only:
-             Whether to omit the point data from the ``TimeSeries`` objects.
-
-        :type page_size: integer or None
-        :param page_size: A limit on the number of points to return per page.
-
-        :type page_token: string or None
-        :param page_token: A token to continue the retrieval.
-
-        :rtype: list of tuples
-        :returns:
-            A list of key-value pairs suitable for passing to ``urlencode``.
-        """
-        def _pairs():
-            yield 'filter', self.filter
-
-            yield 'interval.endTime', _format_timestamp(self._end_time)
-            if self._start_time is not None:
-                yield 'interval.startTime', _format_timestamp(self._start_time)
-
-            if self._per_series_aligner is not None:
-                yield 'aggregation.perSeriesAligner', self._per_series_aligner
-
-            if self._alignment_period_seconds is not None:
-                alignment_period = '{period}s'.format(
-                    period=self._alignment_period_seconds)
-                yield 'aggregation.alignmentPeriod', alignment_period
-
-            if self._cross_series_reducer is not None:
-                yield ('aggregation.crossSeriesReducer',
-                       self._cross_series_reducer)
-
-            for field in self._group_by_fields:
-                yield 'aggregation.groupByFields', field
-
-            if headers_only:
-                yield 'view', 'HEADERS'
-
-            if page_size is not None:
-                yield 'pageSize', page_size
-
-            if page_token is not None:
-                yield 'pageToken', page_token
-
-        return list(_pairs())
-
-    def as_dataframe(self, label=None, labels=None):
-        """Return all the selected time series as a ``pandas`` dataframe.
-
-        .. note::
-
-            Use of this method requires that you have ``pandas`` installed.
-
-        Examples::
-
-            # Generate a dataframe with a multi-level column header including
-            # the resource type and all available resource and metric labels.
-            # This can be useful for seeing what labels are available.
-            dataframe = query.as_dataframe()
-
-            # Generate a dataframe using a particular label for the column
-            # names.
-            dataframe = query.as_dataframe(label='instance_name')
-
-            # Generate a dataframe with a multi-level column header.
-            dataframe = query.as_dataframe(labels=['zone', 'instance_name'])
-
-            # Generate a dataframe with a multi-level column header, assuming
-            # the metric is issued by more than one type of resource.
-            dataframe = query.as_dataframe(
-                labels=['resource_type', 'instance_id'])
-
-        :type label: string or None
-        :param label: The label name to use for the dataframe header.
-            This can be the name of a resource label or metric label
-            (e.g., ``"instance_name"``), or the string ``"resource_type"``.
-
-        :type labels: list of strings, or None
-        :param labels: A list or tuple of label names to use for the dataframe
-            header. If more than one label name is provided, the resulting
-            dataframe will have a multi-level column header. Providing values
-            for both ``label`` and ``labels`` is an error.
-
-        :rtype: :class:`pandas.DataFrame`
-        :returns: A dataframe where each column represents one time series.
-        """
-        import pandas   # pylint: disable=import-error
-
-        if label is not None and labels is not None:
-            raise ValueError('Cannot specify both "label" and "labels".')
-        elif not (labels or labels is None):
-            raise ValueError('"labels" must be non-empty or None.')
-
-        columns = []
-        headers = []
-        for time_series in self:
-            pandas_series = pandas.Series(
-                data=[p.value for p in time_series.points],
-                index=[p.end_time for p in time_series.points],
-            )
-            columns.append(pandas_series)
-            headers.append(time_series.header())
-
-        # Implement a smart default of using all available labels.
-        if label is None and labels is None:
-            resource_labels = set(itertools.chain.from_iterable(
-                header.resource.labels for header in headers))
-            metric_labels = set(itertools.chain.from_iterable(
-                header.metric.labels for header in headers))
-            labels = (['resource_type'] +
-                      _sorted_resource_labels(resource_labels) +
-                      sorted(metric_labels))
-
-        # Assemble the columns into a DataFrame.
-        dataframe = pandas.DataFrame(columns).T
-
-        # Convert the timestamp strings into a DatetimeIndex.
-        dataframe.index = pandas.to_datetime(dataframe.index)
-
-        # Build a column Index or MultiIndex from the label values. Do not
-        # include level names in the column header if the user requested a
-        # single-level header by specifying "label".
-        level_names = labels or None
-        label_keys = labels or [label]
-        dataframe.columns = pandas.MultiIndex.from_arrays(
-            [[header.labels.get(key, '') for header in headers]
-             for key in label_keys],
-            names=level_names)
-
-        # Sort the rows just in case (since the API doesn't guarantee the
-        # ordering), and sort the columns lexicographically.
-        return dataframe.sort_index(axis=0).sort_index(axis=1)
-
-    def copy(self):
-        """Copy the query object.
-
-        :rtype: :class:`Query`
-        :returns: The new query object.
-        """
-        # Using copy.deepcopy() would be appropriate, except that we want
-        # to copy self._client only as a reference.
-        new_query = copy.copy(self)
-        new_query._filter = copy.copy(self._filter)
-        return new_query
-
 
 class TimeSeries(collections.namedtuple(
         'TimeSeries', 'metric resource metric_kind value_type points')):
     """A single time series of metric values.
 
+    This is a named tuple. See :func:`collections.namedtuple`.
+
     :type metric: :class:`~gcloud.monitoring.metric.Metric`
     :param metric: A metric object.
 
@@ -685,6 +121,8 @@ def __repr__(self):
 class Point(collections.namedtuple('Point', 'end_time start_time value')):
     """A single point in a time series.
 
+    This is a named tuple. See :func:`collections.namedtuple`.
+
     :type end_time: string
     :param end_time: The end time in RFC3339 UTC "Zulu" format.
 
@@ -713,101 +151,3 @@ def _from_dict(cls, info):
             value = int(value)  # Convert from string.
 
         return cls(end_time, start_time, value)
-
-
-class _Filter(object):
-    """Helper for assembling a filter string."""
-
-    def __init__(self, metric_type):
-        self.metric_type = metric_type
-        self.group_id = None
-        self.projects = ()
-        self.resource_label_filter = None
-        self.metric_label_filter = None
-
-    def select_resources(self, *args, **kwargs):
-        """Select by resource labels.
-
-        See :meth:`Query.select_resources`.
-        """
-        self.resource_label_filter = _build_label_filter('resource',
-                                                         *args, **kwargs)
-
-    def select_metrics(self, *args, **kwargs):
-        """Select by metric labels.
-
-        See :meth:`Query.select_metrics`.
-        """
-        self.metric_label_filter = _build_label_filter('metric',
-                                                       *args, **kwargs)
-
-    def __str__(self):
-        filters = ['metric.type = "{type}"'.format(type=self.metric_type)]
-        if self.group_id is not None:
-            filters.append('group.id = "{id}"'.format(id=self.group_id))
-        if self.projects:
-            filters.append(
-                ' OR '.join('project = "{project}"'.format(project=project)
-                            for project in self.projects))
-        if self.resource_label_filter:
-            filters.append(self.resource_label_filter)
-        if self.metric_label_filter:
-            filters.append(self.metric_label_filter)
-
-        # Parentheses are never actually required, because OR binds more
-        # tightly than AND in the Monitoring API's filter syntax.
-        return ' AND '.join(filters)
-
-
-def _build_label_filter(category, *args, **kwargs):
-    """Construct a filter string to filter on metric or resource labels."""
-    terms = list(args)
-    for key in kwargs:
-        value = kwargs[key]
-        if value is None:
-            continue
-
-        suffix = None
-        if key.endswith('_prefix') or key.endswith('_suffix'):
-            key, suffix = key.rsplit('_', 1)
-
-        if category == 'resource' and key == 'resource_type':
-            key = 'resource.type'
-        else:
-            key = '.'.join((category, 'label', key))
-
-        if suffix == 'prefix':
-            term = '{key} = starts_with("{value}")'
-        elif suffix == 'suffix':
-            term = '{key} = ends_with("{value}")'
-        else:
-            term = '{key} = "{value}"'
-
-        terms.append(term.format(key=key, value=value))
-
-    return ' AND '.join(sorted(terms))
-
-
-def _sorted_resource_labels(labels):
-    """Sort label names, putting well-known resource labels first."""
-    head = [label for label in TOP_RESOURCE_LABELS if label in labels]
-    tail = sorted(label for label in labels
-                  if label not in TOP_RESOURCE_LABELS)
-    return head + tail
-
-
-def _format_timestamp(timestamp):
-    """Convert a datetime object to a string as required by the API.
-
-    :type timestamp: :class:`datetime.datetime`
-    :param timestamp: A datetime object.
-
-    :rtype: string
-    :returns: The formatted timestamp. For example:
-        ``"2016-02-17T19:18:01.763000Z"``
-    """
-    if timestamp.tzinfo is not None:
-        # Convert to UTC and remove the time zone info.
-        timestamp = timestamp.replace(tzinfo=None) - timestamp.utcoffset()
-
-    return timestamp.isoformat() + 'Z'

From 1e7278437016beaa2b7562cd582c5aa923ed9933 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 7 Apr 2016 23:32:57 -0400
Subject: [PATCH 15/61] Isolated the pandas-dependent code in _dataframe.py.

---
 gcloud/monitoring/_dataframe.py      | 113 +++++++++++++++++++++++++++
 gcloud/monitoring/query.py           |  68 ++--------------
 gcloud/monitoring/test__dataframe.py |  36 +++++++++
 gcloud/monitoring/test_query.py      |  21 -----
 4 files changed, 154 insertions(+), 84 deletions(-)
 create mode 100644 gcloud/monitoring/_dataframe.py
 create mode 100644 gcloud/monitoring/test__dataframe.py

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
new file mode 100644
index 000000000000..8c67653bc084
--- /dev/null
+++ b/gcloud/monitoring/_dataframe.py
@@ -0,0 +1,113 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Time series as `pandas`_ dataframes.
+
+.. _pandas: http://pandas.pydata.org/pandas-docs/stable/
+"""
+
+import itertools
+
+TOP_RESOURCE_LABELS = [
+    'project_id',
+    'aws_account',
+    'location',
+    'region',
+    'zone',
+]
+
+
+def _build_dataframe(time_series_iterable, label=None, labels=None):
+    """Build a ``pandas`` dataframe out of time series.
+
+    :type time_series_iterable:
+        iterable over :class:`~gcloud.monitoring.timeseries.TimeSeries`
+    :param time_series_iterable:
+        An iterable (e.g., a query object) yielding time series.
+
+    :type label: string or None
+    :param label:
+        The label name to use for the dataframe header. This can be the name
+        of a resource label or metric label (e.g., ``"instance_name"``), or
+        the string ``"resource_type"``.
+
+    :type labels: list of strings, or None
+    :param labels:
+        A list or tuple of label names to use for the dataframe header.
+        If more than one label name is provided, the resulting dataframe
+        will have a multi-level column header.
+
+        Specifying neither ``label`` or ``labels`` results in a dataframe
+        with a multi-level column header including the resource type and
+        all available resource and metric labels.
+
+        Specifying both ``label`` and ``labels`` is an error.
+
+    :rtype: :class:`pandas.DataFrame`
+    :returns: A dataframe where each column represents one time series.
+    """
+    import pandas   # pylint: disable=import-error
+
+    if label is not None and labels is not None:
+        raise ValueError('Cannot specify both "label" and "labels".')
+    elif not (labels or labels is None):
+        raise ValueError('"labels" must be non-empty or None.')
+
+    columns = []
+    headers = []
+    for time_series in time_series_iterable:
+        pandas_series = pandas.Series(
+            data=[p.value for p in time_series.points],
+            index=[p.end_time for p in time_series.points],
+        )
+        columns.append(pandas_series)
+        headers.append(time_series.header())
+
+    # Implement a smart default of using all available labels.
+    if label is None and labels is None:
+        resource_labels = set(itertools.chain.from_iterable(
+            header.resource.labels for header in headers))
+        metric_labels = set(itertools.chain.from_iterable(
+            header.metric.labels for header in headers))
+        labels = (['resource_type'] +
+                  _sorted_resource_labels(resource_labels) +
+                  sorted(metric_labels))
+
+    # Assemble the columns into a DataFrame.
+    dataframe = pandas.DataFrame(columns).T
+
+    # Convert the timestamp strings into a DatetimeIndex.
+    dataframe.index = pandas.to_datetime(dataframe.index)
+
+    # Build a column Index or MultiIndex from the label values. Do not
+    # include level names in the column header if the user requested a
+    # single-level header by specifying "label".
+    level_names = labels or None
+    label_keys = labels or [label]
+    dataframe.columns = pandas.MultiIndex.from_arrays(
+        [[header.labels.get(key, '') for header in headers]
+         for key in label_keys],
+        names=level_names)
+
+    # Sort the rows just in case (since the API doesn't guarantee the
+    # ordering), and sort the columns lexicographically.
+    return dataframe.sort_index(axis=0).sort_index(axis=1)
+
+
+def _sorted_resource_labels(labels):
+    """Sort label names, putting well-known resource labels first."""
+    head = [label for label in TOP_RESOURCE_LABELS if label in labels]
+    tail = sorted(label for label in labels
+                  if label not in TOP_RESOURCE_LABELS)
+    return head + tail
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index aa9d5f9e69cb..6fb2bb02ecae 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -23,16 +23,9 @@
 import datetime
 import itertools
 
+from gcloud.monitoring._dataframe import _build_dataframe
 from gcloud.monitoring.timeseries import TimeSeries
 
-TOP_RESOURCE_LABELS = [
-    'project_id',
-    'aws_account',
-    'location',
-    'region',
-    'zone',
-]
-
 _NOW = datetime.datetime.utcnow  # To be replaced by tests.
 
 
@@ -491,7 +484,7 @@ def _pairs():
         return list(_pairs())
 
     def as_dataframe(self, label=None, labels=None):
-        """Return all the selected time series as a ``pandas`` dataframe.
+        """Return all the selected time series as a `pandas`_ dataframe.
 
         .. note::
 
@@ -529,53 +522,10 @@ def as_dataframe(self, label=None, labels=None):
 
         :rtype: :class:`pandas.DataFrame`
         :returns: A dataframe where each column represents one time series.
+
+        .. _pandas: http://pandas.pydata.org/pandas-docs/stable/
         """
-        import pandas   # pylint: disable=import-error
-
-        if label is not None and labels is not None:
-            raise ValueError('Cannot specify both "label" and "labels".')
-        elif not (labels or labels is None):
-            raise ValueError('"labels" must be non-empty or None.')
-
-        columns = []
-        headers = []
-        for time_series in self:
-            pandas_series = pandas.Series(
-                data=[p.value for p in time_series.points],
-                index=[p.end_time for p in time_series.points],
-            )
-            columns.append(pandas_series)
-            headers.append(time_series.header())
-
-        # Implement a smart default of using all available labels.
-        if label is None and labels is None:
-            resource_labels = set(itertools.chain.from_iterable(
-                header.resource.labels for header in headers))
-            metric_labels = set(itertools.chain.from_iterable(
-                header.metric.labels for header in headers))
-            labels = (['resource_type'] +
-                      _sorted_resource_labels(resource_labels) +
-                      sorted(metric_labels))
-
-        # Assemble the columns into a DataFrame.
-        dataframe = pandas.DataFrame(columns).T
-
-        # Convert the timestamp strings into a DatetimeIndex.
-        dataframe.index = pandas.to_datetime(dataframe.index)
-
-        # Build a column Index or MultiIndex from the label values. Do not
-        # include level names in the column header if the user requested a
-        # single-level header by specifying "label".
-        level_names = labels or None
-        label_keys = labels or [label]
-        dataframe.columns = pandas.MultiIndex.from_arrays(
-            [[header.labels.get(key, '') for header in headers]
-             for key in label_keys],
-            names=level_names)
-
-        # Sort the rows just in case (since the API doesn't guarantee the
-        # ordering), and sort the columns lexicographically.
-        return dataframe.sort_index(axis=0).sort_index(axis=1)
+        return _build_dataframe(self, label, labels)  # pragma: NO COVER
 
     def copy(self):
         """Copy the query object.
@@ -663,14 +613,6 @@ def _build_label_filter(category, *args, **kwargs):
     return ' AND '.join(sorted(terms))
 
 
-def _sorted_resource_labels(labels):
-    """Sort label names, putting well-known resource labels first."""
-    head = [label for label in TOP_RESOURCE_LABELS if label in labels]
-    tail = sorted(label for label in labels
-                  if label not in TOP_RESOURCE_LABELS)
-    return head + tail
-
-
 def _format_timestamp(timestamp):
     """Convert a datetime object to a string as required by the API.
 
diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
new file mode 100644
index 000000000000..2d5b42a6d8c2
--- /dev/null
+++ b/gcloud/monitoring/test__dataframe.py
@@ -0,0 +1,36 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+
+class Test__sorted_resource_labels(unittest2.TestCase):
+
+    def _callFUT(self, labels):
+        from gcloud.monitoring._dataframe import _sorted_resource_labels
+        return _sorted_resource_labels(labels)
+
+    def test_empty(self):
+        self.assertEqual(self._callFUT([]), [])
+
+    def test_sorted(self):
+        from gcloud.monitoring._dataframe import TOP_RESOURCE_LABELS
+        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        self.assertEqual(self._callFUT(EXPECTED), EXPECTED)
+
+    def test_reversed(self):
+        from gcloud.monitoring._dataframe import TOP_RESOURCE_LABELS
+        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        INPUT = list(reversed(EXPECTED))
+        self.assertEqual(self._callFUT(INPUT), EXPECTED)
diff --git a/gcloud/monitoring/test_query.py b/gcloud/monitoring/test_query.py
index eaf84094f710..7a570827d4f3 100644
--- a/gcloud/monitoring/test_query.py
+++ b/gcloud/monitoring/test_query.py
@@ -591,27 +591,6 @@ def test_resource_type_suffix(self):
         self.assertEqual(actual, expected)
 
 
-class Test__sorted_resource_labels(unittest2.TestCase):
-
-    def _callFUT(self, labels):
-        from gcloud.monitoring.query import _sorted_resource_labels
-        return _sorted_resource_labels(labels)
-
-    def test_empty(self):
-        self.assertEqual(self._callFUT([]), [])
-
-    def test_sorted(self):
-        from gcloud.monitoring.query import TOP_RESOURCE_LABELS
-        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
-        self.assertEqual(self._callFUT(EXPECTED), EXPECTED)
-
-    def test_reversed(self):
-        from gcloud.monitoring.query import TOP_RESOURCE_LABELS
-        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
-        INPUT = list(reversed(EXPECTED))
-        self.assertEqual(self._callFUT(INPUT), EXPECTED)
-
-
 class Test__format_timestamp(unittest2.TestCase):
 
     def _callFUT(self, timestamp):

From 0937a1a520a1438415b0f119c24a9c2cf7cae5dc Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 8 Apr 2016 14:25:38 -0400
Subject: [PATCH 16/61] Add unit tests for _build_dataframe().

---
 gcloud/monitoring/test__dataframe.py | 187 +++++++++++++++++++++++++++
 1 file changed, 187 insertions(+)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 2d5b42a6d8c2..919d636f69e9 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -15,6 +15,193 @@
 import unittest2
 
 
+PROJECT = 'my-project'
+
+INSTANCE_NAMES = ['instance-1', 'instance-2']
+INSTANCE_ZONES = ['us-east1-a', 'us-east1-b']
+INSTANCE_IDS = ['1234567890123456789', '9876543210987654321']
+
+M = len(INSTANCE_NAMES)
+
+METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
+METRIC_LABELS = [{'instance_name': INSTANCE_NAMES[i]}
+                 for i in range(M)]
+
+RESOURCE_TYPE = 'gce_instance'
+RESOURCE_LABELS = [{'project_id': PROJECT,
+                    'zone': INSTANCE_ZONES[i],
+                    'instance_id': INSTANCE_IDS[i]}
+                   for i in range(M)]
+
+METRIC_KIND = 'GAUGE'
+VALUE_TYPE = 'DOUBLE'
+VALUES = [0.1 * i for i in range(M)]
+
+TIMESTAMPS = [
+    '2016-04-06T22:05:00.042Z',
+    '2016-04-06T22:05:01.042Z',
+    '2016-04-06T22:05:02.042Z',
+]
+N = len(TIMESTAMPS)
+
+
+def parse_timestamps():
+    import datetime
+    return [datetime.datetime.strptime(t, '%Y-%m-%dT%H:%M:%S.%fZ')
+            for t in TIMESTAMPS]
+
+
+def generate_query_results():
+    from gcloud.monitoring.metric import Metric
+    from gcloud.monitoring.resource import Resource
+    from gcloud.monitoring.timeseries import Point, TimeSeries
+
+    def P(timestamp, value):
+        return Point(
+            start_time=timestamp,
+            end_time=timestamp,
+            value=value,
+        )
+
+    for i in range(M):
+        yield TimeSeries(
+            metric=Metric(type=METRIC_TYPE, labels=METRIC_LABELS[i]),
+            resource=Resource(type=RESOURCE_TYPE, labels=RESOURCE_LABELS[i]),
+            metric_kind=METRIC_KIND,
+            value_type=VALUE_TYPE,
+            points=[P(t, VALUES[i]) for t in TIMESTAMPS],
+        )
+
+
+class Test__build_dataframe(unittest2.TestCase):
+
+    def _callFUT(self, *args, **kwargs):
+        from gcloud.monitoring._dataframe import _build_dataframe
+        return _build_dataframe(*args, **kwargs)
+
+    def test_both_label_and_labels_illegal(self):
+        with self.assertRaises(ValueError):
+            self._callFUT([], label='instance_name', labels=['zone'])
+
+    def test_empty_labels_illegal(self):
+        with self.assertRaises(ValueError):
+            self._callFUT([], labels=[])
+
+    def test_simple_label(self):
+        iterable = generate_query_results()
+        dataframe = self._callFUT(iterable, label='instance_name')
+
+        self.assertEqual(dataframe.shape, (N, M))
+        self.assertEqual(dataframe.as_matrix().tolist(),
+                         [VALUES for i in range(N)])
+
+        self.assertEqual(list(dataframe.columns), INSTANCE_NAMES)
+        self.assertIsNone(dataframe.columns.name)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_multiple_labels(self):
+        NAMES = ['resource_type', 'instance_id']
+
+        iterable = generate_query_results()
+        dataframe = self._callFUT(iterable, labels=NAMES)
+
+        self.assertEqual(dataframe.shape, (N, M))
+        self.assertEqual(dataframe.as_matrix().tolist(),
+                         [VALUES for i in range(N)])
+
+        expected_headers = [(RESOURCE_TYPE, instance_id)
+                            for instance_id in INSTANCE_IDS]
+        self.assertEqual(list(dataframe.columns), expected_headers)
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertIsNone(dataframe.columns.name)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_multiple_labels_with_just_one(self):
+        NAME = 'instance_id'
+        NAMES = [NAME]
+
+        iterable = generate_query_results()
+        dataframe = self._callFUT(iterable, labels=NAMES)
+
+        self.assertEqual(dataframe.shape, (N, M))
+        self.assertEqual(dataframe.as_matrix().tolist(),
+                         [VALUES for i in range(N)])
+
+        self.assertEqual(list(dataframe.columns), INSTANCE_IDS)
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertEqual(dataframe.columns.name, NAME)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_smart_labels(self):
+        NAMES = ['resource_type', 'project_id',
+                 'zone', 'instance_id',
+                 'instance_name']
+
+        iterable = generate_query_results()
+        dataframe = self._callFUT(iterable)
+
+        self.assertEqual(dataframe.shape, (N, M))
+        self.assertEqual(dataframe.as_matrix().tolist(),
+                         [VALUES for i in range(N)])
+
+        expected_headers = [
+            (RESOURCE_TYPE, PROJECT, zone, instance_id, instance_name)
+            for zone, instance_id, instance_name
+            in zip(INSTANCE_ZONES, INSTANCE_IDS, INSTANCE_NAMES)]
+        self.assertEqual(list(dataframe.columns), expected_headers)
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertIsNone(dataframe.columns.name)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_empty_table_simple_label(self):
+        import pandas
+        dataframe = self._callFUT([], label='instance_name')
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertIsNone(dataframe.columns.name)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+    def test_empty_table_multiple_labels(self):
+        import pandas
+        NAMES = ['resource_type', 'instance_id']
+        dataframe = self._callFUT([], labels=NAMES)
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertIsNone(dataframe.columns.name)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+    def test_empty_table_multiple_labels_with_just_one(self):
+        import pandas
+        NAME = 'instance_id'
+        NAMES = [NAME]
+        dataframe = self._callFUT([], labels=NAMES)
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertEqual(dataframe.columns.name, NAME)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+    def test_empty_table_smart_labels(self):
+        import pandas
+        NAME = 'resource_type'
+        NAMES = [NAME]
+        dataframe = self._callFUT([])
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertEqual(dataframe.columns.name, NAME)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+
 class Test__sorted_resource_labels(unittest2.TestCase):
 
     def _callFUT(self, labels):

From f5cc18646afae67369f458f7db43253ea61d5a0d Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Sun, 10 Apr 2016 09:08:50 -0400
Subject: [PATCH 17/61] Make the pseudo-enums importable from
 gcloud.monitoring.

---
 gcloud/monitoring/__init__.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gcloud/monitoring/__init__.py b/gcloud/monitoring/__init__.py
index c626b955a4c2..7cd11f8c2669 100644
--- a/gcloud/monitoring/__init__.py
+++ b/gcloud/monitoring/__init__.py
@@ -17,8 +17,13 @@
 from gcloud.monitoring.client import Client
 from gcloud.monitoring.connection import Connection
 from gcloud.monitoring.label import LabelDescriptor
+from gcloud.monitoring.label import LabelValueType
 from gcloud.monitoring.metric import Metric
 from gcloud.monitoring.metric import MetricDescriptor
+from gcloud.monitoring.metric import MetricKind
+from gcloud.monitoring.metric import ValueType
+from gcloud.monitoring.query import Aligner
+from gcloud.monitoring.query import Reducer
 from gcloud.monitoring.query import Query
 from gcloud.monitoring.resource import Resource
 from gcloud.monitoring.resource import ResourceDescriptor

From 19745e7c5ef43def89bbe967aa8c24e68b9012d2 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Mon, 11 Apr 2016 14:39:34 -0400
Subject: [PATCH 18/61] Skip tests of _build_dataframe() if pandas is not
 available.

---
 gcloud/monitoring/test__dataframe.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 919d636f69e9..7721d4f74ed4 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -12,6 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+try:
+    import pandas
+except ImportError:
+    HAVE_PANDAS = False
+else:
+    HAVE_PANDAS = True
+
 import unittest2
 
 
@@ -73,6 +80,7 @@ def P(timestamp, value):
         )
 
 
+@unittest2.skipUnless(HAVE_PANDAS, 'No pandas')
 class Test__build_dataframe(unittest2.TestCase):
 
     def _callFUT(self, *args, **kwargs):
@@ -162,7 +170,6 @@ def test_smart_labels(self):
         self.assertIsNone(dataframe.index.name)
 
     def test_empty_table_simple_label(self):
-        import pandas
         dataframe = self._callFUT([], label='instance_name')
         self.assertEqual(dataframe.shape, (0, 0))
         self.assertIsNone(dataframe.columns.name)
@@ -170,7 +177,6 @@ def test_empty_table_simple_label(self):
         self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
 
     def test_empty_table_multiple_labels(self):
-        import pandas
         NAMES = ['resource_type', 'instance_id']
         dataframe = self._callFUT([], labels=NAMES)
         self.assertEqual(dataframe.shape, (0, 0))
@@ -180,7 +186,6 @@ def test_empty_table_multiple_labels(self):
         self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
 
     def test_empty_table_multiple_labels_with_just_one(self):
-        import pandas
         NAME = 'instance_id'
         NAMES = [NAME]
         dataframe = self._callFUT([], labels=NAMES)
@@ -191,7 +196,6 @@ def test_empty_table_multiple_labels_with_just_one(self):
         self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
 
     def test_empty_table_smart_labels(self):
-        import pandas
         NAME = 'resource_type'
         NAMES = [NAME]
         dataframe = self._callFUT([])

From 6ce7994bc1fbf66806ddff8ccfea437934b85b53 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Mon, 11 Apr 2016 16:56:39 -0400
Subject: [PATCH 19/61] Fix lint errors.

---
 gcloud/monitoring/test__dataframe.py | 26 +++++++++++---------------
 1 file changed, 11 insertions(+), 15 deletions(-)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 7721d4f74ed4..7c120c54b240 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -31,18 +31,18 @@
 M = len(INSTANCE_NAMES)
 
 METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
-METRIC_LABELS = [{'instance_name': INSTANCE_NAMES[i]}
-                 for i in range(M)]
+METRIC_LABELS = list({'instance_name': INSTANCE_NAMES[i]}
+                     for i in range(M))
 
 RESOURCE_TYPE = 'gce_instance'
-RESOURCE_LABELS = [{'project_id': PROJECT,
-                    'zone': INSTANCE_ZONES[i],
-                    'instance_id': INSTANCE_IDS[i]}
-                   for i in range(M)]
+RESOURCE_LABELS = list({'project_id': PROJECT,
+                        'zone': INSTANCE_ZONES[i],
+                        'instance_id': INSTANCE_IDS[i]}
+                       for i in range(M))
 
 METRIC_KIND = 'GAUGE'
 VALUE_TYPE = 'DOUBLE'
-VALUES = [0.1 * i for i in range(M)]
+VALUES = list(0.1 * i for i in range(M))
 
 TIMESTAMPS = [
     '2016-04-06T22:05:00.042Z',
@@ -100,8 +100,7 @@ def test_simple_label(self):
         dataframe = self._callFUT(iterable, label='instance_name')
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(),
-                         [VALUES for i in range(N)])
+        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
 
         self.assertEqual(list(dataframe.columns), INSTANCE_NAMES)
         self.assertIsNone(dataframe.columns.name)
@@ -116,8 +115,7 @@ def test_multiple_labels(self):
         dataframe = self._callFUT(iterable, labels=NAMES)
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(),
-                         [VALUES for i in range(N)])
+        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
 
         expected_headers = [(RESOURCE_TYPE, instance_id)
                             for instance_id in INSTANCE_IDS]
@@ -136,8 +134,7 @@ def test_multiple_labels_with_just_one(self):
         dataframe = self._callFUT(iterable, labels=NAMES)
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(),
-                         [VALUES for i in range(N)])
+        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
 
         self.assertEqual(list(dataframe.columns), INSTANCE_IDS)
         self.assertEqual(dataframe.columns.names, NAMES)
@@ -155,8 +152,7 @@ def test_smart_labels(self):
         dataframe = self._callFUT(iterable)
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(),
-                         [VALUES for i in range(N)])
+        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
 
         expected_headers = [
             (RESOURCE_TYPE, PROJECT, zone, instance_id, instance_name)

From 4f047a55886f5ebb4ab734b930a6246a544c1d1b Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Mon, 11 Apr 2016 17:52:15 -0400
Subject: [PATCH 20/61] Add "NO COVER" pragmas due to not having pandas in the
 testenv:cover environment.

---
 gcloud/monitoring/_dataframe.py      | 3 ++-
 gcloud/monitoring/test__dataframe.py | 8 ++++----
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index 8c67653bc084..0777a6379205 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -28,7 +28,8 @@
 ]
 
 
-def _build_dataframe(time_series_iterable, label=None, labels=None):
+def _build_dataframe(time_series_iterable,
+                     label=None, labels=None):  # pragma: NO COVER
     """Build a ``pandas`` dataframe out of time series.
 
     :type time_series_iterable:
diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 7c120c54b240..833f86f67490 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -17,7 +17,7 @@
 except ImportError:
     HAVE_PANDAS = False
 else:
-    HAVE_PANDAS = True
+    HAVE_PANDAS = True  # pragma: NO COVER
 
 import unittest2
 
@@ -52,13 +52,13 @@
 N = len(TIMESTAMPS)
 
 
-def parse_timestamps():
+def parse_timestamps():  # pragma: NO COVER
     import datetime
     return [datetime.datetime.strptime(t, '%Y-%m-%dT%H:%M:%S.%fZ')
             for t in TIMESTAMPS]
 
 
-def generate_query_results():
+def generate_query_results():  # pragma: NO COVER
     from gcloud.monitoring.metric import Metric
     from gcloud.monitoring.resource import Resource
     from gcloud.monitoring.timeseries import Point, TimeSeries
@@ -81,7 +81,7 @@ def P(timestamp, value):
 
 
 @unittest2.skipUnless(HAVE_PANDAS, 'No pandas')
-class Test__build_dataframe(unittest2.TestCase):
+class Test__build_dataframe(unittest2.TestCase):  # pragma: NO COVER
 
     def _callFUT(self, *args, **kwargs):
         from gcloud.monitoring._dataframe import _build_dataframe

From 27a508cb2003553098ecf65727d01f23582db701 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Mon, 11 Apr 2016 18:26:49 -0400
Subject: [PATCH 21/61] Add a py27-pandas tox test environment.

---
 tox.ini | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index 2367a3806f46..17c13d4d0eb4 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,6 +1,6 @@
 [tox]
 envlist =
-    py26,py27,py34,py35,cover,docs,lint
+    py26,py27,py34,py35,py27-pandas,cover,docs,lint
 
 [testenv]
 commands =
@@ -30,6 +30,17 @@ commands =
 setenv =
     PYTHONPATH =
 
+[testenv:py27-pandas]
+basepython =
+    python2.7
+commands =
+    {[testenv:py27]commands}
+setenv =
+    {[testenv:py27]setenv}
+deps =
+    {[testenv]deps}
+    pandas
+
 [testenv:cover]
 basepython =
     python2.7

From 7c0acce668f0ab3107e1d890bec0d1aaff513630 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 12 Apr 2016 11:43:23 -0400
Subject: [PATCH 22/61] as_matrix() -> values

---
 gcloud/monitoring/test__dataframe.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 833f86f67490..329ca14cc06a 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -100,7 +100,7 @@ def test_simple_label(self):
         dataframe = self._callFUT(iterable, label='instance_name')
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
 
         self.assertEqual(list(dataframe.columns), INSTANCE_NAMES)
         self.assertIsNone(dataframe.columns.name)
@@ -115,7 +115,7 @@ def test_multiple_labels(self):
         dataframe = self._callFUT(iterable, labels=NAMES)
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
 
         expected_headers = [(RESOURCE_TYPE, instance_id)
                             for instance_id in INSTANCE_IDS]
@@ -134,7 +134,7 @@ def test_multiple_labels_with_just_one(self):
         dataframe = self._callFUT(iterable, labels=NAMES)
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
 
         self.assertEqual(list(dataframe.columns), INSTANCE_IDS)
         self.assertEqual(dataframe.columns.names, NAMES)
@@ -152,7 +152,7 @@ def test_smart_labels(self):
         dataframe = self._callFUT(iterable)
 
         self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.as_matrix().tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
 
         expected_headers = [
             (RESOURCE_TYPE, PROJECT, zone, instance_id, instance_name)

From bc1ff058057c56838b25d966281d6c43d7a4dbcf Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 15 Apr 2016 12:15:32 -0400
Subject: [PATCH 23/61] Utilize the pseudo-enums in the docstrings and add a
 few more usage examples.

---
 gcloud/monitoring/label.py  |  5 +++--
 gcloud/monitoring/metric.py | 12 ++++++-----
 gcloud/monitoring/query.py  | 41 ++++++++++++++++++++++++++++++++-----
 3 files changed, 46 insertions(+), 12 deletions(-)

diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
index ec4480e8b1be..98861d7dea5f 100644
--- a/gcloud/monitoring/label.py
+++ b/gcloud/monitoring/label.py
@@ -40,8 +40,9 @@ class LabelDescriptor(object):
 
     :type value_type: string
     :param value_type:
-        The type of the label. It must be one of ``"STRING"``, ``"BOOL"``,
-        or ``"INT64"``.
+        The type of the label. It must be one of ``LabelValueType.STRING``,
+        ``LabelValueType.BOOL``, or ``LabelValueType.INT64``.
+        See :class:`LabelValueType`.
 
     :type description: string
     :param description: A human-readable description for the label.
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index cd22aa1b4d12..06010c13de5a 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -76,14 +76,16 @@ class MetricDescriptor(object):
 
     :type metric_kind: string
     :param metric_kind:
-        The kind of measurement. It must be one of ``"GAUGE"``, ``"DELTA"``,
-        or ``"CUMULATIVE"``.
+        The kind of measurement. It must be one of ``MetricKind.GAUGE``,
+        ``MetricKind.DELTA``, or ``MetricKind.CUMULATIVE``.
+        See :class:`MetricKind`.
 
     :type value_type: string
     :param value_type:
-        The value type of the metric. It must be one of ``"BOOL"``,
-        ``"INT64"``, ``"DOUBLE"``, ``"STRING"``, ``"DISTRIBUTION"``,
-        or ``"MONEY"``.
+        The value type of the metric. It must be one of ``ValueType.BOOL``,
+        ``ValueType.INT64``, ``ValueType.DOUBLE``, ``ValueType.STRING``,
+        ``ValueType.DISTRIBUTION``, or ``ValueType.MONEY``.
+        See :class:`ValueType`.
 
     :type unit: string
     :param unit: The unit in which the metric value is reported.
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index 6fb2bb02ecae..50af6c77abad 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -159,6 +159,18 @@ def filter(self):
     def select_interval(self, end_time, start_time=None):
         """Copy the query and set the query time interval.
 
+        Example::
+
+            import datetime
+
+            now = datetime.datetime.utcnow()
+            query = query.select_interval(
+                end_time=now,
+                start_time=now - datetime.timedelta(minutes=5))
+
+        As a convenience, you can alternatively specify the end time and
+        an interval duration when you create the query initially.
+
         :type end_time: :class:`datetime.datetime`
         :param end_time: The end time (inclusive) of the time interval
             for which results should be returned, as a datetime object.
@@ -179,6 +191,10 @@ def select_interval(self, end_time, start_time=None):
     def select_group(self, group_id):
         """Copy the query and add filtering by group.
 
+        Example::
+
+            query = query.select_group('1234567')
+
         :type group_id: string
         :param group_id: The ID of a group to filter by.
 
@@ -307,17 +323,22 @@ def select_metrics(self, *args, **kwargs):
     def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
         """Copy the query and add temporal alignment.
 
-        If ``per_series_aligner`` is not ``"ALIGN_NONE"``, each time series
-        will contain data points only on the period boundaries.
+        If ``per_series_aligner`` is not ``Aligner.ALIGN_NONE``, each time
+        series will contain data points only on the period boundaries.
 
         Example::
 
+            query = query.align(Aligner.ALIGN_MEAN, minutes=5)
+
+        It is also possible to specify the aligner as a literal string::
+
             query = query.align('ALIGN_MEAN', minutes=5)
 
         :type per_series_aligner: string
         :param per_series_aligner: The approach to be used to align
-            individual time series. For example: ``"ALIGN_MEAN"``.
-            See the `supported aligners`_.
+            individual time series. For example: ``Aligner.ALIGN_MEAN``.
+            See :class:`Aligner` and the descriptions of the `supported
+            aligners`_.
 
         :type seconds: integer
         :param seconds: The number of seconds in the alignment period.
@@ -344,10 +365,20 @@ def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
     def reduce(self, cross_series_reducer, *group_by_fields):
         """Copy the query and add cross-series reduction.
 
+        Cross-series reduction combines time series by aggregating their
+        data points.
+
+        For example, you could request an aggregated time series for each
+        combination of project and zone as follows::
+
+            query = query.reduce(Reducer.REDUCE_MEAN,
+                                 'resource.project_id', 'resource.zone')
+
         :type cross_series_reducer: string
         :param cross_series_reducer:
             The approach to be used to combine time series. For example:
-            ``"REDUCE_MEAN"``. See the `supported reducers`_.
+            ``Reducer.REDUCE_MEAN``. See :class:`Reducer` and the descriptions
+            of the `supported reducers`_.
 
         :type group_by_fields: strings
         :param group_by_fields:

From 95f914788b239429d7754b4f8d843ee85fd65cb6 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 15 Apr 2016 19:45:47 -0400
Subject: [PATCH 24/61] Add some basic usage documentation.

---
 docs/index.rst            |   1 +
 docs/monitoring-usage.rst | 158 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 159 insertions(+)
 create mode 100644 docs/monitoring-usage.rst

diff --git a/docs/index.rst b/docs/index.rst
index dafc38daf4fe..dee362f4bc91 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -124,6 +124,7 @@
   :hidden:
   :caption: Cloud Monitoring
 
+  monitoring-usage
   Client <monitoring-client>
   monitoring-metric
   monitoring-resource
diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
new file mode 100644
index 000000000000..8ca2bb7e5215
--- /dev/null
+++ b/docs/monitoring-usage.rst
@@ -0,0 +1,158 @@
+Using the API
+=============
+
+
+Introduction
+------------
+
+With the Monitoring API, you can work with Stackdriver metric data
+pertaining to monitored resources in Google Cloud Platform (GCP)
+or elsewhere.
+
+Essential concepts:
+
+- Metric data is associated with a **monitored resource**. A monitored
+  resource has a *resource type* and a set of *resource labels* —
+  key-value pairs — that identify the particular resource.
+- A **metric** further identifies the particular kind of data that
+  is being collected. It has a *metric type* and a set of *metric
+  labels* that, when combined with the resource labels, identify
+  a particular time series.
+- A **time series** is a collection of data points associated with
+  points or intervals in time.
+
+Please refer to the documentation for the `Monitoring API`_ for
+more information.
+
+At present, this client library supports querying of time series,
+metric descriptors, and resource descriptors.
+
+.. _Monitoring API: https://cloud.google.com/monitoring/api/
+
+
+The Monitoring Client Object
+----------------------------
+
+The monitoring client library generally makes its
+functionality available as methods of the monitoring
+:class:`~gcloud.monitoring.client.Client` class.
+A :class:`~gcloud.monitoring.client.Client` instance holds
+authentication credentials and the ID of the target project with
+which the metric data of interest is associated. This project ID
+will often refer to a `Stackdriver account`_ binding multiple
+GCP projects and AWS accounts. It can also simply be the ID of
+a monitored project.
+
+Most often the authentication credentials will be determined
+implicitly from your environment. See :doc:`gcloud-auth` for
+more information.
+
+It is thus typical to create a client object as follows::
+
+    from gcloud import monitoring
+
+    client = monitoring.Client(project='target-project')
+
+If you are running in Google Compute Engine or Google App Engine,
+the current project is the default target project. This default
+can be further overridden with the :envvar:`GCLOUD_PROJECT`
+environment variable. Using the default target project is
+even easier::
+
+    client = monitoring.Client()
+
+If necessary, you can pass in ``credentials`` and ``project`` explicitly::
+
+    client = monitoring.Client(project='target-project', credentials=...)
+
+.. _Stackdriver account: https://cloud.google.com/monitoring/accounts/
+
+
+Monitored Resource Descriptors
+------------------------------
+
+The available monitored resource types are defined by *monitored resource
+descriptors*. You can fetch a list of these with the
+:meth:`~gcloud.monitoring.client.Client.list_resource_descriptors` method::
+
+    for descriptor in client.list_resource_descriptors():
+        print descriptor.type
+
+Each :class:`~gcloud.monitoring.resource.ResourceDescriptor`
+has a type, a display name, a description, and a list of
+:class:`~gcloud.monitoring.label.LabelDescriptor` instances.
+See the documentation about `Monitored Resources`_
+for more information.
+
+.. _Monitored Resources:
+    https://cloud.google.com/monitoring/api/v3/monitored-resources
+
+
+Metric Descriptors
+------------------
+
+The available metric types are defined by *metric descriptors*.
+They include `platform metrics`_, `agent metrics`_, and `custom metrics`_.
+You can list all of these with the
+:meth:`~gcloud.monitoring.client.Client.list_metric_descriptors` method::
+
+    for descriptor in client.list_metric_descriptors():
+        print descriptor.type
+
+See :class:`~gcloud.monitoring.metric.MetricDescriptor` and the
+`Metric Descriptors`_ API documentation for more information.
+
+.. _platform metrics: https://cloud.google.com/monitoring/api/metrics
+.. _agent metrics: https://cloud.google.com/monitoring/agent/
+.. _custom metrics: https://cloud.google.com/monitoring/custom-metrics/
+.. _Metric Descriptors:
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.metricDescriptors
+
+
+Time Series Queries
+-------------------
+
+A time series includes a collection of data points and a set of
+resource and metric label values.
+See :class:`~gcloud.monitoring.timeseries.TimeSeries` and the
+`Time Series`_ API documentation for more information.
+
+While you can obtain time series objects by iterating over a
+:class:`~gcloud.monitoring.query.Query` object, usually it is
+more useful to retrieve time series data in the form of a `pandas`_
+:class:`~pandas.DataFrame`, where each column corresponds to a
+single time series. For this, you must have ``pandas`` installed;
+it is not a required dependency of ``gcloud-python``.
+
+You can display CPU utilization across your GCE instances during
+the last five minutes as follows::
+
+    METRIC = 'compute.googleapis.com/instance/cpu/utilization'
+    query = client.query(METRIC, minutes=5)
+    print query.as_dataframe()
+
+:class:`~gcloud.monitoring.query.Query` objects provide a variety of
+methods for refining the query. You can request temporal alignment
+and cross-series reduction, and you can filter by label values.
+See the client :meth:`~gcloud.monitoring.client.Client.query` method
+and the :class:`~gcloud.monitoring.query.Query` class for more
+information.
+
+For example, you can display CPU utilization during the last hour
+across GCE instances with names beginning with ``"mycluster-"``,
+averaged over five-minute intervals and aggregated per zone, as
+follows::
+
+    from gcloud.monitoring import Aligner, Reducer
+
+    METRIC = 'compute.googleapis.com/instance/cpu/utilization'
+    query = client.query(METRIC, hours=1) \
+                  .select_metrics(instance_name_prefix='mycluster-') \
+                  .align(Aligner.ALIGN_MEAN, minutes=5) \
+                  .reduce(Reducer.REDUCE_MEAN, 'resource.zone')
+    print query.as_dataframe()
+
+.. _Time Series:
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
+.. _pandas: http://pandas.pydata.org/pandas-docs/stable/

From 1b231bc53ad22096eea7b501bb202acdcd5bf9cc Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Sat, 16 Apr 2016 09:29:04 -0400
Subject: [PATCH 25/61] Fix some remaining references to the pseudo-enums in a
 docstring.

---
 gcloud/monitoring/timeseries.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 79bea6793419..c545967e8c11 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -44,12 +44,16 @@ class TimeSeries(collections.namedtuple(
 
     :type metric_kind: string
     :param metric_kind:
-        The kind of measurement: ``"GAUGE"``. ``"DELTA"``, or ``"CUMULATIVE"``.
+        The kind of measurement: ``MetricKind.GAUGE``, ``MetricKind.DELTA``,
+        or ``MetricKind.CUMULATIVE``.
+        See :class:`~gcloud.monitoring.metric.MetricKind`.
 
     :type value_type: string
     :param value_type:
-        The value type of the metric: ``"BOOL"``, ``"INT64"``, ``"DOUBLE"``,
-        ``"STRING"``, ``"DISTRIBUTION"``, or ``"MONEY"``.
+        The value type of the metric: ``ValueType.BOOL``, ``ValueType.INT64``,
+        ``ValueType.DOUBLE``, ``ValueType.STRING``, ``ValueType.DISTRIBUTION``,
+        or ``ValueType.MONEY``.
+        See :class:`~gcloud.monitoring.metric.ValueType`.
 
     :type points: list of :class:`Point`
     :param points: A list of point objects.

From 1092feae304c8c6eaa82de331c869796db8a9763 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Sat, 16 Apr 2016 13:17:41 -0400
Subject: [PATCH 26/61] Add prompts (">>>") to examples showing interactive
 usage.

---
 docs/monitoring-usage.rst   | 38 ++++++++++++++++++-------------------
 gcloud/monitoring/client.py | 26 ++++++++++++-------------
 2 files changed, 31 insertions(+), 33 deletions(-)

diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
index 8ca2bb7e5215..daf84a33d5db 100644
--- a/docs/monitoring-usage.rst
+++ b/docs/monitoring-usage.rst
@@ -49,9 +49,8 @@ more information.
 
 It is thus typical to create a client object as follows::
 
-    from gcloud import monitoring
-
-    client = monitoring.Client(project='target-project')
+    >>> from gcloud import monitoring
+    >>> client = monitoring.Client(project='target-project')
 
 If you are running in Google Compute Engine or Google App Engine,
 the current project is the default target project. This default
@@ -59,11 +58,11 @@ can be further overridden with the :envvar:`GCLOUD_PROJECT`
 environment variable. Using the default target project is
 even easier::
 
-    client = monitoring.Client()
+    >>> client = monitoring.Client()
 
 If necessary, you can pass in ``credentials`` and ``project`` explicitly::
 
-    client = monitoring.Client(project='target-project', credentials=...)
+    >>> client = monitoring.Client(project='target-project', credentials=...)
 
 .. _Stackdriver account: https://cloud.google.com/monitoring/accounts/
 
@@ -75,8 +74,8 @@ The available monitored resource types are defined by *monitored resource
 descriptors*. You can fetch a list of these with the
 :meth:`~gcloud.monitoring.client.Client.list_resource_descriptors` method::
 
-    for descriptor in client.list_resource_descriptors():
-        print descriptor.type
+    >>> for descriptor in client.list_resource_descriptors():
+    ...     print descriptor.type
 
 Each :class:`~gcloud.monitoring.resource.ResourceDescriptor`
 has a type, a display name, a description, and a list of
@@ -96,8 +95,8 @@ They include `platform metrics`_, `agent metrics`_, and `custom metrics`_.
 You can list all of these with the
 :meth:`~gcloud.monitoring.client.Client.list_metric_descriptors` method::
 
-    for descriptor in client.list_metric_descriptors():
-        print descriptor.type
+    >>> for descriptor in client.list_metric_descriptors():
+    ...     print descriptor.type
 
 See :class:`~gcloud.monitoring.metric.MetricDescriptor` and the
 `Metric Descriptors`_ API documentation for more information.
@@ -128,9 +127,9 @@ it is not a required dependency of ``gcloud-python``.
 You can display CPU utilization across your GCE instances during
 the last five minutes as follows::
 
-    METRIC = 'compute.googleapis.com/instance/cpu/utilization'
-    query = client.query(METRIC, minutes=5)
-    print query.as_dataframe()
+    >>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
+    >>> query = client.query(METRIC, minutes=5)
+    >>> print query.as_dataframe()
 
 :class:`~gcloud.monitoring.query.Query` objects provide a variety of
 methods for refining the query. You can request temporal alignment
@@ -144,14 +143,13 @@ across GCE instances with names beginning with ``"mycluster-"``,
 averaged over five-minute intervals and aggregated per zone, as
 follows::
 
-    from gcloud.monitoring import Aligner, Reducer
-
-    METRIC = 'compute.googleapis.com/instance/cpu/utilization'
-    query = client.query(METRIC, hours=1) \
-                  .select_metrics(instance_name_prefix='mycluster-') \
-                  .align(Aligner.ALIGN_MEAN, minutes=5) \
-                  .reduce(Reducer.REDUCE_MEAN, 'resource.zone')
-    print query.as_dataframe()
+    >>> from gcloud.monitoring import Aligner, Reducer
+    >>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
+    >>> query = client.query(METRIC, hours=1) \
+    ...               .select_metrics(instance_name_prefix='mycluster-') \
+    ...               .align(Aligner.ALIGN_MEAN, minutes=5) \
+    ...               .reduce(Reducer.REDUCE_MEAN, 'resource.zone')
+    >>> print query.as_dataframe()
 
 .. _Time Series:
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 06703f0681f6..039c731f7766 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -16,10 +16,10 @@
 
 Example::
 
-    from gcloud import monitoring
-    client = monitoring.Client()
-    query = client.query(minutes=5)
-    print query.as_dataframe()  # Requires pandas.
+    >>> from gcloud import monitoring
+    >>> client = monitoring.Client()
+    >>> query = client.query(minutes=5)
+    >>> print query.as_dataframe()  # Requires pandas.
 
 At present, the client supports querying of time series, metric descriptors,
 and monitored resource descriptors.
@@ -64,8 +64,8 @@ def query(self,
 
         Example::
 
-            query = client.query(minutes=5)
-            print query.as_dataframe()  # Requires pandas.
+            >>> query = client.query(minutes=5)
+            >>> print query.as_dataframe()  # Requires pandas.
 
         :type metric_type: string
         :param metric_type: The metric type name. The default value is
@@ -116,8 +116,8 @@ def fetch_metric_descriptor(self, metric_type):
 
         Example::
 
-            METRIC = 'compute.googleapis.com/instance/cpu/utilization'
-            print client.fetch_metric_descriptor(METRIC)
+            >>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
+            >>> print client.fetch_metric_descriptor(METRIC)
 
         :type metric_type: string
         :param metric_type: The metric type name.
@@ -134,8 +134,8 @@ def list_metric_descriptors(self, filter=None):
 
         Example::
 
-            for descriptor in client.list_metric_descriptors():
-                print descriptor.type
+            >>> for descriptor in client.list_metric_descriptors():
+            ...     print descriptor.type
 
         :type filter: string or None
         :param filter: An optional filter string describing the metric
@@ -155,7 +155,7 @@ def fetch_resource_descriptor(self, resource_type):
 
         Example::
 
-            print client.fetch_resource_descriptor('gce_instance')
+            >>> print client.fetch_resource_descriptor('gce_instance')
 
         :type resource_type: string
         :param resource_type: The resource type name.
@@ -172,8 +172,8 @@ def list_resource_descriptors(self, filter=None):
 
         Example::
 
-            for descriptor in client.list_resource_descriptors():
-                print descriptor.type
+            >>> for descriptor in client.list_resource_descriptors():
+            ...     print descriptor.type
 
         :type filter: string or None
         :param filter: An optional filter string describing the resource

From a4795bbf1dc4952d56ff3a5527303624fc716296 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Sat, 16 Apr 2016 18:12:21 -0400
Subject: [PATCH 27/61] Add basic system tests.

---
 system_tests/monitoring.py      | 133 ++++++++++++++++++++++++++++++++
 system_tests/run_system_test.py |   2 +
 2 files changed, 135 insertions(+)
 create mode 100644 system_tests/monitoring.py

diff --git a/system_tests/monitoring.py b/system_tests/monitoring.py
new file mode 100644
index 000000000000..7cafa17bea65
--- /dev/null
+++ b/system_tests/monitoring.py
@@ -0,0 +1,133 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest2
+
+from gcloud import _helpers
+from gcloud.environment_vars import TESTS_PROJECT
+from gcloud import monitoring
+
+
+METRIC_TYPE = 'pubsub.googleapis.com/topic/send_message_operation_count'
+METRIC_KIND = monitoring.MetricKind.DELTA
+VALUE_TYPE = monitoring.ValueType.INT64
+
+RESOURCE_TYPE = 'pubsub_topic'
+
+
+def setUpModule():
+    _helpers.PROJECT = TESTS_PROJECT
+
+
+class TestMonitoring(unittest2.TestCase):
+
+    def test_fetch_metric_descriptor(self):
+        client = monitoring.Client()
+        descriptor = client.fetch_metric_descriptor(METRIC_TYPE)
+
+        expected_name = 'projects/{project}/metricDescriptors/{type}'.format(
+            project=client.project,
+            type=METRIC_TYPE,
+        )
+        self.assertEqual(descriptor.name, expected_name)
+        self.assertEqual(descriptor.type, METRIC_TYPE)
+        self.assertEqual(descriptor.metric_kind, METRIC_KIND)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+        self.assertTrue(descriptor.description)
+
+        self.assertTrue(descriptor.labels)
+        for label in descriptor.labels:
+            self.assertTrue(label.key)
+            self.assertTrue(label.value_type)
+            self.assertTrue(label.description)
+
+    def test_list_metric_descriptors(self):
+        client = monitoring.Client()
+
+        descriptor = None
+        for item in client.list_metric_descriptors():
+            if item.type == METRIC_TYPE:
+                descriptor = item
+
+        self.assertIsNotNone(descriptor)
+
+        expected_name = 'projects/{project}/{what}/{type}'.format(
+            project=client.project,
+            what='metricDescriptors',
+            type=METRIC_TYPE,
+        )
+        self.assertEqual(descriptor.name, expected_name)
+        self.assertEqual(descriptor.type, METRIC_TYPE)
+        self.assertEqual(descriptor.metric_kind, METRIC_KIND)
+        self.assertEqual(descriptor.value_type, VALUE_TYPE)
+        self.assertTrue(descriptor.description)
+
+        self.assertTrue(descriptor.labels)
+        for label in descriptor.labels:
+            self.assertTrue(label.key)
+            self.assertTrue(label.value_type)
+            self.assertTrue(label.description)
+
+    def test_fetch_resource_descriptor(self):
+        client = monitoring.Client()
+        descriptor = client.fetch_resource_descriptor(RESOURCE_TYPE)
+
+        expected_name = 'projects/{project}/{what}/{type}'.format(
+            project=client.project,
+            what='monitoredResourceDescriptors',
+            type=RESOURCE_TYPE,
+        )
+        self.assertEqual(descriptor.name, expected_name)
+        self.assertEqual(descriptor.type, RESOURCE_TYPE)
+        self.assertTrue(descriptor.display_name)
+        self.assertTrue(descriptor.description)
+
+        self.assertTrue(descriptor.labels)
+        for label in descriptor.labels:
+            self.assertTrue(label.key)
+            self.assertTrue(label.value_type)
+            self.assertTrue(label.description)
+
+    def test_list_resource_descriptors(self):
+        client = monitoring.Client()
+
+        descriptor = None
+        for item in client.list_resource_descriptors():
+            if item.type == RESOURCE_TYPE:
+                descriptor = item
+
+        self.assertIsNotNone(descriptor)
+
+        expected_name = 'projects/{project}/{what}/{type}'.format(
+            project=client.project,
+            what='monitoredResourceDescriptors',
+            type=RESOURCE_TYPE,
+        )
+        self.assertEqual(descriptor.name, expected_name)
+        self.assertEqual(descriptor.type, RESOURCE_TYPE)
+        self.assertTrue(descriptor.display_name)
+        self.assertTrue(descriptor.description)
+
+        self.assertTrue(descriptor.labels)
+        for label in descriptor.labels:
+            self.assertTrue(label.key)
+            self.assertTrue(label.value_type)
+            self.assertTrue(label.description)
+
+    def test_query(self):
+        client = monitoring.Client()
+        query = client.query(METRIC_TYPE, hours=1)
+        # There may be no data, but we can ask anyway.
+        for _ in query:
+            pass
diff --git a/system_tests/run_system_test.py b/system_tests/run_system_test.py
index c880a81bfe2a..6369a9bb7227 100644
--- a/system_tests/run_system_test.py
+++ b/system_tests/run_system_test.py
@@ -23,6 +23,7 @@
 import bigtable_happybase
 import datastore
 import logging_
+import monitoring
 import pubsub
 import storage
 import system_test_utils
@@ -36,6 +37,7 @@
     'bigtable': bigtable,
     'bigtable-happybase': bigtable_happybase,
     'logging': logging_,
+    'monitoring': monitoring,
 }
 
 

From adb7e102bb158a442e473166b66d5919334cfdbd Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Sat, 16 Apr 2016 18:32:53 -0400
Subject: [PATCH 28/61] Expect that the service will never return an empty
 name, type, or key.

---
 gcloud/monitoring/label.py         |  2 +-
 gcloud/monitoring/metric.py        |  6 +++---
 gcloud/monitoring/resource.py      |  6 +++---
 gcloud/monitoring/test_label.py    |  5 +++--
 gcloud/monitoring/test_metric.py   | 13 +++++++++----
 gcloud/monitoring/test_resource.py | 19 ++++++++++++++-----
 6 files changed, 33 insertions(+), 18 deletions(-)

diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
index 98861d7dea5f..e31f82024cc9 100644
--- a/gcloud/monitoring/label.py
+++ b/gcloud/monitoring/label.py
@@ -65,7 +65,7 @@ def _from_dict(cls, info):
         :returns: A label descriptor.
         """
         return cls(
-            info.get('key', ''),
+            info['key'],
             info.get('valueType', LabelValueType.STRING),
             info.get('description', ''),
         )
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 06010c13de5a..517183c193e4 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -187,8 +187,8 @@ def _from_dict(cls, info):
         :returns: A metric descriptor.
         """
         return cls(
-            name=info.get('name', ''),
-            type=info.get('type', ''),
+            name=info['name'],
+            type=info['type'],
             labels=tuple(LabelDescriptor._from_dict(label)
                          for label in info.get('labels', [])),
             metric_kind=info['metricKind'],
@@ -236,6 +236,6 @@ def _from_dict(cls, info):
         :returns: A metric object.
         """
         return cls(
-            type=info.get('type', ''),
+            type=info['type'],
             labels=info.get('labels', {}),
         )
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index ae9702a0565d..d4171f635efa 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -136,8 +136,8 @@ def _from_dict(cls, info):
         :returns: A resource descriptor.
         """
         return cls(
-            name=info.get('name', ''),
-            type=info.get('type', ''),
+            name=info['name'],
+            type=info['type'],
             display_name=info.get('displayName', ''),
             description=info.get('description', ''),
             labels=tuple(LabelDescriptor._from_dict(label)
@@ -181,6 +181,6 @@ def _from_dict(cls, info):
         :returns: A resource object.
         """
         return cls(
-            type=info.get('type', ''),
+            type=info['type'],
             labels=info.get('labels', {}),
         )
diff --git a/gcloud/monitoring/test_label.py b/gcloud/monitoring/test_label.py
index ede78ce9748e..862f2ce8dc53 100644
--- a/gcloud/monitoring/test_label.py
+++ b/gcloud/monitoring/test_label.py
@@ -64,8 +64,9 @@ def test_from_dict(self):
         self.assertEqual(descriptor.description, DESCRIPTION)
 
     def test_from_dict_defaults(self):
-        info = {}
+        KEY = 'response_code'
+        info = {'key': KEY}
         descriptor = self._getTargetClass()._from_dict(info)
-        self.assertEqual(descriptor.key, '')
+        self.assertEqual(descriptor.key, KEY)
         self.assertEqual(descriptor.value_type, 'STRING')
         self.assertEqual(descriptor.description, '')
diff --git a/gcloud/monitoring/test_metric.py b/gcloud/monitoring/test_metric.py
index bbff3c215dbd..38840a23b5a0 100644
--- a/gcloud/monitoring/test_metric.py
+++ b/gcloud/monitoring/test_metric.py
@@ -138,17 +138,21 @@ def test_from_dict(self):
         self.assertEqual(descriptor.display_name, DISPLAY_NAME)
 
     def test_from_dict_defaults(self):
+        TYPE = 'appengine.googleapis.com/http/server/response_count'
+        NAME = 'projects/my-project/metricDescriptors/' + TYPE
         METRIC_KIND = 'CUMULATIVE'
         VALUE_TYPE = 'DOUBLE'
 
         info = {
+            'name': NAME,
+            'type': TYPE,
             'metricKind': METRIC_KIND,
             'valueType': VALUE_TYPE,
         }
         descriptor = self._getTargetClass()._from_dict(info)
 
-        self.assertEqual(descriptor.name, '')
-        self.assertEqual(descriptor.type, '')
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
         self.assertEqual(descriptor.labels, ())
         self.assertEqual(descriptor.metric_kind, METRIC_KIND)
         self.assertEqual(descriptor.value_type, VALUE_TYPE)
@@ -347,9 +351,10 @@ def test_from_dict(self):
         self.assertEqual(metric.labels, LABELS)
 
     def test_from_dict_defaults(self):
-        info = {}
+        TYPE = 'appengine.googleapis.com/http/server/response_count'
+        info = {'type': TYPE}
         metric = self._getTargetClass()._from_dict(info)
-        self.assertEqual(metric.type, '')
+        self.assertEqual(metric.type, TYPE)
         self.assertEqual(metric.labels, {})
 
 
diff --git a/gcloud/monitoring/test_resource.py b/gcloud/monitoring/test_resource.py
index c027c63fbb47..786411b76cd6 100644
--- a/gcloud/monitoring/test_resource.py
+++ b/gcloud/monitoring/test_resource.py
@@ -87,9 +87,17 @@ def test_from_dict(self):
         self.assertEqual(label3.key, LABEL3['key'])
 
     def test_from_dict_defaults(self):
-        descriptor = self._getTargetClass()._from_dict({})
-        self.assertEqual(descriptor.name, '')
-        self.assertEqual(descriptor.type, '')
+        TYPE = 'gce_instance'
+        NAME = 'projects/my-project/monitoredResourceDescriptors/' + TYPE
+
+        info = {
+            'name': NAME,
+            'type': TYPE,
+        }
+        descriptor = self._getTargetClass()._from_dict(info)
+
+        self.assertEqual(descriptor.name, NAME)
+        self.assertEqual(descriptor.type, TYPE)
         self.assertEqual(descriptor.display_name, '')
         self.assertEqual(descriptor.description, '')
         self.assertEqual(descriptor.labels, ())
@@ -297,9 +305,10 @@ def test_from_dict(self):
         self.assertEqual(resource.labels, LABELS)
 
     def test_from_dict_defaults(self):
-        info = {}
+        TYPE = 'gce_instance'
+        info = {'type': TYPE}
         resource = self._getTargetClass()._from_dict(info)
-        self.assertEqual(resource.type, '')
+        self.assertEqual(resource.type, TYPE)
         self.assertEqual(resource.labels, {})
 
 

From eb738829da538981729b5c41377addc5d6936c35 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 10:36:02 -0400
Subject: [PATCH 29/61] Use print() in docstring examples.

---
 docs/monitoring-usage.rst   |  8 ++++----
 gcloud/monitoring/client.py | 12 ++++++------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
index daf84a33d5db..23cbd4c9f85b 100644
--- a/docs/monitoring-usage.rst
+++ b/docs/monitoring-usage.rst
@@ -75,7 +75,7 @@ descriptors*. You can fetch a list of these with the
 :meth:`~gcloud.monitoring.client.Client.list_resource_descriptors` method::
 
     >>> for descriptor in client.list_resource_descriptors():
-    ...     print descriptor.type
+    ...     print(descriptor.type)
 
 Each :class:`~gcloud.monitoring.resource.ResourceDescriptor`
 has a type, a display name, a description, and a list of
@@ -96,7 +96,7 @@ You can list all of these with the
 :meth:`~gcloud.monitoring.client.Client.list_metric_descriptors` method::
 
     >>> for descriptor in client.list_metric_descriptors():
-    ...     print descriptor.type
+    ...     print(descriptor.type)
 
 See :class:`~gcloud.monitoring.metric.MetricDescriptor` and the
 `Metric Descriptors`_ API documentation for more information.
@@ -129,7 +129,7 @@ the last five minutes as follows::
 
     >>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
     >>> query = client.query(METRIC, minutes=5)
-    >>> print query.as_dataframe()
+    >>> print(query.as_dataframe())
 
 :class:`~gcloud.monitoring.query.Query` objects provide a variety of
 methods for refining the query. You can request temporal alignment
@@ -149,7 +149,7 @@ follows::
     ...               .select_metrics(instance_name_prefix='mycluster-') \
     ...               .align(Aligner.ALIGN_MEAN, minutes=5) \
     ...               .reduce(Reducer.REDUCE_MEAN, 'resource.zone')
-    >>> print query.as_dataframe()
+    >>> print(query.as_dataframe())
 
 .. _Time Series:
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 039c731f7766..662b86e13044 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -19,7 +19,7 @@
     >>> from gcloud import monitoring
     >>> client = monitoring.Client()
     >>> query = client.query(minutes=5)
-    >>> print query.as_dataframe()  # Requires pandas.
+    >>> print(query.as_dataframe())  # Requires pandas.
 
 At present, the client supports querying of time series, metric descriptors,
 and monitored resource descriptors.
@@ -65,7 +65,7 @@ def query(self,
         Example::
 
             >>> query = client.query(minutes=5)
-            >>> print query.as_dataframe()  # Requires pandas.
+            >>> print(query.as_dataframe())  # Requires pandas.
 
         :type metric_type: string
         :param metric_type: The metric type name. The default value is
@@ -117,7 +117,7 @@ def fetch_metric_descriptor(self, metric_type):
         Example::
 
             >>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
-            >>> print client.fetch_metric_descriptor(METRIC)
+            >>> print(client.fetch_metric_descriptor(METRIC))
 
         :type metric_type: string
         :param metric_type: The metric type name.
@@ -135,7 +135,7 @@ def list_metric_descriptors(self, filter=None):
         Example::
 
             >>> for descriptor in client.list_metric_descriptors():
-            ...     print descriptor.type
+            ...     print(descriptor.type)
 
         :type filter: string or None
         :param filter: An optional filter string describing the metric
@@ -155,7 +155,7 @@ def fetch_resource_descriptor(self, resource_type):
 
         Example::
 
-            >>> print client.fetch_resource_descriptor('gce_instance')
+            >>> print(client.fetch_resource_descriptor('gce_instance'))
 
         :type resource_type: string
         :param resource_type: The resource type name.
@@ -173,7 +173,7 @@ def list_resource_descriptors(self, filter=None):
         Example::
 
             >>> for descriptor in client.list_resource_descriptors():
-            ...     print descriptor.type
+            ...     print(descriptor.type)
 
         :type filter: string or None
         :param filter: An optional filter string describing the resource

From aeeba8f82c7326722598ed2d82c0aef1a6a14a9e Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 11:43:04 -0400
Subject: [PATCH 30/61] Add pandas to the intersphinx configuration.

---
 docs/conf.py                    | 1 +
 docs/monitoring-usage.rst       | 7 +++----
 gcloud/monitoring/_dataframe.py | 7 ++-----
 gcloud/monitoring/query.py      | 6 ++----
 4 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 37842e9bc08c..6b2dcd872739 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -292,5 +292,6 @@
 intersphinx_mapping = {
     'httplib2': ('http://bitworking.org/projects/httplib2/doc/html/', None),
     'oauth2client': ('http://oauth2client.readthedocs.org/en/latest/', None),
+    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
     'python': ('https://docs.python.org/', None),
 }
diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
index 23cbd4c9f85b..0dddadfc8ddc 100644
--- a/docs/monitoring-usage.rst
+++ b/docs/monitoring-usage.rst
@@ -119,9 +119,9 @@ See :class:`~gcloud.monitoring.timeseries.TimeSeries` and the
 
 While you can obtain time series objects by iterating over a
 :class:`~gcloud.monitoring.query.Query` object, usually it is
-more useful to retrieve time series data in the form of a `pandas`_
-:class:`~pandas.DataFrame`, where each column corresponds to a
-single time series. For this, you must have ``pandas`` installed;
+more useful to retrieve time series data in the form of a
+:class:`pandas.DataFrame`, where each column corresponds to a
+single time series. For this, you must have :mod:`pandas` installed;
 it is not a required dependency of ``gcloud-python``.
 
 You can display CPU utilization across your GCE instances during
@@ -153,4 +153,3 @@ follows::
 
 .. _Time Series:
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
-.. _pandas: http://pandas.pydata.org/pandas-docs/stable/
diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index 0777a6379205..7220bb8ab436 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -12,10 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Time series as `pandas`_ dataframes.
-
-.. _pandas: http://pandas.pydata.org/pandas-docs/stable/
-"""
+"""Time series as :mod:`pandas` dataframes."""
 
 import itertools
 
@@ -30,7 +27,7 @@
 
 def _build_dataframe(time_series_iterable,
                      label=None, labels=None):  # pragma: NO COVER
-    """Build a ``pandas`` dataframe out of time series.
+    """Build a :mod:`pandas` dataframe out of time series.
 
     :type time_series_iterable:
         iterable over :class:`~gcloud.monitoring.timeseries.TimeSeries`
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index 50af6c77abad..ba6f882ae872 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -515,11 +515,11 @@ def _pairs():
         return list(_pairs())
 
     def as_dataframe(self, label=None, labels=None):
-        """Return all the selected time series as a `pandas`_ dataframe.
+        """Return all the selected time series as a :mod:`pandas` dataframe.
 
         .. note::
 
-            Use of this method requires that you have ``pandas`` installed.
+            Use of this method requires that you have :mod:`pandas` installed.
 
         Examples::
 
@@ -553,8 +553,6 @@ def as_dataframe(self, label=None, labels=None):
 
         :rtype: :class:`pandas.DataFrame`
         :returns: A dataframe where each column represents one time series.
-
-        .. _pandas: http://pandas.pydata.org/pandas-docs/stable/
         """
         return _build_dataframe(self, label, labels)  # pragma: NO COVER
 

From 5f85d998e0fd7f37c298e07b96f2cd55e0e3ecea Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 11:45:49 -0400
Subject: [PATCH 31/61] Alphabetical order.

---
 gcloud/monitoring/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gcloud/monitoring/__init__.py b/gcloud/monitoring/__init__.py
index 7cd11f8c2669..2ba783148131 100644
--- a/gcloud/monitoring/__init__.py
+++ b/gcloud/monitoring/__init__.py
@@ -23,8 +23,8 @@
 from gcloud.monitoring.metric import MetricKind
 from gcloud.monitoring.metric import ValueType
 from gcloud.monitoring.query import Aligner
-from gcloud.monitoring.query import Reducer
 from gcloud.monitoring.query import Query
+from gcloud.monitoring.query import Reducer
 from gcloud.monitoring.resource import Resource
 from gcloud.monitoring.resource import ResourceDescriptor
 from gcloud.monitoring.timeseries import Point

From a780431c45d517e9dccd867261e0e575e9b0cd7a Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 11:54:12 -0400
Subject: [PATCH 32/61] Change TOP_RESOURCE_LABELS from list to tuple.

---
 gcloud/monitoring/_dataframe.py      | 4 ++--
 gcloud/monitoring/test__dataframe.py | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index 7220bb8ab436..da8361b9edfc 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -16,13 +16,13 @@
 
 import itertools
 
-TOP_RESOURCE_LABELS = [
+TOP_RESOURCE_LABELS = (
     'project_id',
     'aws_account',
     'location',
     'region',
     'zone',
-]
+)
 
 
 def _build_dataframe(time_series_iterable,
diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 329ca14cc06a..eaa45a959779 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -213,11 +213,11 @@ def test_empty(self):
 
     def test_sorted(self):
         from gcloud.monitoring._dataframe import TOP_RESOURCE_LABELS
-        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
-        self.assertEqual(self._callFUT(EXPECTED), EXPECTED)
+        EXPECTED = TOP_RESOURCE_LABELS + ('other-1', 'other-2')
+        self.assertSequenceEqual(self._callFUT(EXPECTED), EXPECTED)
 
     def test_reversed(self):
         from gcloud.monitoring._dataframe import TOP_RESOURCE_LABELS
-        EXPECTED = TOP_RESOURCE_LABELS + ['other-1', 'other-2']
+        EXPECTED = TOP_RESOURCE_LABELS + ('other-1', 'other-2')
         INPUT = list(reversed(EXPECTED))
-        self.assertEqual(self._callFUT(INPUT), EXPECTED)
+        self.assertSequenceEqual(self._callFUT(INPUT), EXPECTED)

From 7432956425e19690c0454ad55e39858e3f035328 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 12:18:44 -0400
Subject: [PATCH 33/61] Rephrase a complex if-statement.

---
 gcloud/monitoring/_dataframe.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index da8361b9edfc..81d7e3321bfd 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -57,10 +57,11 @@ def _build_dataframe(time_series_iterable,
     """
     import pandas   # pylint: disable=import-error
 
-    if label is not None and labels is not None:
-        raise ValueError('Cannot specify both "label" and "labels".')
-    elif not (labels or labels is None):
-        raise ValueError('"labels" must be non-empty or None.')
+    if labels is not None:
+        if label is not None:
+            raise ValueError('Cannot specify both "label" and "labels".')
+        elif not labels:
+            raise ValueError('"labels" must be non-empty or None.')
 
     columns = []
     headers = []

From 663aecacc8b8bb4efefe103dc67313e029d9a452 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 12:21:06 -0400
Subject: [PATCH 34/61] p -> point

---
 gcloud/monitoring/_dataframe.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index 81d7e3321bfd..e31ba6282d4c 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -67,8 +67,8 @@ def _build_dataframe(time_series_iterable,
     headers = []
     for time_series in time_series_iterable:
         pandas_series = pandas.Series(
-            data=[p.value for p in time_series.points],
-            index=[p.end_time for p in time_series.points],
+            data=[point.value for point in time_series.points],
+            index=[point.end_time for point in time_series.points],
         )
         columns.append(pandas_series)
         headers.append(time_series.header())

From f07abbdf32f6a4e142052bf8217c43950c460299 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 12:36:27 -0400
Subject: [PATCH 35/61] Use DataFrame.from_records() to build from a list of
 rows.

---
 gcloud/monitoring/_dataframe.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index e31ba6282d4c..35339b4d8c59 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -84,7 +84,7 @@ def _build_dataframe(time_series_iterable,
                   sorted(metric_labels))
 
     # Assemble the columns into a DataFrame.
-    dataframe = pandas.DataFrame(columns).T
+    dataframe = pandas.DataFrame.from_records(columns).T
 
     # Convert the timestamp strings into a DatetimeIndex.
     dataframe.index = pandas.to_datetime(dataframe.index)

From c0b4b111465dce7f76414ac216cb0656d0203d79 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 13:02:14 -0400
Subject: [PATCH 36/61] Add a comment about the system test getting no time
 series data.

---
 system_tests/monitoring.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/system_tests/monitoring.py b/system_tests/monitoring.py
index 7cafa17bea65..5efbe0ce3a7b 100644
--- a/system_tests/monitoring.py
+++ b/system_tests/monitoring.py
@@ -130,4 +130,4 @@ def test_query(self):
         query = client.query(METRIC_TYPE, hours=1)
         # There may be no data, but we can ask anyway.
         for _ in query:
-            pass
+            pass    # Not necessarily reached.

From e43e8f5f9ec3a94e339e7edb65e5832625731a93 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 13:46:27 -0400
Subject: [PATCH 37/61] Use Query.DEFAULT_METRIC_TYPE cross-reference in doc
 strings.

---
 gcloud/monitoring/client.py | 5 +++--
 gcloud/monitoring/query.py  | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 662b86e13044..a35e40200546 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -69,8 +69,9 @@ def query(self,
 
         :type metric_type: string
         :param metric_type: The metric type name. The default value is
-            ``"compute.googleapis.com/instance/cpu/utilization"``, but
-            please note that this default value is provided only for
+            :data:`Query.DEFAULT_METRIC_TYPE
+            <gcloud.monitoring.query.Query.DEFAULT_METRIC_TYPE>`,
+            but please note that this default value is provided only for
             demonstration purposes and is subject to change. See the
             `supported metrics`_.
 
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index ba6f882ae872..fc086c7827f5 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -77,8 +77,9 @@ class Query(object):
 
     :type metric_type: string
     :param metric_type: The metric type name. The default value is
-        ``"compute.googleapis.com/instance/cpu/utilization"``, but
-        please note that this default value is provided only for
+        :data:`Query.DEFAULT_METRIC_TYPE
+        <gcloud.monitoring.query.Query.DEFAULT_METRIC_TYPE>`,
+        but please note that this default value is provided only for
         demonstration purposes and is subject to change. See the
         `supported metrics`_.
 

From 9bfafcf7020ebfde17ef475e5f247878684b7ab1 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 14:32:03 -0400
Subject: [PATCH 38/61] Add some docstring text about NotFound exceptions.

---
 gcloud/monitoring/client.py   | 6 ++++--
 gcloud/monitoring/metric.py   | 3 ++-
 gcloud/monitoring/resource.py | 3 ++-
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index a35e40200546..10196bf6440f 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -126,7 +126,8 @@ def fetch_metric_descriptor(self, metric_type):
         :rtype: :class:`~gcloud.monitoring.metric.MetricDescriptor`
         :returns: The metric descriptor instance.
 
-        :raises: :class:`gcloud.exceptions.NotFound`
+        :raises: :class:`gcloud.exceptions.NotFound` if the metric descriptor
+            is not found.
         """
         return MetricDescriptor._fetch(self, metric_type)
 
@@ -164,7 +165,8 @@ def fetch_resource_descriptor(self, resource_type):
         :rtype: :class:`~gcloud.monitoring.resource.ResourceDescriptor`
         :returns: The resource descriptor instance.
 
-        :raises: :class:`gcloud.exceptions.NotFound`
+        :raises: :class:`gcloud.exceptions.NotFound` if the resource descriptor
+            is not found.
         """
         return ResourceDescriptor._fetch(self, resource_type)
 
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 517183c193e4..e50132e3c832 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -122,7 +122,8 @@ def _fetch(cls, client, metric_type):
         :rtype: :class:`MetricDescriptor`
         :returns: The metric descriptor instance.
 
-        :raises: :class:`gcloud.exceptions.NotFound`
+        :raises: :class:`gcloud.exceptions.NotFound` if the metric descriptor
+            is not found.
         """
         path = '/projects/{project}/metricDescriptors/{type}'.format(
             project=client.project,
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index d4171f635efa..d4dcb831595c 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -71,7 +71,8 @@ def _fetch(cls, client, resource_type):
         :rtype: :class:`ResourceDescriptor`
         :returns: The resource descriptor instance.
 
-        :raises: :class:`gcloud.exceptions.NotFound`
+        :raises: :class:`gcloud.exceptions.NotFound` if the resource descriptor
+            is not found.
         """
         path = '/projects/{project}/monitoredResourceDescriptors/{type}' \
             .format(project=client.project,

From 44286412a7859ab569c82a02384145147d30c857 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 16:28:18 -0400
Subject: [PATCH 39/61] Rename "filter" parameter to "filter_" in private
 methods.

---
 gcloud/monitoring/metric.py        | 12 +++++-------
 gcloud/monitoring/resource.py      | 12 +++++-------
 gcloud/monitoring/test_metric.py   |  2 +-
 gcloud/monitoring/test_resource.py |  2 +-
 4 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index e50132e3c832..2de64e741910 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -132,14 +132,14 @@ def _fetch(cls, client, metric_type):
         return cls._from_dict(info)
 
     @classmethod
-    def _list(cls, client, filter=None):
+    def _list(cls, client, filter_=None):
         """List all metric descriptors for the project.
 
         :type client: :class:`gcloud.monitoring.client.Client`
         :param client: The client to use.
 
-        :type filter: string or None
-        :param filter: An optional filter string describing the metric
+        :type filter_: string or None
+        :param filter_: An optional filter string describing the metric
             descriptors to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`MetricDescriptor`
@@ -148,8 +148,6 @@ def _list(cls, client, filter=None):
         .. _filter documentation:
             https://cloud.google.com/monitoring/api/v3/filters
         """
-        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
-
         path = '/projects/{project}/metricDescriptors/'.format(
             project=client.project)
 
@@ -159,8 +157,8 @@ def _list(cls, client, filter=None):
         while True:
             params = {}
 
-            if filter is not None:
-                params['filter'] = filter
+            if filter_ is not None:
+                params['filter'] = filter_
 
             if page_token is not None:
                 params['pageToken'] = page_token
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index d4dcb831595c..81ea92b19f17 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -81,14 +81,14 @@ def _fetch(cls, client, resource_type):
         return cls._from_dict(info)
 
     @classmethod
-    def _list(cls, client, filter=None):
+    def _list(cls, client, filter_=None):
         """List all resource descriptors for the project.
 
         :type client: :class:`gcloud.monitoring.client.Client`
         :param client: The client to use.
 
-        :type filter: string or None
-        :param filter: An optional filter string describing the resource
+        :type filter_: string or None
+        :param filter_: An optional filter string describing the resource
             descriptors to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`ResourceDescriptor`
@@ -97,8 +97,6 @@ def _list(cls, client, filter=None):
         .. _filter documentation:
             https://cloud.google.com/monitoring/api/v3/filters
         """
-        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
-
         path = '/projects/{project}/monitoredResourceDescriptors/'.format(
             project=client.project)
 
@@ -108,8 +106,8 @@ def _list(cls, client, filter=None):
         while True:
             params = {}
 
-            if filter is not None:
-                params['filter'] = filter
+            if filter_ is not None:
+                params['filter'] = filter_
 
             if page_token is not None:
                 params['pageToken'] = page_token
diff --git a/gcloud/monitoring/test_metric.py b/gcloud/monitoring/test_metric.py
index 38840a23b5a0..605042d48bdf 100644
--- a/gcloud/monitoring/test_metric.py
+++ b/gcloud/monitoring/test_metric.py
@@ -307,7 +307,7 @@ def test_list_filtered(self):
 
         connection = _Connection(RESPONSE)
         client = _Client(project=PROJECT, connection=connection)
-        descriptors = self._getTargetClass()._list(client, filter=FILTER)
+        descriptors = self._getTargetClass()._list(client, FILTER)
 
         self.assertEqual(len(descriptors), 0)
 
diff --git a/gcloud/monitoring/test_resource.py b/gcloud/monitoring/test_resource.py
index 786411b76cd6..46d6d771b516 100644
--- a/gcloud/monitoring/test_resource.py
+++ b/gcloud/monitoring/test_resource.py
@@ -259,7 +259,7 @@ def test_list_filtered(self):
 
         connection = _Connection(RESPONSE)
         client = _Client(project=PROJECT, connection=connection)
-        descriptors = self._getTargetClass()._list(client, filter=FILTER)
+        descriptors = self._getTargetClass()._list(client, FILTER)
 
         self.assertEqual(len(descriptors), 0)
 

From f040b1b812d1e26afb5670885d9801ebab7e5cb2 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 16:44:44 -0400
Subject: [PATCH 40/61] Move status comments into module docstrings.

---
 gcloud/monitoring/metric.py     | 6 +++---
 gcloud/monitoring/timeseries.py | 8 ++++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 2de64e741910..4fa248ac7dda 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -14,14 +14,14 @@
 
 """Metric Descriptors for the `Google Monitoring API (V3)`_.
 
+Features intentionally omitted from this first version of the client library:
+  * Creating and deleting metric descriptors.
+
 .. _Google Monitoring API (V3):
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
     projects.metricDescriptors
 """
 
-# Features intentionally omitted from this first version of the client library:
-#   - Creating and deleting metric descriptors.
-
 import collections
 
 from gcloud.monitoring.label import LabelDescriptor
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index c545967e8c11..d3092e4d2dc5 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -14,14 +14,14 @@
 
 """Time series for the `Google Monitoring API (V3)`_.
 
+Features intentionally omitted from this first version of the client library:
+  * Writing time series.
+  * Natural representation of distribution values.
+
 .. _Google Monitoring API (V3):
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
 """
 
-# Features intentionally omitted from this first version of the client library:
-#   - Creating time series.
-#   - Natural representation of distribution values.
-
 import collections
 
 import six

From fcd2d2263e497abe8148ddf10fd05cd3ac0ce96a Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 17:02:20 -0400
Subject: [PATCH 41/61] Use :data: for docstring cross references to
 pseudo-enums.

---
 gcloud/monitoring/label.py      |  4 ++--
 gcloud/monitoring/metric.py     | 11 ++++++-----
 gcloud/monitoring/query.py      |  8 ++++----
 gcloud/monitoring/timeseries.py | 11 ++++++-----
 4 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
index e31f82024cc9..d2f7c92201af 100644
--- a/gcloud/monitoring/label.py
+++ b/gcloud/monitoring/label.py
@@ -40,8 +40,8 @@ class LabelDescriptor(object):
 
     :type value_type: string
     :param value_type:
-        The type of the label. It must be one of ``LabelValueType.STRING``,
-        ``LabelValueType.BOOL``, or ``LabelValueType.INT64``.
+        The type of the label. It must be one of :data:`LabelValueType.STRING`,
+        :data:`LabelValueType.BOOL`, or :data:`LabelValueType.INT64`.
         See :class:`LabelValueType`.
 
     :type description: string
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 4fa248ac7dda..d224a90e5d6b 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -76,15 +76,16 @@ class MetricDescriptor(object):
 
     :type metric_kind: string
     :param metric_kind:
-        The kind of measurement. It must be one of ``MetricKind.GAUGE``,
-        ``MetricKind.DELTA``, or ``MetricKind.CUMULATIVE``.
+        The kind of measurement. It must be one of :data:`MetricKind.GAUGE`,
+        :data:`MetricKind.DELTA`, or :data:`MetricKind.CUMULATIVE`.
         See :class:`MetricKind`.
 
     :type value_type: string
     :param value_type:
-        The value type of the metric. It must be one of ``ValueType.BOOL``,
-        ``ValueType.INT64``, ``ValueType.DOUBLE``, ``ValueType.STRING``,
-        ``ValueType.DISTRIBUTION``, or ``ValueType.MONEY``.
+        The value type of the metric. It must be one of :data:`ValueType.BOOL`,
+        :data:`ValueType.INT64`, :data:`ValueType.DOUBLE`,
+        :data:`ValueType.STRING`, :data:`ValueType.DISTRIBUTION`,
+        or :data:`ValueType.MONEY`.
         See :class:`ValueType`.
 
     :type unit: string
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index fc086c7827f5..6ae3fe52f194 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -324,7 +324,7 @@ def select_metrics(self, *args, **kwargs):
     def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
         """Copy the query and add temporal alignment.
 
-        If ``per_series_aligner`` is not ``Aligner.ALIGN_NONE``, each time
+        If ``per_series_aligner`` is not :data:`Aligner.ALIGN_NONE`, each time
         series will contain data points only on the period boundaries.
 
         Example::
@@ -337,7 +337,7 @@ def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
 
         :type per_series_aligner: string
         :param per_series_aligner: The approach to be used to align
-            individual time series. For example: ``Aligner.ALIGN_MEAN``.
+            individual time series. For example: :data:`Aligner.ALIGN_MEAN`.
             See :class:`Aligner` and the descriptions of the `supported
             aligners`_.
 
@@ -378,8 +378,8 @@ def reduce(self, cross_series_reducer, *group_by_fields):
         :type cross_series_reducer: string
         :param cross_series_reducer:
             The approach to be used to combine time series. For example:
-            ``Reducer.REDUCE_MEAN``. See :class:`Reducer` and the descriptions
-            of the `supported reducers`_.
+            :data:`Reducer.REDUCE_MEAN`. See :class:`Reducer` and the
+            descriptions of the `supported reducers`_.
 
         :type group_by_fields: strings
         :param group_by_fields:
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index d3092e4d2dc5..dfa2dc1737c4 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -44,15 +44,16 @@ class TimeSeries(collections.namedtuple(
 
     :type metric_kind: string
     :param metric_kind:
-        The kind of measurement: ``MetricKind.GAUGE``, ``MetricKind.DELTA``,
-        or ``MetricKind.CUMULATIVE``.
+        The kind of measurement: :data:`MetricKind.GAUGE`,
+        :data:`MetricKind.DELTA`, or :data:`MetricKind.CUMULATIVE`.
         See :class:`~gcloud.monitoring.metric.MetricKind`.
 
     :type value_type: string
     :param value_type:
-        The value type of the metric: ``ValueType.BOOL``, ``ValueType.INT64``,
-        ``ValueType.DOUBLE``, ``ValueType.STRING``, ``ValueType.DISTRIBUTION``,
-        or ``ValueType.MONEY``.
+        The value type of the metric: :data:`ValueType.BOOL`,
+        :data:`ValueType.INT64`, :data:`ValueType.DOUBLE`,
+        :data:`ValueType.STRING`, :data:`ValueType.DISTRIBUTION`,
+        or :data:`ValueType.MONEY`.
         See :class:`~gcloud.monitoring.metric.ValueType`.
 
     :type points: list of :class:`Point`

From 41e8ff20c658ce1d29574a1770f20d11dc266188 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 17:12:13 -0400
Subject: [PATCH 42/61] Change some empty lists to empty tuples.

---
 gcloud/monitoring/metric.py   | 2 +-
 gcloud/monitoring/query.py    | 2 +-
 gcloud/monitoring/resource.py | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index d224a90e5d6b..4623b1384f7e 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -166,7 +166,7 @@ def _list(cls, client, filter_=None):
 
             response = client.connection.api_request(
                 method='GET', path=path, query_params=params)
-            for info in response.get('metricDescriptors', []):
+            for info in response.get('metricDescriptors', ()):
                 descriptors.append(cls._from_dict(info))
 
             page_token = response.get('nextPageToken')
diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index 6ae3fe52f194..afb6dc1ff027 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -443,7 +443,7 @@ def _fragments():
                     path=path,
                     query_params=params,
                 )
-                for info in response.get('timeSeries', []):
+                for info in response.get('timeSeries', ()):
                     yield TimeSeries._from_dict(info)
 
                 page_token = response.get('nextPageToken')
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 81ea92b19f17..852f47c0041f 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -114,7 +114,7 @@ def _list(cls, client, filter_=None):
 
             response = client.connection.api_request(
                 method='GET', path=path, query_params=params)
-            for info in response.get('resourceDescriptors', []):
+            for info in response.get('resourceDescriptors', ()):
                 descriptors.append(cls._from_dict(info))
 
             page_token = response.get('nextPageToken')

From 4f47836acda64cfcde86a7d23863ae59c2f5ef06 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 17:55:08 -0400
Subject: [PATCH 43/61] _NOW -> _UTCNOW

---
 gcloud/monitoring/query.py      | 4 ++--
 gcloud/monitoring/test_query.py | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index afb6dc1ff027..cdb0f3fd394f 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -26,7 +26,7 @@
 from gcloud.monitoring._dataframe import _build_dataframe
 from gcloud.monitoring.timeseries import TimeSeries
 
-_NOW = datetime.datetime.utcnow  # To be replaced by tests.
+_UTCNOW = datetime.datetime.utcnow  # To be replaced by tests.
 
 
 class Aligner(object):
@@ -122,7 +122,7 @@ def __init__(self, client,
         start_time = None
         if days or hours or minutes:
             if end_time is None:
-                end_time = _NOW().replace(second=0, microsecond=0)
+                end_time = _UTCNOW().replace(second=0, microsecond=0)
             start_time = end_time - datetime.timedelta(days=days,
                                                        hours=hours,
                                                        minutes=minutes)
diff --git a/gcloud/monitoring/test_query.py b/gcloud/monitoring/test_query.py
index 7a570827d4f3..b44ab14065d3 100644
--- a/gcloud/monitoring/test_query.py
+++ b/gcloud/monitoring/test_query.py
@@ -132,7 +132,7 @@ def test_constructor_default_end_time(self):
         ]
 
         client = _Client(project=PROJECT, connection=_Connection())
-        with _Monkey(MUT, _NOW=lambda: NOW):
+        with _Monkey(MUT, _UTCNOW=lambda: NOW):
             query = self._makeOne(client, METRIC_TYPE, minutes=MINUTES)
 
         self.assertEqual(query._start_time, T0)

From 474b42d2aa83ef7ef8ac81eb84f04086e52c9659 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 18:10:50 -0400
Subject: [PATCH 44/61] Remove docstring text explaining about named tuples.

---
 gcloud/monitoring/metric.py     | 2 --
 gcloud/monitoring/resource.py   | 2 --
 gcloud/monitoring/timeseries.py | 4 ----
 3 files changed, 8 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 4623b1384f7e..8dc2cd7327c8 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -213,8 +213,6 @@ def __repr__(self):
 class Metric(collections.namedtuple('Metric', 'type labels')):
     """A specific metric identified by specifying values for all labels.
 
-    This is a named tuple. See :func:`collections.namedtuple`.
-
     :type type: string
     :param type: The metric type name.
 
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 852f47c0041f..26d8f3d28b0b 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -157,8 +157,6 @@ def __repr__(self):
 class Resource(collections.namedtuple('Resource', 'type labels')):
     """A monitored resource identified by specifying values for all labels.
 
-    This is a named tuple. See :func:`collections.namedtuple`.
-
     :type type: string
     :param type: The resource type name.
 
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index dfa2dc1737c4..49a9882ec54b 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -34,8 +34,6 @@ class TimeSeries(collections.namedtuple(
         'TimeSeries', 'metric resource metric_kind value_type points')):
     """A single time series of metric values.
 
-    This is a named tuple. See :func:`collections.namedtuple`.
-
     :type metric: :class:`~gcloud.monitoring.metric.Metric`
     :param metric: A metric object.
 
@@ -126,8 +124,6 @@ def __repr__(self):
 class Point(collections.namedtuple('Point', 'end_time start_time value')):
     """A single point in a time series.
 
-    This is a named tuple. See :func:`collections.namedtuple`.
-
     :type end_time: string
     :param end_time: The end time in RFC3339 UTC "Zulu" format.
 

From 259da039ce2c4d7e37394de64f3758caaaee5e09 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 18:24:38 -0400
Subject: [PATCH 45/61] Reformat a docstring example.

---
 gcloud/monitoring/query.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index cdb0f3fd394f..a805a14f16b6 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -405,8 +405,11 @@ def iter(self, headers_only=False, _page_size=None):
         Note that the :class:`Query` object itself is an iterable, such that
         the following are equivalent::
 
-            for timeseries in query: ...
-            for timeseries in query.iter(): ...
+            for timeseries in query:
+                ...
+
+            for timeseries in query.iter():
+                ...
 
         :type headers_only: boolean
         :param headers_only:

From 9bb980da21488145cf10ac63980eef34e566044a Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 18:26:38 -0400
Subject: [PATCH 46/61] _page_size -> page_size

---
 gcloud/monitoring/query.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index a805a14f16b6..a47da7fa4297 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -399,7 +399,7 @@ def reduce(self, cross_series_reducer, *group_by_fields):
         new_query._group_by_fields = group_by_fields
         return new_query
 
-    def iter(self, headers_only=False, _page_size=None):
+    def iter(self, headers_only=False, page_size=None):
         """Yield all time series objects selected by the query.
 
         Note that the :class:`Query` object itself is an iterable, such that
@@ -415,8 +415,8 @@ def iter(self, headers_only=False, _page_size=None):
         :param headers_only:
              Whether to omit the point data from the time series objects.
 
-        :type _page_size: integer or None
-        :param _page_size:
+        :type page_size: integer or None
+        :param page_size:
             An optional positive number specifying the maximum number of
             points to return per page. This can be used to control how far
             the iterator reads ahead.
@@ -438,7 +438,7 @@ def _fragments():
             while True:
                 params = self._build_query_params(
                     headers_only=headers_only,
-                    page_size=_page_size,
+                    page_size=page_size,
                     page_token=page_token,
                 )
                 response = self._client.connection.api_request(

From 3ed53f53c41a6e684453f6da4c094869e35c774b Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 21:18:28 -0400
Subject: [PATCH 47/61] Introduce an _iter_fragments() helper method.

---
 gcloud/monitoring/query.py | 61 +++++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 27 deletions(-)

diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index a47da7fa4297..8c0cfadb7bfa 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -427,42 +427,49 @@ def iter(self, headers_only=False, page_size=None):
         :raises: :exc:`ValueError` if the query time interval has not been
             specified.
         """
-        if self._end_time is None:
-            raise ValueError('Query time interval not specified.')
-
-        path = '/projects/{project}/timeSeries/'.format(
-            project=self._client.project)
-
-        def _fragments():
-            page_token = None
-            while True:
-                params = self._build_query_params(
-                    headers_only=headers_only,
-                    page_size=page_size,
-                    page_token=page_token,
-                )
-                response = self._client.connection.api_request(
-                    method='GET',
-                    path=path,
-                    query_params=params,
-                )
-                for info in response.get('timeSeries', ()):
-                    yield TimeSeries._from_dict(info)
-
-                page_token = response.get('nextPageToken')
-                if not page_token:
-                    break
-
         # The following use of groupby() relies on equality comparison
         # of time series as (named) tuples.
         for timeseries, fragments in itertools.groupby(
-                _fragments(),
+                self._iter_fragments(headers_only, page_size),
                 lambda fragment: fragment.header()):
             points = list(itertools.chain.from_iterable(
                 fragment.points for fragment in fragments))
             points.reverse()  # Order from oldest to newest.
             yield timeseries.header(points=points)
 
+    def _iter_fragments(self, headers_only=False, page_size=None):
+        """Yield all time series fragments selected by the query.
+
+        There may be multiple fragments per time series. These will be
+        contiguous.
+
+        The parameters and return value are as for :meth:`Query.iter`.
+        """
+        if self._end_time is None:
+            raise ValueError('Query time interval not specified.')
+
+        path = '/projects/{project}/timeSeries/'.format(
+            project=self._client.project)
+
+        page_token = None
+        while True:
+            params = self._build_query_params(
+                headers_only=headers_only,
+                page_size=page_size,
+                page_token=page_token,
+            )
+            response = self._client.connection.api_request(
+                method='GET',
+                path=path,
+                query_params=params,
+            )
+            for info in response.get('timeSeries', ()):
+                yield TimeSeries._from_dict(info)
+
+            page_token = response.get('nextPageToken')
+            if not page_token:
+                break
+
     def _build_query_params(self, headers_only=False,
                             page_size=None, page_token=None):
         """Assemble the list of key-value pairs for the URL query string.

From b2563eef724bfb529851a4563da5e8b20e874ce9 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 21:54:35 -0400
Subject: [PATCH 48/61] Make _build_query_params() a generator.

---
 gcloud/monitoring/query.py      | 57 ++++++++++++++++-----------------
 gcloud/monitoring/test_query.py |  9 +++---
 2 files changed, 32 insertions(+), 34 deletions(-)

diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index 8c0cfadb7bfa..df6a5973c460 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -453,11 +453,11 @@ def _iter_fragments(self, headers_only=False, page_size=None):
 
         page_token = None
         while True:
-            params = self._build_query_params(
+            params = list(self._build_query_params(
                 headers_only=headers_only,
                 page_size=page_size,
                 page_token=page_token,
-            )
+            ))
             response = self._client.connection.api_request(
                 method='GET',
                 path=path,
@@ -472,9 +472,9 @@ def _iter_fragments(self, headers_only=False, page_size=None):
 
     def _build_query_params(self, headers_only=False,
                             page_size=None, page_token=None):
-        """Assemble the list of key-value pairs for the URL query string.
+        """Yield key-value pairs for the URL query string.
 
-        We use a list of key-value pairs instead of a ``dict`` to allow for
+        We use a series of key-value pairs instead of a ``dict`` to allow for
         repeated fields.
 
         :type headers_only: boolean
@@ -488,42 +488,39 @@ def _build_query_params(self, headers_only=False,
         :type page_token: string or None
         :param page_token: A token to continue the retrieval.
 
-        :rtype: list of tuples
+        :rtype: iterator over tuples
         :returns:
-            A list of key-value pairs suitable for passing to ``urlencode``.
+            Key-value pairs suitable for passing to ``urlencode``.
         """
-        def _pairs():
-            yield 'filter', self.filter
-
-            yield 'interval.endTime', _format_timestamp(self._end_time)
-            if self._start_time is not None:
-                yield 'interval.startTime', _format_timestamp(self._start_time)
+        yield 'filter', self.filter
 
-            if self._per_series_aligner is not None:
-                yield 'aggregation.perSeriesAligner', self._per_series_aligner
+        yield 'interval.endTime', _format_timestamp(self._end_time)
+        if self._start_time is not None:
+            yield 'interval.startTime', _format_timestamp(self._start_time)
 
-            if self._alignment_period_seconds is not None:
-                alignment_period = '{period}s'.format(
-                    period=self._alignment_period_seconds)
-                yield 'aggregation.alignmentPeriod', alignment_period
+        if self._per_series_aligner is not None:
+            yield 'aggregation.perSeriesAligner', self._per_series_aligner
 
-            if self._cross_series_reducer is not None:
-                yield ('aggregation.crossSeriesReducer',
-                       self._cross_series_reducer)
+        if self._alignment_period_seconds is not None:
+            alignment_period = '{period}s'.format(
+                period=self._alignment_period_seconds)
+            yield 'aggregation.alignmentPeriod', alignment_period
 
-            for field in self._group_by_fields:
-                yield 'aggregation.groupByFields', field
+        if self._cross_series_reducer is not None:
+            yield ('aggregation.crossSeriesReducer',
+                   self._cross_series_reducer)
 
-            if headers_only:
-                yield 'view', 'HEADERS'
+        for field in self._group_by_fields:
+            yield 'aggregation.groupByFields', field
 
-            if page_size is not None:
-                yield 'pageSize', page_size
+        if headers_only:
+            yield 'view', 'HEADERS'
 
-            if page_token is not None:
-                yield 'pageToken', page_token
+        if page_size is not None:
+            yield 'pageSize', page_size
 
-        return list(_pairs())
+        if page_token is not None:
+            yield 'pageToken', page_token
 
     def as_dataframe(self, label=None, labels=None):
         """Return all the selected time series as a :mod:`pandas` dataframe.
diff --git a/gcloud/monitoring/test_query.py b/gcloud/monitoring/test_query.py
index b44ab14065d3..b6b5b3302e09 100644
--- a/gcloud/monitoring/test_query.py
+++ b/gcloud/monitoring/test_query.py
@@ -214,11 +214,12 @@ def test_request_parameters_minimal(self):
         client = _Client(project=PROJECT, connection=_Connection())
         query = self._makeOne(client, METRIC_TYPE)
         query = query.select_interval(end_time=T1)
+        actual = list(query._build_query_params())
         expected = [
             ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
             ('interval.endTime', T1.isoformat() + 'Z'),
         ]
-        self.assertEqual(query._build_query_params(), expected)
+        self.assertEqual(actual, expected)
 
     def test_request_parameters_maximal(self):
         import datetime
@@ -240,9 +241,9 @@ def test_request_parameters_maximal(self):
         query = query.select_interval(start_time=T0, end_time=T1)
         query = query.align(ALIGNER, minutes=MINUTES, seconds=SECONDS)
         query = query.reduce(REDUCER, FIELD1, FIELD2)
-        actual = query._build_query_params(headers_only=True,
-                                           page_size=PAGE_SIZE,
-                                           page_token=PAGE_TOKEN)
+        actual = list(query._build_query_params(headers_only=True,
+                                                page_size=PAGE_SIZE,
+                                                page_token=PAGE_TOKEN))
         expected = [
             ('filter', 'metric.type = "{type}"'.format(type=METRIC_TYPE)),
             ('interval.endTime', T1.isoformat() + 'Z'),

From e8a6f433d4acb5d7cf30e942b0ad85586cbdec46 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 22:49:58 -0400
Subject: [PATCH 49/61] Use six.iteritems().

---
 gcloud/monitoring/query.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/gcloud/monitoring/query.py b/gcloud/monitoring/query.py
index df6a5973c460..b8c529f50ae1 100644
--- a/gcloud/monitoring/query.py
+++ b/gcloud/monitoring/query.py
@@ -23,6 +23,8 @@
 import datetime
 import itertools
 
+import six
+
 from gcloud.monitoring._dataframe import _build_dataframe
 from gcloud.monitoring.timeseries import TimeSeries
 
@@ -624,8 +626,7 @@ def __str__(self):
 def _build_label_filter(category, *args, **kwargs):
     """Construct a filter string to filter on metric or resource labels."""
     terms = list(args)
-    for key in kwargs:
-        value = kwargs[key]
+    for key, value in six.iteritems(kwargs):
         if value is None:
             continue
 

From b336e610772933334475f90d64e49a456f4256bc Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Tue, 19 Apr 2016 23:52:26 -0400
Subject: [PATCH 50/61] Reorganize test data around DIMENSIONS instead of N and
 M.

---
 gcloud/monitoring/test__dataframe.py | 45 ++++++++++++++--------------
 1 file changed, 23 insertions(+), 22 deletions(-)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index eaa45a959779..06a9cec528d7 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -28,28 +28,28 @@
 INSTANCE_ZONES = ['us-east1-a', 'us-east1-b']
 INSTANCE_IDS = ['1234567890123456789', '9876543210987654321']
 
-M = len(INSTANCE_NAMES)
-
 METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
-METRIC_LABELS = list({'instance_name': INSTANCE_NAMES[i]}
-                     for i in range(M))
+METRIC_LABELS = list({'instance_name': name} for name in INSTANCE_NAMES)
 
 RESOURCE_TYPE = 'gce_instance'
-RESOURCE_LABELS = list({'project_id': PROJECT,
-                        'zone': INSTANCE_ZONES[i],
-                        'instance_id': INSTANCE_IDS[i]}
-                       for i in range(M))
+RESOURCE_LABELS = list({
+    'project_id': PROJECT,
+    'zone': zone,
+    'instance_id': instance_id,
+} for zone, instance_id in zip(INSTANCE_ZONES, INSTANCE_IDS))
 
 METRIC_KIND = 'GAUGE'
 VALUE_TYPE = 'DOUBLE'
-VALUES = list(0.1 * i for i in range(M))
 
 TIMESTAMPS = [
     '2016-04-06T22:05:00.042Z',
     '2016-04-06T22:05:01.042Z',
     '2016-04-06T22:05:02.042Z',
 ]
-N = len(TIMESTAMPS)
+
+DIMENSIONS = len(TIMESTAMPS), len(INSTANCE_NAMES)
+VALUES = list(0.1 * i for i in range(DIMENSIONS[1]))
+ARRAY = [VALUES] * DIMENSIONS[0]
 
 
 def parse_timestamps():  # pragma: NO COVER
@@ -70,13 +70,14 @@ def P(timestamp, value):
             value=value,
         )
 
-    for i in range(M):
+    for metric_labels, resource_labels, value in zip(
+            METRIC_LABELS, RESOURCE_LABELS, VALUES):
         yield TimeSeries(
-            metric=Metric(type=METRIC_TYPE, labels=METRIC_LABELS[i]),
-            resource=Resource(type=RESOURCE_TYPE, labels=RESOURCE_LABELS[i]),
+            metric=Metric(type=METRIC_TYPE, labels=metric_labels),
+            resource=Resource(type=RESOURCE_TYPE, labels=resource_labels),
             metric_kind=METRIC_KIND,
             value_type=VALUE_TYPE,
-            points=[P(t, VALUES[i]) for t in TIMESTAMPS],
+            points=[P(t, value) for t in TIMESTAMPS],
         )
 
 
@@ -99,8 +100,8 @@ def test_simple_label(self):
         iterable = generate_query_results()
         dataframe = self._callFUT(iterable, label='instance_name')
 
-        self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
 
         self.assertEqual(list(dataframe.columns), INSTANCE_NAMES)
         self.assertIsNone(dataframe.columns.name)
@@ -114,8 +115,8 @@ def test_multiple_labels(self):
         iterable = generate_query_results()
         dataframe = self._callFUT(iterable, labels=NAMES)
 
-        self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
 
         expected_headers = [(RESOURCE_TYPE, instance_id)
                             for instance_id in INSTANCE_IDS]
@@ -133,8 +134,8 @@ def test_multiple_labels_with_just_one(self):
         iterable = generate_query_results()
         dataframe = self._callFUT(iterable, labels=NAMES)
 
-        self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
 
         self.assertEqual(list(dataframe.columns), INSTANCE_IDS)
         self.assertEqual(dataframe.columns.names, NAMES)
@@ -151,8 +152,8 @@ def test_smart_labels(self):
         iterable = generate_query_results()
         dataframe = self._callFUT(iterable)
 
-        self.assertEqual(dataframe.shape, (N, M))
-        self.assertEqual(dataframe.values.tolist(), [VALUES] * N)
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
 
         expected_headers = [
             (RESOURCE_TYPE, PROJECT, zone, instance_id, instance_name)

From cb7ec374605c7a6011f431bbb5bfbbf9b1fb4823 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Wed, 20 Apr 2016 00:01:22 -0400
Subject: [PATCH 51/61] Restyle an import.

---
 gcloud/monitoring/test__dataframe.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index 06a9cec528d7..dc03bbd26e2a 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -61,7 +61,8 @@ def parse_timestamps():  # pragma: NO COVER
 def generate_query_results():  # pragma: NO COVER
     from gcloud.monitoring.metric import Metric
     from gcloud.monitoring.resource import Resource
-    from gcloud.monitoring.timeseries import Point, TimeSeries
+    from gcloud.monitoring.timeseries import Point
+    from gcloud.monitoring.timeseries import TimeSeries
 
     def P(timestamp, value):
         return Point(

From 6bccf2fb4cbbbf5ba20ec512f2c74b7aa5d24622 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Wed, 20 Apr 2016 00:31:30 -0400
Subject: [PATCH 52/61] Unpack points more elegantly.

---
 gcloud/monitoring/timeseries.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 49a9882ec54b..4a793ccc1c49 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -24,8 +24,6 @@
 
 import collections
 
-import six
-
 from gcloud.monitoring.metric import Metric
 from gcloud.monitoring.resource import Resource
 
@@ -147,7 +145,7 @@ def _from_dict(cls, info):
         """
         end_time = info['interval']['endTime']
         start_time = info['interval'].get('startTime')
-        value_type, value = next(six.iteritems(info['value']))
+        (value_type, value), = info['value'].items()
         if value_type == 'int64Value':
             value = int(value)  # Convert from string.
 

From fe8ee019e31d68a7fe8bfb0d5054dfb71958964f Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 21 Apr 2016 16:15:13 -0400
Subject: [PATCH 53/61] Remove pylint comment disabling redefined-builtin.

(It's disabled project-wide.)
---
 gcloud/monitoring/client.py   | 2 --
 gcloud/monitoring/metric.py   | 1 -
 gcloud/monitoring/resource.py | 1 -
 3 files changed, 4 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 10196bf6440f..873fe21b3236 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -149,7 +149,6 @@ def list_metric_descriptors(self, filter=None):
         .. _filter documentation:
             https://cloud.google.com/monitoring/api/v3/filters
         """
-        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
         return MetricDescriptor._list(self, filter)
 
     def fetch_resource_descriptor(self, resource_type):
@@ -188,5 +187,4 @@ def list_resource_descriptors(self, filter=None):
         .. _filter documentation:
             https://cloud.google.com/monitoring/api/v3/filters
         """
-        # Allow "filter" as a parameter name: pylint: disable=redefined-builtin
         return ResourceDescriptor._list(self, filter)
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 8dc2cd7327c8..09ce62c85404 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -100,7 +100,6 @@ class MetricDescriptor(object):
 
     def __init__(self, name, type, labels, metric_kind, value_type,
                  unit, description, display_name):
-        # Allow "type" as a parameter name: pylint: disable=redefined-builtin
         self.name = name
         self.type = type
         self.labels = labels
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 26d8f3d28b0b..231735e30512 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -51,7 +51,6 @@ class ResourceDescriptor(object):
     """
 
     def __init__(self, name, type, display_name, description, labels):
-        # Allow "type" as a parameter name: pylint: disable=redefined-builtin
         self.name = name
         self.type = type
         self.display_name = display_name

From 1f5e9e752a73918558a2374110df6948a1b6cc82 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 21 Apr 2016 16:42:14 -0400
Subject: [PATCH 54/61] Cache the label map without having to disable pylint.

---
 gcloud/monitoring/test_timeseries.py |  3 +++
 gcloud/monitoring/timeseries.py      | 10 +++++-----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/gcloud/monitoring/test_timeseries.py b/gcloud/monitoring/test_timeseries.py
index ae2609641d5c..b6839c548d6f 100644
--- a/gcloud/monitoring/test_timeseries.py
+++ b/gcloud/monitoring/test_timeseries.py
@@ -142,6 +142,9 @@ def test_labels(self):
         labels.update(RESOURCE_LABELS)
         labels.update(METRIC_LABELS)
 
+        self.assertIsNone(series._labels)
+        self.assertEqual(series.labels, labels)
+        self.assertIsNotNone(series._labels)
         self.assertEqual(series.labels, labels)
 
 
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index 4a793ccc1c49..b7d7aeae6cc8 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -56,6 +56,8 @@ class TimeSeries(collections.namedtuple(
     :param points: A list of point objects.
     """
 
+    _labels = None
+
     @property
     def labels(self):
         """A single dictionary with values for all the labels.
@@ -63,15 +65,13 @@ def labels(self):
         This combines ``resource.labels`` and ``metric.labels`` and also
         adds ``"resource_type"``.
         """
-        # pylint: disable=attribute-defined-outside-init
-        try:
-            return self._labels
-        except AttributeError:
+        if self._labels is None:
             labels = {'resource_type': self.resource.type}
             labels.update(self.resource.labels)
             labels.update(self.metric.labels)
             self._labels = labels
-            return self._labels
+
+        return self._labels
 
     def header(self, points=None):
         """Copy everything but the point data.

From 2d2969358cd6a05dd834f02533cd7816b1947604 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 21 Apr 2016 17:52:53 -0400
Subject: [PATCH 55/61] Excercise the test harness fully by reading past the
 available responses.

---
 gcloud/monitoring/test_client.py   | 6 +++++-
 gcloud/monitoring/test_metric.py   | 7 ++++++-
 gcloud/monitoring/test_query.py    | 6 +++++-
 gcloud/monitoring/test_resource.py | 7 ++++++-
 4 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/gcloud/monitoring/test_client.py b/gcloud/monitoring/test_client.py
index 6c1c27fd14e6..a30a0b8cd081 100644
--- a/gcloud/monitoring/test_client.py
+++ b/gcloud/monitoring/test_client.py
@@ -28,6 +28,7 @@ def _makeOne(self, *args, **kwargs):
 
     def test_query(self):
         import datetime
+        from gcloud.exceptions import NotFound
 
         START_TIME = datetime.datetime(2016, 4, 6, 22, 5, 0)
         END_TIME = datetime.datetime(2016, 4, 6, 22, 10, 0)
@@ -126,6 +127,9 @@ def P(timestamp, value):
         request, = connection._requested
         self.assertEqual(request, expected_request)
 
+        with self.assertRaises(NotFound):
+            list(query)
+
     def test_fetch_metric_descriptor(self):
         TYPE = 'custom.googleapis.com/my-metric'
         NAME = 'projects/{project}/metricDescriptors/{type}'.format(
@@ -321,5 +325,5 @@ def api_request(self, **kwargs):
         self._requested.append(kwargs)
         try:
             return self._responses.pop(0)
-        except IndexError:  # pragma: NO COVER
+        except IndexError:
             raise NotFound('miss')
diff --git a/gcloud/monitoring/test_metric.py b/gcloud/monitoring/test_metric.py
index 605042d48bdf..ceffb089e43a 100644
--- a/gcloud/monitoring/test_metric.py
+++ b/gcloud/monitoring/test_metric.py
@@ -238,6 +238,8 @@ def test_list(self):
         self.assertEqual(request, expected_request)
 
     def test_list_paged(self):
+        from gcloud.exceptions import NotFound
+
         PROJECT = 'my-project'
         PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
 
@@ -295,6 +297,9 @@ def test_list_paged(self):
         self.assertEqual(request1, expected_request1)
         self.assertEqual(request2, expected_request2)
 
+        with self.assertRaises(NotFound):
+            self._getTargetClass()._list(client)
+
     def test_list_filtered(self):
         PROJECT = 'my-project'
         PATH = 'projects/{project}/metricDescriptors/'.format(project=PROJECT)
@@ -369,7 +374,7 @@ def api_request(self, **kwargs):
         self._requested.append(kwargs)
         try:
             return self._responses.pop(0)
-        except IndexError:  # pragma: NO COVER
+        except IndexError:
             raise NotFound('miss')
 
 
diff --git a/gcloud/monitoring/test_query.py b/gcloud/monitoring/test_query.py
index b6b5b3302e09..5a0f187c0c00 100644
--- a/gcloud/monitoring/test_query.py
+++ b/gcloud/monitoring/test_query.py
@@ -329,6 +329,7 @@ def test_iteration(self):
     def test_iteration_paged(self):
         import copy
         import datetime
+        from gcloud.exceptions import NotFound
 
         T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
         T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
@@ -409,6 +410,9 @@ def test_iteration_paged(self):
         self.assertEqual(request1, expected_request1)
         self.assertEqual(request2, expected_request2)
 
+        with self.assertRaises(NotFound):
+            list(query)
+
     def test_iteration_empty(self):
         import datetime
 
@@ -623,7 +627,7 @@ def api_request(self, **kwargs):
         self._requested.append(kwargs)
         try:
             return self._responses.pop(0)
-        except IndexError:  # pragma: NO COVER
+        except IndexError:
             raise NotFound('miss')
 
 
diff --git a/gcloud/monitoring/test_resource.py b/gcloud/monitoring/test_resource.py
index 46d6d771b516..368c285e068e 100644
--- a/gcloud/monitoring/test_resource.py
+++ b/gcloud/monitoring/test_resource.py
@@ -192,6 +192,8 @@ def test_list(self):
         self.assertEqual(request, expected_request)
 
     def test_list_paged(self):
+        from gcloud.exceptions import NotFound
+
         PROJECT = 'my-project'
         PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
             project=PROJECT)
@@ -246,6 +248,9 @@ def test_list_paged(self):
         self.assertEqual(request1, expected_request1)
         self.assertEqual(request2, expected_request2)
 
+        with self.assertRaises(NotFound):
+            self._getTargetClass()._list(client)
+
     def test_list_filtered(self):
         PROJECT = 'my-project'
         PATH = 'projects/{project}/monitoredResourceDescriptors/'.format(
@@ -323,7 +328,7 @@ def api_request(self, **kwargs):
         self._requested.append(kwargs)
         try:
             return self._responses.pop(0)
-        except IndexError:  # pragma: NO COVER
+        except IndexError:
             raise NotFound('miss')
 
 

From 2dfd890e15b0b1b81ac294c65a43898af3f81da4 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Thu, 21 Apr 2016 17:59:43 -0400
Subject: [PATCH 56/61] Change some more empty lists into empty tuples.

---
 gcloud/monitoring/metric.py     | 2 +-
 gcloud/monitoring/resource.py   | 2 +-
 gcloud/monitoring/timeseries.py | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index 09ce62c85404..b2fee355e659 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -189,7 +189,7 @@ def _from_dict(cls, info):
             name=info['name'],
             type=info['type'],
             labels=tuple(LabelDescriptor._from_dict(label)
-                         for label in info.get('labels', [])),
+                         for label in info.get('labels', ())),
             metric_kind=info['metricKind'],
             value_type=info['valueType'],
             unit=info.get('unit', ''),
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 231735e30512..a43fbbcb86ad 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -139,7 +139,7 @@ def _from_dict(cls, info):
             display_name=info.get('displayName', ''),
             description=info.get('description', ''),
             labels=tuple(LabelDescriptor._from_dict(label)
-                         for label in info.get('labels', [])),
+                         for label in info.get('labels', ())),
         )
 
     def __repr__(self):
diff --git a/gcloud/monitoring/timeseries.py b/gcloud/monitoring/timeseries.py
index b7d7aeae6cc8..caa733a7cfc6 100644
--- a/gcloud/monitoring/timeseries.py
+++ b/gcloud/monitoring/timeseries.py
@@ -100,7 +100,7 @@ def _from_dict(cls, info):
         resource = Resource._from_dict(info['resource'])
         metric_kind = info['metricKind']
         value_type = info['valueType']
-        points = [Point._from_dict(p) for p in info.get('points', [])]
+        points = [Point._from_dict(p) for p in info.get('points', ())]
         return cls(metric, resource, metric_kind, value_type, points)
 
     def __repr__(self):

From 681292dd83ebf30635435fb180ef11d3d3288c21 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 22 Apr 2016 08:47:06 -0400
Subject: [PATCH 57/61] filter/filter_ -> filter_string

---
 gcloud/monitoring/client.py   | 22 ++++++++++++----------
 gcloud/monitoring/metric.py   | 13 +++++++------
 gcloud/monitoring/resource.py | 13 +++++++------
 3 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
index 873fe21b3236..633740a36cb1 100644
--- a/gcloud/monitoring/client.py
+++ b/gcloud/monitoring/client.py
@@ -131,7 +131,7 @@ def fetch_metric_descriptor(self, metric_type):
         """
         return MetricDescriptor._fetch(self, metric_type)
 
-    def list_metric_descriptors(self, filter=None):
+    def list_metric_descriptors(self, filter_string=None):
         """List all metric descriptors for the project.
 
         Example::
@@ -139,9 +139,10 @@ def list_metric_descriptors(self, filter=None):
             >>> for descriptor in client.list_metric_descriptors():
             ...     print(descriptor.type)
 
-        :type filter: string or None
-        :param filter: An optional filter string describing the metric
-            descriptors to be returned. See the `filter documentation`_.
+        :type filter_string: string or None
+        :param filter_string:
+            An optional filter expression describing the metric descriptors
+            to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`~gcloud.monitoring.metric.MetricDescriptor`
         :returns: A list of metric descriptor instances.
@@ -149,7 +150,7 @@ def list_metric_descriptors(self, filter=None):
         .. _filter documentation:
             https://cloud.google.com/monitoring/api/v3/filters
         """
-        return MetricDescriptor._list(self, filter)
+        return MetricDescriptor._list(self, filter_string)
 
     def fetch_resource_descriptor(self, resource_type):
         """Look up a resource descriptor by type.
@@ -169,7 +170,7 @@ def fetch_resource_descriptor(self, resource_type):
         """
         return ResourceDescriptor._fetch(self, resource_type)
 
-    def list_resource_descriptors(self, filter=None):
+    def list_resource_descriptors(self, filter_string=None):
         """List all resource descriptors for the project.
 
         Example::
@@ -177,9 +178,10 @@ def list_resource_descriptors(self, filter=None):
             >>> for descriptor in client.list_resource_descriptors():
             ...     print(descriptor.type)
 
-        :type filter: string or None
-        :param filter: An optional filter string describing the resource
-            descriptors to be returned. See the `filter documentation`_.
+        :type filter_string: string or None
+        :param filter_string:
+            An optional filter expression describing the resource descriptors
+            to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`~gcloud.monitoring.resource.ResourceDescriptor`
         :returns: A list of resource descriptor instances.
@@ -187,4 +189,4 @@ def list_resource_descriptors(self, filter=None):
         .. _filter documentation:
             https://cloud.google.com/monitoring/api/v3/filters
         """
-        return ResourceDescriptor._list(self, filter)
+        return ResourceDescriptor._list(self, filter_string)
diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index b2fee355e659..d044b7302859 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -132,15 +132,16 @@ def _fetch(cls, client, metric_type):
         return cls._from_dict(info)
 
     @classmethod
-    def _list(cls, client, filter_=None):
+    def _list(cls, client, filter_string=None):
         """List all metric descriptors for the project.
 
         :type client: :class:`gcloud.monitoring.client.Client`
         :param client: The client to use.
 
-        :type filter_: string or None
-        :param filter_: An optional filter string describing the metric
-            descriptors to be returned. See the `filter documentation`_.
+        :type filter_string: string or None
+        :param filter_string:
+            An optional filter expression describing the metric descriptors
+            to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`MetricDescriptor`
         :returns: A list of metric descriptor instances.
@@ -157,8 +158,8 @@ def _list(cls, client, filter_=None):
         while True:
             params = {}
 
-            if filter_ is not None:
-                params['filter'] = filter_
+            if filter_string is not None:
+                params['filter'] = filter_string
 
             if page_token is not None:
                 params['pageToken'] = page_token
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index a43fbbcb86ad..650bbaa779d4 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -80,15 +80,16 @@ def _fetch(cls, client, resource_type):
         return cls._from_dict(info)
 
     @classmethod
-    def _list(cls, client, filter_=None):
+    def _list(cls, client, filter_string=None):
         """List all resource descriptors for the project.
 
         :type client: :class:`gcloud.monitoring.client.Client`
         :param client: The client to use.
 
-        :type filter_: string or None
-        :param filter_: An optional filter string describing the resource
-            descriptors to be returned. See the `filter documentation`_.
+        :type filter_string: string or None
+        :param filter_string:
+            An optional filter expression describing the resource descriptors
+            to be returned. See the `filter documentation`_.
 
         :rtype: list of :class:`ResourceDescriptor`
         :returns: A list of resource descriptor instances.
@@ -105,8 +106,8 @@ def _list(cls, client, filter_=None):
         while True:
             params = {}
 
-            if filter_ is not None:
-                params['filter'] = filter_
+            if filter_string is not None:
+                params['filter'] = filter_string
 
             if page_token is not None:
                 params['pageToken'] = page_token

From b6bf58e58b2f3d1405d3b7b789ae9d3fdd00169c Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 22 Apr 2016 09:10:20 -0400
Subject: [PATCH 58/61] '%Y-%m-%dT%H:%M:%S.%fZ' -> _RFC3339_MICROS

---
 gcloud/monitoring/test__dataframe.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gcloud/monitoring/test__dataframe.py b/gcloud/monitoring/test__dataframe.py
index dc03bbd26e2a..dfccf6c6f913 100644
--- a/gcloud/monitoring/test__dataframe.py
+++ b/gcloud/monitoring/test__dataframe.py
@@ -54,7 +54,8 @@
 
 def parse_timestamps():  # pragma: NO COVER
     import datetime
-    return [datetime.datetime.strptime(t, '%Y-%m-%dT%H:%M:%S.%fZ')
+    from gcloud._helpers import _RFC3339_MICROS
+    return [datetime.datetime.strptime(t, _RFC3339_MICROS)
             for t in TIMESTAMPS]
 
 

From a088e33ca0cd8dbec10c12656884eafb2a6704ef Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 22 Apr 2016 10:43:28 -0400
Subject: [PATCH 59/61] Use parentheses instead of backslashes.

---
 docs/.DS_Store                | Bin 0 -> 6148 bytes
 docs/monitoring-usage.rst     |   8 ++++----
 gcloud/monitoring/resource.py |   6 +++---
 3 files changed, 7 insertions(+), 7 deletions(-)
 create mode 100644 docs/.DS_Store

diff --git a/docs/.DS_Store b/docs/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..f41eff01ff9c737d8260c227aa472125ab65d41d
GIT binary patch
literal 6148
zcmeHKJx{|h5IxhVRAuRe7`^ZVx-mvo*pVtEHa?mPDmApCt;Cp-e}MQY{0;_Y5Gx}K
z6YuO3ic_Z}0(2*xpJU%$US1SCCL%Lf<$a<a5q02<Nf%ATc%FUDwq%5pjjJ)Ge0td*
zj%LMtEm{Xu0af6)DZt-un@;J1Ry3jd_xt?uP@gYmS(dMsBci8+>qqxEL4GmIH_p$m
zD(k~r$_2XB`=ftD%i22fe%o$}3;4Wnxp=*R*M_)&->0j$4NePiI)_ha6s&Nq;}gWx
zA}XBr?_OgyDr_1e0v^c`7h#>2G^T>)cvH+~OpAaG?cO)VML0$4MVLk70)AwfpW5G2
z0DCrDXUC(qs(>n>3VbWT>w|?erh=tMw{)O!M*v`gVQ1*`F9qjV!BnvHh#8pisX(7<
z<cMK>I>xQUrGlkLpH4;&A4cwM<b-0}-BI7Va5AY!ZB+qPAXK2`FMGWIA2y%=!z8^@
z1yq55rGQDYVK%@c$=<s5aJ<)A_!*py<4TV%1&wUSuESgL9^4t`EO&sZVCfMfF#Qp5
LGH9a;{HOw7dWDe$

literal 0
HcmV?d00001

diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
index 0dddadfc8ddc..521b91411e92 100644
--- a/docs/monitoring-usage.rst
+++ b/docs/monitoring-usage.rst
@@ -145,10 +145,10 @@ follows::
 
     >>> from gcloud.monitoring import Aligner, Reducer
     >>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
-    >>> query = client.query(METRIC, hours=1) \
-    ...               .select_metrics(instance_name_prefix='mycluster-') \
-    ...               .align(Aligner.ALIGN_MEAN, minutes=5) \
-    ...               .reduce(Reducer.REDUCE_MEAN, 'resource.zone')
+    >>> query = (client.query(METRIC, hours=1)
+    ...          .select_metrics(instance_name_prefix='mycluster-')
+    ...          .align(Aligner.ALIGN_MEAN, minutes=5)
+    ...          .reduce(Reducer.REDUCE_MEAN, 'resource.zone'))
     >>> print(query.as_dataframe())
 
 .. _Time Series:
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 650bbaa779d4..79418acd6188 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -73,9 +73,9 @@ def _fetch(cls, client, resource_type):
         :raises: :class:`gcloud.exceptions.NotFound` if the resource descriptor
             is not found.
         """
-        path = '/projects/{project}/monitoredResourceDescriptors/{type}' \
-            .format(project=client.project,
-                    type=resource_type)
+        path = ('/projects/{project}/monitoredResourceDescriptors/{type}'
+                .format(project=client.project,
+                        type=resource_type))
         info = client.connection.api_request(method='GET', path=path)
         return cls._from_dict(info)
 

From ae124aee091baa157f35943b347f180e918ef76b Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 22 Apr 2016 10:49:33 -0400
Subject: [PATCH 60/61] Reorganize a hard-to-understand bit of code for
 building multi-level column headers.

---
 gcloud/monitoring/_dataframe.py | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/gcloud/monitoring/_dataframe.py b/gcloud/monitoring/_dataframe.py
index 35339b4d8c59..1b5b1944d918 100644
--- a/gcloud/monitoring/_dataframe.py
+++ b/gcloud/monitoring/_dataframe.py
@@ -89,15 +89,19 @@ def _build_dataframe(time_series_iterable,
     # Convert the timestamp strings into a DatetimeIndex.
     dataframe.index = pandas.to_datetime(dataframe.index)
 
-    # Build a column Index or MultiIndex from the label values. Do not
-    # include level names in the column header if the user requested a
-    # single-level header by specifying "label".
-    level_names = labels or None
-    label_keys = labels or [label]
+    # Build a multi-level stack of column headers. Some labels may
+    # be undefined for some time series.
+    levels = []
+    for key in labels or [label]:
+        level = [header.labels.get(key, '') for header in headers]
+        levels.append(level)
+
+    # Build a column Index or MultiIndex. Do not include level names
+    # in the column header if the user requested a single-level header
+    # by specifying "label".
     dataframe.columns = pandas.MultiIndex.from_arrays(
-        [[header.labels.get(key, '') for header in headers]
-         for key in label_keys],
-        names=level_names)
+        levels,
+        names=labels or None)
 
     # Sort the rows just in case (since the API doesn't guarantee the
     # ordering), and sort the columns lexicographically.

From 13e98c0a712d32711f2aa4b9e0cf329841de0e93 Mon Sep 17 00:00:00 2001
From: Ken Rimey <rimey@google.com>
Date: Fri, 22 Apr 2016 13:21:58 -0400
Subject: [PATCH 61/61] type -> type_

---
 gcloud/monitoring/metric.py        | 10 +++++-----
 gcloud/monitoring/resource.py      | 10 +++++-----
 gcloud/monitoring/test_metric.py   |  2 +-
 gcloud/monitoring/test_resource.py |  2 +-
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/gcloud/monitoring/metric.py b/gcloud/monitoring/metric.py
index d044b7302859..a6c3f3eae82d 100644
--- a/gcloud/monitoring/metric.py
+++ b/gcloud/monitoring/metric.py
@@ -64,8 +64,8 @@ class MetricDescriptor(object):
         The "resource name" of the metric descriptor. For example:
         ``"projects/<project_id>/metricDescriptors/<type>"``
 
-    :type type: string
-    :param type:
+    :type type_: string
+    :param type_:
         The metric type including a DNS name prefix. For example:
         ``"compute.googleapis.com/instance/cpu/utilization"``
 
@@ -98,10 +98,10 @@ class MetricDescriptor(object):
     :param display_name: A concise name for the metric.
     """
 
-    def __init__(self, name, type, labels, metric_kind, value_type,
+    def __init__(self, name, type_, labels, metric_kind, value_type,
                  unit, description, display_name):
         self.name = name
-        self.type = type
+        self.type = type_
         self.labels = labels
         self.metric_kind = metric_kind
         self.value_type = value_type
@@ -188,7 +188,7 @@ def _from_dict(cls, info):
         """
         return cls(
             name=info['name'],
-            type=info['type'],
+            type_=info['type'],
             labels=tuple(LabelDescriptor._from_dict(label)
                          for label in info.get('labels', ())),
             metric_kind=info['metricKind'],
diff --git a/gcloud/monitoring/resource.py b/gcloud/monitoring/resource.py
index 79418acd6188..5d377cbb9ba1 100644
--- a/gcloud/monitoring/resource.py
+++ b/gcloud/monitoring/resource.py
@@ -32,8 +32,8 @@ class ResourceDescriptor(object):
         The "resource name" of the monitored resource descriptor:
         ``"projects/<project_id>/monitoredResourceDescriptors/<type>"``
 
-    :type type: string
-    :param type:
+    :type type_: string
+    :param type_:
         The monitored resource type. For example: ``"gce_instance"``
 
     :type display_name: string
@@ -50,9 +50,9 @@ class ResourceDescriptor(object):
         to identify a specific instance of this monitored resource.
     """
 
-    def __init__(self, name, type, display_name, description, labels):
+    def __init__(self, name, type_, display_name, description, labels):
         self.name = name
-        self.type = type
+        self.type = type_
         self.display_name = display_name
         self.description = description
         self.labels = labels
@@ -136,7 +136,7 @@ def _from_dict(cls, info):
         """
         return cls(
             name=info['name'],
-            type=info['type'],
+            type_=info['type'],
             display_name=info.get('displayName', ''),
             description=info.get('description', ''),
             labels=tuple(LabelDescriptor._from_dict(label)
diff --git a/gcloud/monitoring/test_metric.py b/gcloud/monitoring/test_metric.py
index ceffb089e43a..19e6f76cba78 100644
--- a/gcloud/monitoring/test_metric.py
+++ b/gcloud/monitoring/test_metric.py
@@ -75,7 +75,7 @@ def test_constructor(self):
 
         descriptor = self._makeOne(
             name=NAME,
-            type=TYPE,
+            type_=TYPE,
             labels=LABELS,
             metric_kind=METRIC_KIND,
             value_type=VALUE_TYPE,
diff --git a/gcloud/monitoring/test_resource.py b/gcloud/monitoring/test_resource.py
index 368c285e068e..deba3c6cbc90 100644
--- a/gcloud/monitoring/test_resource.py
+++ b/gcloud/monitoring/test_resource.py
@@ -42,7 +42,7 @@ def test_constructor(self):
 
         descriptor = self._makeOne(
             name=NAME,
-            type=TYPE,
+            type_=TYPE,
             display_name=DISPLAY_NAME,
             description=DESCRIPTION,
             labels=LABELS,