Renaming project -> new_project and implementing fetch_project.

This is to make the distinction clear between a Resource Manager
API request and object creation.

docs/resource-manager-api.rst

@@ -28,8 +28,8 @@ Here's a quick example of the full life-cycle:
     ...     print(project)
 
     >>> # Create a new project
-    >>> new_project = client.project('your-project-id-here',
-    ...                              name='My new project)
+    >>> new_project = client.new_project('your-project-id-here',
+    ...                                  name='My new project)
     >>> new_project.create()
 
     >>> # Update an existing project

gcloud/resource_manager/client.py

@@ -78,7 +78,7 @@ def from_service_account_p12(cls, *args, **kwargs):
                                   'Resource Manager API. Only user '
                                   'credentials can be used.')
 
-    def project(self, project_id, name=None, labels=None):
+    def new_project(self, project_id, name=None, labels=None):
         """Creates a :class:`.Project` bound to the current client.
 
         Use :meth:`Project.reload() \
@@ -105,6 +105,24 @@ def project(self, project_id, name=None, labels=None):
         return Project(project_id=project_id,
                        client=self, name=name, labels=labels)
 
+    def fetch_project(self, project_id):
+        """Get an existing project by ID.
+
+        .. note::
+
+            If the project does not exist, this will raise a
+            :class:`NotFound <gcloud.exceptions.NotFound>` error.
+
+        :type project_id: str
+        :param project_id: The ID for this project.
+
+        :rtype: :class:`.Project`
+        :returns: A :class:`.Project` with metadata fetched from the API.
+        """
+        project = self.new_project(project_id)
+        project.reload()
+        return project
+
     def list_projects(self, filter_params=None, page_size=None):
         """List the projects visible to this client.
 

gcloud/resource_manager/project.py

@@ -24,14 +24,14 @@ class Project(object):
     .. note::
 
         A :class:`Project` can also be created via
-        :meth:`Client.project() \
-        <gcloud.resource_manager.client.Client.project>`
+        :meth:`Client.new_project() \
+        <gcloud.resource_manager.client.Client.new_project>`
 
     To manage labels on a :class:`Project`::
 
         >>> from gcloud import resource_manager
         >>> client = resource_manager.Client()
-        >>> project = client.project('purple-spaceship-123')
+        >>> project = client.new_project('purple-spaceship-123')
         >>> project.labels = {'color': 'purple'}
         >>> project.labels['environment'] = 'production'
         >>> project.update()
@@ -139,9 +139,9 @@ def reload(self, client=None):
 
         This method will reload the newest metadata for the project. If you've
         created a new :class:`Project` instance via
-        :meth:`Client.project() \
-        <gcloud.resource_manager.client.Client.project>`, this method will
-        retrieve project metadata.
+        :meth:`Client.new_project() \
+        <gcloud.resource_manager.client.Client.new_project>`,
+        this method will retrieve project metadata.
 
         .. warning::
 

gcloud/resource_manager/test_client.py

@@ -98,22 +98,49 @@ def test_from_service_account_p12_factory(self):
         with self.assertRaises(NotImplementedError):
             klass.from_service_account_p12()
 
-    def test_project_factory(self):
+    def test_new_project_factory(self):
         from gcloud.resource_manager.project import Project
 
         credentials = _Credentials()
         client = self._makeOne(credentials=credentials)
         project_id = 'project_id'
         name = object()
         labels = object()
-        project = client.project(project_id, name=name, labels=labels)
+        project = client.new_project(project_id, name=name, labels=labels)
 
         self.assertTrue(isinstance(project, Project))
         self.assertEqual(project._client, client)
         self.assertEqual(project.project_id, project_id)
         self.assertEqual(project.name, name)
         self.assertEqual(project.labels, labels)
 
+    def test_fetch_project(self):
+        from gcloud.resource_manager.project import Project
+
+        project_id = 'project-id'
+        project_number = 123
+        project_name = 'Project Name'
+        labels = {'env': 'prod'}
+        project_resource = {
+            'projectId': project_id,
+            'projectNumber': project_number,
+            'name': project_name,
+            'labels': labels,
+            'lifecycleState': 'ACTIVE',
+        }
+
+        credentials = _Credentials()
+        client = self._makeOne(credentials=credentials)
+        # Patch the connection with one we can easily control.
+        client.connection = _Connection(project_resource)
+
+        project = client.fetch_project(project_id)
+        self.assertTrue(isinstance(project, Project))
+        self.assertEqual(project._client, client)
+        self.assertEqual(project.project_id, project_id)
+        self.assertEqual(project.name, project_name)
+        self.assertEqual(project.labels, labels)
+
     def test_list_projects_return_type(self):
         from gcloud.resource_manager.client import _ProjectIterator