Rename document_from_url to document_from_gcs_url. (#2986)

This does a rename requested by the NL team.

language/google/cloud/language/client.py

@@ -14,6 +14,8 @@
 
 """Basic client for Google Cloud Natural Language API."""
 
+import functools
+import warnings
 
 from google.cloud import client as client_module
 from google.cloud.language.connection import Connection
@@ -87,8 +89,8 @@ def document_from_html(self, content, **kwargs):
         return Document(self, content=content,
                         doc_type=Document.HTML, **kwargs)
 
-    def document_from_url(self, gcs_url,
-                          doc_type=Document.PLAIN_TEXT, **kwargs):
+    def document_from_gcs_url(self, gcs_url,
+                              doc_type=Document.PLAIN_TEXT, **kwargs):
         """Create a Cloud Storage document bound to this client.
 
         :type gcs_url: str
@@ -110,3 +112,13 @@ def document_from_url(self, gcs_url,
         :returns: A document bound to this client.
         """
         return Document(self, gcs_url=gcs_url, doc_type=doc_type, **kwargs)
+
+    @functools.wraps(document_from_gcs_url)
+    def document_from_url(self, *args, **kwargs):
+        """Deprecated equivalent to document_from_gcs_url.
+
+        DEPRECATED: 2017-02-06
+        """
+        warnings.warn('The `document_from_url` method is deprecated; use '
+                      '`document_from_gcs_url` instead.', DeprecationWarning)
+        return self.document_from_gcs_url(*args, **kwargs)

language/unit_tests/test_client.py

@@ -14,9 +14,10 @@
 
 import unittest
 
+import mock
+
 
 def make_mock_credentials():
-    import mock
     from google.auth import credentials
 
     credentials = mock.Mock(spec=credentials.Credentials)
@@ -92,21 +93,21 @@ def test_document_from_html_factory_failure(self):
         with self.assertRaises(TypeError):
             client.document_from_html('abc', doc_type='foo')
 
-    def test_document_from_url_factory(self):
+    def test_document_from_gcs_url_factory(self):
         from google.cloud.language.document import Document
 
         creds = make_mock_credentials()
         client = self._make_one(credentials=creds, http=object())
 
         gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
-        document = client.document_from_url(gcs_url)
+        document = client.document_from_gcs_url(gcs_url)
         self.assertIsInstance(document, Document)
         self.assertIs(document.client, client)
         self.assertIsNone(document.content)
         self.assertEqual(document.gcs_url, gcs_url)
         self.assertEqual(document.doc_type, Document.PLAIN_TEXT)
 
-    def test_document_from_url_factory_explicit(self):
+    def test_document_from_gcs_url_factory_explicit(self):
         from google.cloud.language.document import Document
         from google.cloud.language.document import Encoding
 
@@ -115,11 +116,31 @@ def test_document_from_url_factory_explicit(self):
 
         encoding = Encoding.UTF32
         gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
-        document = client.document_from_url(gcs_url, doc_type=Document.HTML,
-                                            encoding=encoding)
+        document = client.document_from_gcs_url(gcs_url,
+                                                doc_type=Document.HTML,
+                                                encoding=encoding)
         self.assertIsInstance(document, Document)
         self.assertIs(document.client, client)
         self.assertIsNone(document.content)
         self.assertEqual(document.gcs_url, gcs_url)
         self.assertEqual(document.doc_type, Document.HTML)
         self.assertEqual(document.encoding, encoding)
+
+    def test_document_from_url_deprecation(self):
+        import warnings
+
+        creds = make_mock_credentials()
+        client = self._make_one(credentials=creds, http=object())
+
+        Client = self._get_target_class()
+        with mock.patch.object(Client, 'document_from_gcs_url') as dfgu:
+            with mock.patch.object(warnings, 'warn') as warn:
+                client.document_from_url(gcs_url='gs://bogus')
+
+                # Establish that the warning happened and sent a
+                # DeprecationWarning.
+                self.assertEqual(warn.call_count, 1)
+                self.assertEqual(warn.mock_calls[0][1][1], DeprecationWarning)
+
+                # Establish that the new (renamed) method is called.
+                dfgu.assert_called_once_with(gcs_url='gs://bogus')