Skip to content

Commit eea013e

Browse files
dhermesdhermes
authored
Merge pull request #2187 from dhermes/language-impl-4
Updating language implementation after some review comments
2 parents 2a0586f + 23451b9 commit eea013e

7 files changed

Lines changed: 99 additions & 110 deletions

File tree

‎docs/language-usage.rst‎

Lines changed: 11 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,7 @@ Client
2323

2424
:class:`~gcloud.language.client.Client` objects provide a
2525
means to configure your application. Each instance holds
26-
both a ``project`` and an authenticated connection to the
27-
Natural Language service.
26+
an authenticated connection to the Natural Language service.
2827

2928
For an overview of authentication in ``gcloud-python``, see
3029
:doc:`gcloud-auth`.
@@ -37,13 +36,13 @@ create an instance of :class:`~gcloud.language.client.Client`.
3736
>>> from gcloud import language
3837
>>> client = language.Client()
3938
40-
By default the ``language`` is ``'en'`` and the ``encoding`` is
39+
By default the ``language`` is ``'en-US'`` and the ``encoding`` is
4140
UTF-8. To over-ride these values:
4241

4342
.. code-block:: python
4443
4544
>>> client = language.Client(language='es',
46-
... encoding=encoding=language.Encoding.UTF16)
45+
... encoding=language.Encoding.UTF16)
4746
4847
The encoding can be one of
4948
:attr:`Encoding.UTF8 <gcloud.language.document.Encoding.UTF8>`,
@@ -85,7 +84,7 @@ the client
8584
.. code-block:: python
8685
8786
>>> document.language
88-
'en'
87+
'en-US'
8988
>>> document.language == client.language
9089
True
9190
@@ -123,30 +122,24 @@ The document type (``doc_type``) value can be one of
123122

124123
In addition to supplying the text / HTML content, a document can refer
125124
to content stored in `Google Cloud Storage`_. We can use the
126-
:meth:`~gcloud.language.client.Client.document_from_blob` method:
125+
:meth:`~gcloud.language.client.Client.document_from_url` method:
127126

128127
.. code-block:: python
129128
130-
>>> document = client.document_from_blob('my-text-bucket',
131-
... 'sentiment-me.txt')
132-
>>> document.gcs_url
133-
'gs://my-text-bucket/sentiment-me.txt'
129+
>>> gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
130+
>>> document = client.document_from_url(
131+
... gcs_url, doc_type=language.Document.HTML)
132+
>>> document.gcs_url == gcs_url
133+
True
134134
>>> document.doc_type == language.Document.PLAIN_TEXT
135135
True
136136
137-
and the :meth:`~gcloud.language.client.Client.document_from_url`
138-
method. In either case, the document type can be specified with
139-
the ``doc_type`` argument:
137+
The document type can be specified with the ``doc_type`` argument:
140138

141139
.. code-block:: python
142140
143-
>>> gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
144141
>>> document = client.document_from_url(
145142
... gcs_url, doc_type=language.Document.HTML)
146-
>>> document.gcs_url == gcs_url
147-
True
148-
>>> document.doc_type == language.Document.HTML
149-
True
150143
151144
.. _analyzeEntities: https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeEntities
152145
.. _analyzeSentiment: https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeSentiment

‎gcloud/language/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@
1616

1717
from gcloud.language.client import Client
1818
from gcloud.language.document import Document
19+
from gcloud.language.document import Encoding

‎gcloud/language/client.py‎

Lines changed: 8 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,14 @@
1515
"""Basic client for Google Cloud Natural Language API."""
1616

1717

18-
from gcloud.client import JSONClient
18+
from gcloud import client as client_module
1919
from gcloud.language.connection import Connection
2020
from gcloud.language.document import Document
2121

2222

23-
class Client(JSONClient):
23+
class Client(client_module.Client):
2424
"""Client to bundle configuration needed for API requests.
2525
26-
:type project: str
27-
:param project: the project which the client acts on behalf of. If not
28-
passed, falls back to the default inferred from the
29-
environment.
30-
3126
:type credentials: :class:`~oauth2client.client.OAuth2Credentials`
3227
:param credentials: (Optional) The OAuth2 Credentials to use for the
3328
connection owned by this client. If not passed (and
@@ -50,9 +45,9 @@ def document_from_text(self, content, **kwargs):
5045
5146
:type kwargs: dict
5247
:param kwargs: Remaining keyword arguments to be passed along to the
53-
:class:`Document` constructor.
48+
:class:`.Document` constructor.
5449
55-
:rtype: :class:`Document`
50+
:rtype: :class:`.Document`
5651
:returns: A plain-text document bound to this client.
5752
:raises: :class:`~exceptions.TypeError` if ``doc_type`` is passed as a
5853
keyword argument.
@@ -70,9 +65,9 @@ def document_from_html(self, content, **kwargs):
7065
7166
:type kwargs: dict
7267
:param kwargs: Remaining keyword arguments to be passed along to the
73-
:class:`Document` constructor.
68+
:class:`.Document` constructor.
7469
75-
:rtype: :class:`Document`
70+
:rtype: :class:`.Document`
7671
:returns: An HTML document bound to this client.
7772
:raises: :class:`~exceptions.TypeError` if ``doc_type`` is passed as a
7873
keyword argument.
@@ -98,38 +93,9 @@ def document_from_url(self, gcs_url,
9893
9994
:type kwargs: dict
10095
:param kwargs: Remaining keyword arguments to be passed along to the
101-
:class:`Document` constructor.
96+
:class:`.Document` constructor.
10297
103-
:rtype: :class:`Document`
98+
:rtype: :class:`.Document`
10499
:returns: A document bound to this client.
105100
"""
106101
return Document(self, gcs_url=gcs_url, doc_type=doc_type, **kwargs)
107-
108-
def document_from_blob(self, bucket_name, blob_name,
109-
doc_type=Document.PLAIN_TEXT, **kwargs):
110-
"""Create a Cloud Storage document bound to this client.
111-
112-
:type bucket_name: str
113-
:param bucket_name: The name of the bucket that contains the
114-
document text.
115-
116-
:type blob_name: str
117-
:param blob_name: The name of the blob (within the bucket) that
118-
contains document text.
119-
120-
:type doc_type: str
121-
:param doc_type: (Optional) The type of text in the document.
122-
Defaults to plain text. Can also be specified
123-
as HTML via :attr:`~.Document.HTML`.
124-
125-
:type kwargs: dict
126-
:param kwargs: Remaining keyword arguments to be passed along to the
127-
:class:`Document` constructor.
128-
129-
:rtype: :class:`Document`
130-
:returns: A document bound to this client.
131-
"""
132-
# NOTE: We assume that the bucket and blob name don't
133-
# need to be URL-encoded.
134-
gcs_url = 'gs://%s/%s' % (bucket_name, blob_name)
135-
return self.document_from_url(gcs_url, doc_type=doc_type, **kwargs)

‎gcloud/language/document.py‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
from gcloud.language.entity import Entity
2121

2222

23-
DEFAULT_LANGUAGE = 'en'
23+
DEFAULT_LANGUAGE = 'en-US'
2424
"""Default document language, English."""
2525

2626

@@ -48,7 +48,7 @@ class Document(object):
4848
object.
4949
5050
:type client: :class:`~gcloud.language.client.Client`
51-
:param client: A client which holds credentials and project
51+
:param client: A client which holds credentials and other
5252
configuration.
5353
5454
:type content: str
@@ -129,12 +129,14 @@ def analyze_entities(self):
129129
in the text, entity types, salience, mentions for each entity, and
130130
other properties.
131131
132-
See:
133-
https://cloud.google.com/natural-language/reference/\
134-
rest/v1beta1/documents/analyzeEntities
132+
.. _analyzeEntities: https://cloud.google.com/natural-language/\
133+
reference/rest/v1beta1/documents/analyzeEntities
134+
135+
See `analyzeEntities`_.
135136
136137
:rtype: list
137-
:returns: A list of :class:`Entity` returned from the API.
138+
:returns: A list of :class:`~.language.entity.Entity` returned from
139+
the API.
138140
"""
139141
data = {
140142
'document': self._to_dict(),

‎gcloud/language/entity.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,16 +57,18 @@ class Entity(object):
5757
so this value will be removed from the passed in ``metadata``
5858
and put in its own property.
5959
60-
See:
61-
https://cloud.google.com/natural-language/reference/rest/v1beta1/Entity
60+
.. _Entity message: https://cloud.google.com/natural-language/\
61+
reference/rest/v1beta1/Entity
62+
.. _EntityType enum: https://cloud.google.com/natural-language/\
63+
reference/rest/v1beta1/Entity#Type
64+
65+
See `Entity message`_.
6266
6367
:type name: str
6468
:param name: The name / phrase identified as the entity.
6569
6670
:type entity_type: str
67-
:param entity_type: The type of the entity. See
68-
https://cloud.google.com/natural-language/\
69-
reference/rest/v1beta1/Entity#Type
71+
:param entity_type: The type of the entity. See `EntityType enum`_.
7072
7173
:type metadata: dict
7274
:param metadata: The metadata associated with the entity.

‎gcloud/language/test_client.py‎

Lines changed: 7 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,9 @@ def _makeOne(self, *args, **kw):
2727
def test_ctor(self):
2828
from gcloud.language.connection import Connection
2929

30-
project = 'PROJECT'
3130
creds = _Credentials()
3231
http = object()
33-
client = self._makeOne(project=project, credentials=creds, http=http)
32+
client = self._makeOne(credentials=creds, http=http)
3433
self.assertIsInstance(client.connection, Connection)
3534
self.assertTrue(client.connection.credentials is creds)
3635
self.assertTrue(client.connection.http is http)
@@ -39,8 +38,7 @@ def test_document_from_text_factory(self):
3938
from gcloud.language.document import Document
4039

4140
creds = _Credentials()
42-
client = self._makeOne(project='PROJECT',
43-
credentials=creds, http=object())
41+
client = self._makeOne(credentials=creds, http=object())
4442

4543
content = 'abc'
4644
language = 'es'
@@ -55,8 +53,7 @@ def test_document_from_text_factory(self):
5553

5654
def test_document_from_text_factory_failure(self):
5755
creds = _Credentials()
58-
client = self._makeOne(project='PROJECT',
59-
credentials=creds, http=object())
56+
client = self._makeOne(credentials=creds, http=object())
6057

6158
with self.assertRaises(TypeError):
6259
client.document_from_text('abc', doc_type='foo')
@@ -65,8 +62,7 @@ def test_document_from_html_factory(self):
6562
from gcloud.language.document import Document
6663

6764
creds = _Credentials()
68-
client = self._makeOne(project='PROJECT',
69-
credentials=creds, http=object())
65+
client = self._makeOne(credentials=creds, http=object())
7066

7167
content = '<html>abc</html>'
7268
language = 'ja'
@@ -81,8 +77,7 @@ def test_document_from_html_factory(self):
8177

8278
def test_document_from_html_factory_failure(self):
8379
creds = _Credentials()
84-
client = self._makeOne(project='PROJECT',
85-
credentials=creds, http=object())
80+
client = self._makeOne(credentials=creds, http=object())
8681

8782
with self.assertRaises(TypeError):
8883
client.document_from_html('abc', doc_type='foo')
@@ -91,8 +86,7 @@ def test_document_from_url_factory(self):
9186
from gcloud.language.document import Document
9287

9388
creds = _Credentials()
94-
client = self._makeOne(project='PROJECT',
95-
credentials=creds, http=object())
89+
client = self._makeOne(credentials=creds, http=object())
9690

9791
gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
9892
document = client.document_from_url(gcs_url)
@@ -107,8 +101,7 @@ def test_document_from_url_factory_explicit(self):
107101
from gcloud.language.document import Encoding
108102

109103
creds = _Credentials()
110-
client = self._makeOne(project='PROJECT',
111-
credentials=creds, http=object())
104+
client = self._makeOne(credentials=creds, http=object())
112105

113106
encoding = Encoding.UTF32
114107
gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
@@ -121,23 +114,6 @@ def test_document_from_url_factory_explicit(self):
121114
self.assertEqual(document.doc_type, Document.HTML)
122115
self.assertEqual(document.encoding, encoding)
123116

124-
def test_document_from_blob_factory(self):
125-
from gcloud.language.document import Document
126-
127-
creds = _Credentials()
128-
client = self._makeOne(project='PROJECT',
129-
credentials=creds, http=object())
130-
131-
bucket_name = 'my-text-bucket'
132-
blob_name = 'sentiment-me.txt'
133-
gcs_url = 'gs://%s/%s' % (bucket_name, blob_name)
134-
document = client.document_from_blob(bucket_name, blob_name)
135-
self.assertIsInstance(document, Document)
136-
self.assertIs(document.client, client)
137-
self.assertIsNone(document.content)
138-
self.assertEqual(document.gcs_url, gcs_url)
139-
self.assertEqual(document.doc_type, Document.PLAIN_TEXT)
140-
141117

142118
class _Credentials(object):
143119

0 commit comments

Comments
 (0)