Add client factories.

These factory classmethods generate credentials / connection from supplied values, paralleling the factories in 'gcloud.connection.Connection'.

Author: tseaver

docs/pubsub-usage.rst

@@ -282,16 +282,14 @@ Create a client using the defaults from the environment:
  >>> from gcloud.pubsub.client import Client
  >>> client = Client()
 
-Create a client using an explicit connection, but the default project:
+Create a client using explicit credentials, but the default project:
 
 .. doctest::
 
  >>> from gcloud.pubsub.client import Client
- >>> from gcloud.pubsub.connection import Connection
- >>> connection = Connection.from_service_account_json('/path/to/creds.json')
- >>> client = Client(connection=connection)
+ >>> client = Client.from_service_account_json('/path/to/creds.json')
 
-Create a client using an explicit project ID, but the connetion inferred
+Create a client using an explicit project ID, but the credentials inferred
 from the environment:
 
 .. doctest::

gcloud/pubsub/client.py

@@ -23,6 +23,7 @@
 from gcloud._helpers import _ClientProxy
 from gcloud.pubsub._implicit_environ import _require_connection
 from gcloud.pubsub import api
+from gcloud.pubsub.connection import Connection
 from gcloud.pubsub.subscription import Subscription
 from gcloud.pubsub.topic import Topic
 
@@ -35,8 +36,8 @@ class Client(object):
  from the environment.
 
  :type project: str or None
- :param connection: The configured project. Defaults to the value inferred
-  from the environment.
+ :param project: The configured project. Defaults to the value inferred
+ from the environment.
  """
 
  def __init__(self, connection=None, project=None):
@@ -45,6 +46,73 @@ def __init__(self, connection=None, project=None):
  project = get_default_project()
  self.project = project
 
+ @classmethod
+ def from_service_account_json(cls, json_credentials_path, project=None,
+ *args, **kwargs):
+ """Factory to retrieve JSON credentials while creating connection.
+
+ :type json_credentials_path: string
+ :param json_credentials_path: The path to a private key file (this file
+ was given to you when you created the
+ service account). This file must contain
+ a JSON object with a private key and
+ other credentials information (downloaded
+ from the Google APIs console).
+
+ :type project: str or None
+ :param project: The configured project. Defaults to the value inferred
+ from the environment.
+
+ :rtype: :class:`gcloud.pubsub.client.Client`
+ :returns: A client, configured with a connection created with the
+ retrieved JSON credentials, and the supplied project.
+ """
+ connection = Connection.from_service_account_json(
+ json_credentials_path, *args, **kwargs)
+ return cls(connection=connection, project=project)
+
+ @classmethod
+ def from_service_account_p12(cls, client_email, private_key_path,
+ project=None, *args, **kwargs):
+ """Factory to retrieve P12 credentials while creating connection.
+
+ .. note::
+ Unless you have an explicit reason to use a PKCS12 key for your
+ service account, we recommend using a JSON key.
+
+ :type client_email: string
+ :param client_email: The e-mail attached to the service account.
+
+ :type private_key_path: string
+ :param private_key_path: The path to a private key file (this file was
+ given to you when you created the service
+ account). This file must be in P12 format.
+
+ :type project: str or None
+ :param project: The configured project. Defaults to the value inferred
+ from the environment.
+
+ :rtype: :class:`gcloud.pubsub.client.Client`
+ :returns: A client, configured with a connection created with the
+ retrieved P12 credentials, and the supplied project.
+ """
+ connection = Connection.from_service_account_p12(
+ client_email, private_key_path, *args, **kwargs)
+ return cls(connection=connection, project=project)
+
+ @classmethod
+ def from_environment(cls, project=None, *args, **kwargs):
+ """Factory to retrieve implicit credentials while creating connection.
+
+ :rtype: :class:`gcloud.pubsub.client.Client`
+ :returns: The connection created with the retrieved implicit
+ credentials.
+ :returns: A client, configured with a connection created with the
+ retrieved implicit credentials, and the supplied project
+ """
+ connection = Connection.from_environment(*args, **kwargs)
+ return cls(connection=connection, project=project)
+
  def topic(self, name):
  """Proxy for :class:`gcloud.pubsub.topic.Topic`.
 

gcloud/pubsub/test_client.py

@@ -42,6 +42,73 @@ def test_ctor_explicit(self):
  self.assertTrue(client.connection is connection)
  self.assertEqual(client.project, PROJECT)
 
+ def test_from_service_account_json(self):
+ from gcloud._testing import _Monkey
+ from gcloud import connection
+
+ PROJECT = 'PROJECT'
+ KLASS = self._getTargetClass()
+ CREDS = _Credentials()
+
+ _called = []
+
+ def mock_creds(*args):
+ _called.append(args)
+ return CREDS
+
+ JSON_CREDS_PATH = '/path/to/credentials.json'
+ with _Monkey(connection, get_for_service_account_json=mock_creds):
+ client = KLASS.from_service_account_json(JSON_CREDS_PATH, PROJECT)
+
+ self.assertTrue(client.connection.credentials is CREDS)
+ self.assertEqual(_called, [(JSON_CREDS_PATH,)])
+ self.assertEqual(client.project, PROJECT)
+
+ def test_from_service_account_p12(self):
+ from gcloud._testing import _Monkey
+ from gcloud import connection
+
+ PROJECT = 'PROJECT'
+ KLASS = self._getTargetClass()
+ CREDS = _Credentials()
+
+ _called = []
+
+ def mock_creds(*args):
+ _called.append(args)
+ return CREDS
+
+ CLIENT_EMAIL = 'client@example.com'
+ P12_PRIVKEY_PATH = '/path/to/privkey.p12'
+ with _Monkey(connection, get_for_service_account_p12=mock_creds):
+ client = KLASS.from_service_account_p12(
+ CLIENT_EMAIL, P12_PRIVKEY_PATH, PROJECT)
+
+ self.assertTrue(client.connection.credentials is CREDS)
+ self.assertEqual(_called, [(CLIENT_EMAIL, P12_PRIVKEY_PATH,)])
+ self.assertEqual(client.project, PROJECT)
+
+ def test_from_environment(self):
+ from gcloud._testing import _Monkey
+ from gcloud import connection
+
+ PROJECT = 'PROJECT'
+ KLASS = self._getTargetClass()
+ CREDS = _Credentials()
+
+ _called = []
+
+ def mock_creds(*args):
+ _called.append(args)
+ return CREDS
+
+ with _Monkey(connection, get_credentials=mock_creds):
+ client = KLASS.from_environment(PROJECT)
+
+ self.assertTrue(client.connection.credentials is CREDS)
+ self.assertEqual(_called, [()])
+ self.assertEqual(client.project, PROJECT)
+
  def test_topic(self):
  from gcloud.pubsub.client import _Topic
  from gcloud.pubsub.topic import Topic
@@ -224,3 +291,9 @@ class _Dummy(object):
 
  def __init__(self, **kw):
  self.__dict__.update(kw)
+
+
+class _Credentials(object):
+
+ def create_scoped_required(self):
+ return False