diff --git a/language/google/cloud/language/client.py b/language/google/cloud/language/client.py index d788c9b3d62d..4c8380eba2fc 100644 --- a/language/google/cloud/language/client.py +++ b/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) diff --git a/language/unit_tests/test_client.py b/language/unit_tests/test_client.py index 56b6aa22b235..ee5b61f3ea86 100644 --- a/language/unit_tests/test_client.py +++ b/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')