Add Docs and Service account project ID

Author: daspecster

docs/gcloud-config.rst

@@ -0,0 +1,55 @@
+Configuration
+*************
+
+Overview
+========
+
+- Use service :class:`Client <gcloud.client.Client>` objects to configure
+  your applications.
+
+  For example:
+
+  .. code-block:: python
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client()
+
+- :class:`Client <gcloud.client.Client>` objects hold both a ``project``
+  and an authenticated connection to a service.
+
+- The authentication credentials can be implicitly determined from the
+  environment or directly via
+  :meth:`from_service_account_json <gcloud.client.Client.from_service_account_json>`
+  and
+  :meth:`from_service_account_p12 <gcloud.client.Client.from_service_account_p12>`.
+
+- Logging in with the `Google Cloud SDK`_ will automatically configure a JSON
+  key file with your default project ID and credentials.
+  Setting the ``GOOGLE_APPLICATION_CREDENTIALS`` and ``GCLOUD_PROJECT``
+  environment variables will override the automatically configured credentials.
+
+- You can change your default project ID to ``my-new-default-project`` with
+  ``gcloud`` command line tool.
+
+  .. code-block:: bash
+
+     $ gcloud config set project my-new-default-project
+
+.. _Google Cloud SDK: http://cloud.google.com/sdk
+
+- You can override the credentials inferred from the environment by passing
+  explicit ``credentials`` to one of the alternative ``classmethod`` factories,
+  :meth:`gcloud.client.Client.from_service_account_json`:
+
+  .. code-block:: python
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client.from_service_account_json('/path/to/creds.json')
+
+  or :meth:`gcloud.client.Client.from_service_account_p12`:
+
+  .. code-block:: python
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client.from_service_account_p12(
+     ...     '/path/to/creds.p12', '[email protected]')

docs/index.rst

@@ -4,6 +4,7 @@
   :caption: gcloud
 
   gcloud-api
+  gcloud-config
   gcloud-auth
 
 .. toctree::

gcloud/_helpers.py

@@ -22,6 +22,7 @@
 import os
 import re
 import socket
+import subprocess
 import sys
 from threading import local as Local
 
@@ -130,13 +131,13 @@ def _ensure_tuple_or_list(arg_name, tuple_or_list):
     This effectively reduces the iterable types allowed to a very short
     whitelist: list and tuple.
 
-    :type arg_name: string
+    :type arg_name: str
     :param arg_name: Name of argument to use in error message.
 
-    :type tuple_or_list: sequence of string
+    :type tuple_or_list: sequence of str
     :param tuple_or_list: Sequence to be verified.
 
-    :rtype: list of string
+    :rtype: list of str
     :returns: The ``tuple_or_list`` passed in cast to a ``list``.
     :raises: class:`TypeError` if the ``tuple_or_list`` is not a tuple or
              list.
@@ -150,7 +151,7 @@ def _ensure_tuple_or_list(arg_name, tuple_or_list):
 def _app_engine_id():
     """Gets the App Engine application ID if it can be inferred.
 
-    :rtype: string or ``NoneType``
+    :rtype: str or ``NoneType``
     :returns: App Engine application ID if running in App Engine,
               else ``None``.
     """
@@ -163,7 +164,7 @@ def _app_engine_id():
 def _file_project_id():
     """Gets the project id from the credentials file if one is available.
 
-    :rtype: string or ``NoneType``
+    :rtype: str or ``NoneType``
     :returns: Project-ID from JSON credentials file if value exists,
               else ``None``.
     """
@@ -177,6 +178,22 @@ def _file_project_id():
         return None
 
 
+def _default_service_project_id():
+    """Retrieves the project ID from the gcloud command line tool.
+
+    :rtype: str or ``NoneType``
+    :returns: Project-ID from ``gcloud info`` else ``None``
+    """
+    gcloud_project_conf = subprocess.check_output(['gcloud', 'info'])
+    gcloud_project_conf = gcloud_project_conf.split('\n')
+
+    for key in gcloud_project_conf:
+        if key.startswith('Project:'):
+            return key[10:-1]
+
+    return None
+
+
 def _compute_engine_id():
     """Gets the Compute Engine project ID if it can be inferred.
 
@@ -190,7 +207,7 @@ def _compute_engine_id():
     See https://github.com/google/oauth2client/issues/93 for context about
     DNS latency.
 
-    :rtype: string or ``NoneType``
+    :rtype: str or ``NoneType``
     :returns: Compute Engine project ID if the metadata service is available,
               else ``None``.
     """
@@ -223,14 +240,14 @@ def _determine_default_project(project=None):
 
     * GCLOUD_PROJECT environment variable
     * GOOGLE_APPLICATION_CREDENTIALS JSON file
-    * Get from oauth defaults
+    * Get from `gcloud auth login` defaults
     * Google App Engine application ID
     * Google Compute Engine project ID (from metadata server)
 
-    :type project: string
+    :type project: str
     :param project: Optional. The project name to use as default.
 
-    :rtype: string or ``NoneType``
+    :rtype: str or ``NoneType``
     :returns: Default project if it can be determined.
     """
     if project is None:
@@ -239,8 +256,8 @@ def _determine_default_project(project=None):
     if project is None:
         project = _file_project_id()
 
-    # if project is None:
-    #     print oauth2client.get_application_default()
+    if project is None:
+        project = _default_service_project_id()
 
     if project is None:
         project = _app_engine_id()
@@ -257,7 +274,7 @@ def _millis(when):
     :type when: :class:`datetime.datetime`
     :param when: the datetime to convert
 
-    :rtype: integer
+    :rtype: int
     :returns: milliseconds since epoch for ``when``
     """
     micros = _microseconds_from_datetime(when)
@@ -282,7 +299,7 @@ def _microseconds_from_datetime(value):
     :type value: :class:`datetime.datetime`
     :param value: The timestamp to convert.
 
-    :rtype: integer
+    :rtype: int
     :returns: The timestamp, in microseconds.
     """
     if not value.tzinfo:
@@ -299,7 +316,7 @@ def _millis_from_datetime(value):
     :type value: :class:`datetime.datetime`, or None
     :param value: the timestamp
 
-    :rtype: integer, or ``NoneType``
+    :rtype: int, or ``NoneType``
     :returns: the timestamp, in milliseconds, or None
     """
     if value is not None:
@@ -456,20 +473,20 @@ def _datetime_to_pb_timestamp(when):
 def _name_from_project_path(path, project, template):
     """Validate a URI path and get the leaf object's name.
 
-    :type path: string
+    :type path: str
     :param path: URI path containing the name.
 
-    :type project: string or NoneType
+    :type project: str or NoneType
     :param project: The project associated with the request. It is
                     included for validation purposes.  If passed as None,
                     disables validation.
 
-    :type template: string
+    :type template: str
     :param template: Template regex describing the expected form of the path.
                      The regex must have two named groups, 'project' and
                      'name'.
 
-    :rtype: string
+    :rtype: str
     :returns: Name parsed from ``path``.
     :raises: :class:`ValueError` if the ``path`` is ill-formed or if
              the project from the ``path`` does not agree with the

gcloud/test__helpers.py

@@ -183,6 +183,37 @@ def test_no_environment(self):
         self.assertEqual(None, self._callFUT())
 
 
+class Test__get_default_service_project_id(unittest2.TestCase):
+
+    def callFUT(self, project_result=''):
+        from gcloud._helpers import _default_service_project_id
+        import subprocess
+        self.check_output_called_with = []
+
+        def check_output_mock(called_with=None):
+            self.check_output_called_with = called_with
+            return project_result
+
+        from gcloud._testing import _Monkey
+        with _Monkey(subprocess, check_output=check_output_mock):
+            return _default_service_project_id(), self.check_output_called_with
+
+    def test_read_from_cli_info(self):
+        project_id, called_with = self.callFUT('Project: [test-project-id]')
+        self.assertEqual('test-project-id', project_id)
+        self.assertEqual(['gcloud', 'info'], called_with)
+
+    def test_cli_info_not_set(self):
+        project_id, called_with = self.callFUT()
+        self.assertEqual(None, project_id)
+        self.assertEqual(['gcloud', 'info'], called_with)
+
+    def test_info_value_not_present(self):
+        project_id, called_with = self.callFUT('Active Configuration')
+        self.assertEqual(None, project_id)
+        self.assertEqual(['gcloud', 'info'], called_with)
+
+
 class Test__compute_engine_id(unittest2.TestCase):
 
     def _callFUT(self):
@@ -254,7 +285,7 @@ def _callFUT(self, project=None):
         return _determine_default_project(project=project)
 
     def _determine_default_helper(self, prod=None, gae=None, gce=None,
-                                  project=None):
+                                  file_id=None, srv_id=None, project=None):
         from gcloud._testing import _Monkey
         from gcloud import _helpers
 
@@ -264,6 +295,14 @@ def prod_mock():
             _callers.append('prod_mock')
             return prod
 
+        def file_id_mock():
+            _callers.append('file_id_mock')
+            return file_id
+
+        def srv_id_mock():
+            _callers.append('srv_id_mock')
+            return srv_id
+
         def gae_mock():
             _callers.append('gae_mock')
             return gae
@@ -274,6 +313,8 @@ def gce_mock():
 
         patched_methods = {
             '_get_production_project': prod_mock,
+            '_file_project_id': file_id_mock,
+            '_default_service_project_id': srv_id_mock,
             '_app_engine_id': gae_mock,
             '_compute_engine_id': gce_mock,
         }
@@ -286,7 +327,8 @@ def gce_mock():
     def test_no_value(self):
         project, callers = self._determine_default_helper()
         self.assertEqual(project, None)
-        self.assertEqual(callers, ['prod_mock', 'gae_mock', 'gce_mock'])
+        self.assertEqual(callers, ['prod_mock', 'file_id_mock', 'srv_id_mock',
+                                   'gae_mock', 'gce_mock'])
 
     def test_explicit(self):
         PROJECT = object()
@@ -304,13 +346,15 @@ def test_gae(self):
         PROJECT = object()
         project, callers = self._determine_default_helper(gae=PROJECT)
         self.assertEqual(project, PROJECT)
-        self.assertEqual(callers, ['prod_mock', 'gae_mock'])
+        self.assertEqual(callers, ['prod_mock', 'file_id_mock',
+                                   'srv_id_mock', 'gae_mock'])
 
     def test_gce(self):
         PROJECT = object()
         project, callers = self._determine_default_helper(gce=PROJECT)
         self.assertEqual(project, PROJECT)
-        self.assertEqual(callers, ['prod_mock', 'gae_mock', 'gce_mock'])
+        self.assertEqual(callers, ['prod_mock', 'file_id_mock', 'srv_id_mock',
+                                   'gae_mock', 'gce_mock'])
 
 
 class Test__millis(unittest2.TestCase):