gcloud 0.7.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,248 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "gcloud/translate/connection"
17
+ require "gcloud/translate/translation"
18
+ require "gcloud/translate/detection"
19
+ require "gcloud/translate/language"
20
+ require "gcloud/translate/errors"
21
+
22
+ module Gcloud
23
+ module Translate
24
+ ##
25
+ # # Api
26
+ #
27
+ # Represents top-level access to the Google Translate API. Each instance
28
+ # requires a public API access key. To create a key, follow the general
29
+ # instructions at [Identifying your application to
30
+ # Google](https://cloud.google.com/translate/v2/using_rest#auth), and the
31
+ # specific instructions for [Server
32
+ # keys](https://cloud.google.com/translate/v2/using_rest#creating-server-api-keys).
33
+ # See {Gcloud#translate}.
34
+ #
35
+ # @see https://cloud.google.com/translate/v2/getting_started Translate API
36
+ # Getting Started
37
+ #
38
+ # @example
39
+ # require "gcloud"
40
+ #
41
+ # gcloud = Gcloud.new
42
+ # translate = gcloud.translate
43
+ #
44
+ # translation = translate.translate "Hello world!", to: "la"
45
+ #
46
+ # puts translation #=> Salve mundi!
47
+ #
48
+ # translation.from #=> "en"
49
+ # translation.origin #=> "Hello world!"
50
+ # translation.to #=> "la"
51
+ # translation.text #=> "Salve mundi!"
52
+ #
53
+ class Api
54
+ ##
55
+ # @private The Connection object.
56
+ attr_accessor :connection
57
+
58
+ ##
59
+ # @private Creates a new Translate Api instance.
60
+ #
61
+ # See {Gcloud.translate}
62
+ def initialize key
63
+ key ||= ENV["TRANSLATE_KEY"]
64
+ if key.nil?
65
+ key_mising_msg = "An API key is required to use the Translate API."
66
+ fail ArgumentError, key_mising_msg
67
+ end
68
+ @connection = Connection.new key
69
+ end
70
+
71
+ ##
72
+ # Returns text translations from one language to another.
73
+ #
74
+ # @see https://cloud.google.com/translate/v2/using_rest#Translate
75
+ # Translate Text
76
+ #
77
+ # @param [String] text The text or texts to translate.
78
+ # @param [String] to The target language into which the text should be
79
+ # translated. This is required. The value must be an [ISO
80
+ # 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language
81
+ # code.
82
+ # @param [String] from The source language of the text or texts. This is
83
+ # an [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
84
+ # language code. This is optional.
85
+ # @param [String] format The format of the text. Possible values include
86
+ # `:text` and `:html`. This is optional. The Translate API default is
87
+ # `:html`.
88
+ # @param [String] cid The customization id for translate. This is
89
+ # optional.
90
+ #
91
+ # @return [Translation, Array<Translation>] A single {Translation} object
92
+ # if just one text was given, or an array of {Translation} objects if
93
+ # multiple texts were given.
94
+ #
95
+ # @example
96
+ # require "gcloud"
97
+ #
98
+ # gcloud = Gcloud.new
99
+ # translate = gcloud.translate
100
+ #
101
+ # translation = translate.translate "Hello world!", to: "la"
102
+ #
103
+ # puts translation #=> Salve mundi!
104
+ #
105
+ # translation.detected? #=> true
106
+ # translation.from #=> "en"
107
+ # translation.origin #=> "Hello world!"
108
+ # translation.to #=> "la"
109
+ # translation.text #=> "Salve mundi!"
110
+ #
111
+ # @example Setting the `from` language.
112
+ # require "gcloud"
113
+ #
114
+ # gcloud = Gcloud.new
115
+ # translate = gcloud.translate
116
+ #
117
+ # translation = translate.translate "Hello world!",
118
+ # from: :en, to: :la
119
+ # translation.detected? #=> false
120
+ # translation.text #=> "Salve mundi!"
121
+ #
122
+ # @example Retrieving multiple translations.
123
+ # require "gcloud"
124
+ #
125
+ # gcloud = Gcloud.new
126
+ # translate = gcloud.translate
127
+ #
128
+ # translations = translate.translate "Hello my friend.",
129
+ # "See you soon.",
130
+ # from: "en", to: "la"
131
+ # translations.count #=> 2
132
+ # translations[0].text #=> "Salve amice."
133
+ # translations[1].text #=> "Vide te mox."
134
+ #
135
+ # @example Preserving HTML tags.
136
+ # require "gcloud"
137
+ #
138
+ # gcloud = Gcloud.new
139
+ # translate = gcloud.translate
140
+ #
141
+ # translation = translate.translate "<strong>Hello</strong> world!",
142
+ # to: :la
143
+ # translation.text #=> "<strong>Salve</strong> mundi!"
144
+ #
145
+ def translate *text, to: nil, from: nil, format: nil, cid: nil
146
+ return nil if text.empty?
147
+ fail ArgumentError, "to is required" if to.nil?
148
+ to = to.to_s
149
+ from = from.to_s if from
150
+ format = format.to_s if format
151
+ resp = connection.translate(*text, to: to, from: from,
152
+ format: format, cid: cid)
153
+ fail ApiError.from_response(resp) unless resp.success?
154
+ Translation.from_response resp, text, to, from
155
+ end
156
+
157
+ ##
158
+ # Detect the most likely language or languages of a text or multiple
159
+ # texts.
160
+ #
161
+ # @see https://cloud.google.com/translate/v2/using_rest#detect-language
162
+ # Detect Language
163
+ #
164
+ # @param [String] text The text or texts upon which language detection
165
+ # should be performed.
166
+ #
167
+ # @return [Detection, Array<Detection>] A single {Detection} object if
168
+ # just one text was given, or an array of {Detection} objects if
169
+ # multiple texts were given.
170
+ #
171
+ # @example
172
+ # require "gcloud"
173
+ #
174
+ # gcloud = Gcloud.new
175
+ # translate = gcloud.translate
176
+ #
177
+ # detection = translate.detect "Hello world!"
178
+ # puts detection.language #=> en
179
+ # puts detection.confidence #=> 0.7100697
180
+ #
181
+ # @example Detecting multiple texts.
182
+ # require "gcloud"
183
+ #
184
+ # gcloud = Gcloud.new
185
+ # translate = gcloud.translate
186
+ #
187
+ # detections = translate.detect "Hello world!",
188
+ # "Bonjour le monde!"
189
+ # puts detections.count #=> 2
190
+ # puts detection.first.language #=> en
191
+ # puts detection.first.confidence #=> 0.7100697
192
+ # puts detection.last.language #=> fr
193
+ # puts detection.last.confidence #=> 0.40440267
194
+ #
195
+ def detect *text
196
+ return nil if text.empty?
197
+ resp = connection.detect(*text)
198
+ fail ApiError.from_response(resp) unless resp.success?
199
+ Detection.from_response resp, text
200
+ end
201
+
202
+ ##
203
+ # List the languages supported by the API. These are the languages to and
204
+ # from which text can be translated.
205
+ #
206
+ # @see https://cloud.google.com/translate/v2/using_rest#supported-languages
207
+ # Discover Supported Languages
208
+ #
209
+ # @param [String] language The language and collation in which the names
210
+ # of the languages are returned. If this is `nil` then no names are
211
+ # returned.
212
+ #
213
+ # @return [Array<Language>] An array of {Language} objects supported by
214
+ # the API.
215
+ #
216
+ # @example
217
+ # require "gcloud"
218
+ #
219
+ # gcloud = Gcloud.new
220
+ # translate = gcloud.translate
221
+ #
222
+ # languages = translate.languages
223
+ # languages.count #=> 104
224
+ #
225
+ # english = languages.detect { |l| l.code == "en" }
226
+ # english.name #=> nil
227
+ #
228
+ # @example Get all languages with their names in French.
229
+ # require "gcloud"
230
+ #
231
+ # gcloud = Gcloud.new
232
+ # translate = gcloud.translate
233
+ #
234
+ # languages = translate.languages "fr"
235
+ # languages.count #=> 104
236
+ #
237
+ # english = languages.detect { |l| l.code == "en" }
238
+ # english.name #=> "Anglais"
239
+ #
240
+ def languages language = nil
241
+ language = language.to_s if language
242
+ resp = connection.languages language
243
+ fail ApiError.from_response(resp) unless resp.success?
244
+ Array(resp.data["languages"]).map { |gapi| Language.from_gapi gapi }
245
+ end
246
+ end
247
+ end
248
+ end
@@ -0,0 +1,76 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "gcloud/version"
17
+ require "google/api_client"
18
+
19
+ module Gcloud
20
+ module Translate
21
+ ##
22
+ # @private Represents the connection to Translate, as well as expose the API
23
+ # calls
24
+ class Connection
25
+ API_VERSION = "v2"
26
+
27
+ attr_accessor :client
28
+
29
+ ##
30
+ # Creates a new Connection instance.
31
+ def initialize key
32
+ @client = Google::APIClient.new application_name: "gcloud-ruby",
33
+ application_version: Gcloud::VERSION,
34
+ authorization: nil
35
+ @translate = @client.discovered_api "translate", API_VERSION
36
+ @client.key = key # set key after discovery, helps with tests
37
+ end
38
+
39
+ def translate *text, to: nil, from: nil, format: nil, cid: nil
40
+ params = { q: text,
41
+ target: to,
42
+ source: from,
43
+ format: format,
44
+ cid: cid,
45
+ prettyprint: false
46
+ }.delete_if { |_, v| v.nil? }
47
+
48
+ @client.execute(
49
+ api_method: @translate.translations.list,
50
+ parameters: params
51
+ )
52
+ end
53
+
54
+ def detect *text
55
+ @client.execute(
56
+ api_method: @translate.detections.list,
57
+ parameters: { q: text, prettyprint: false }
58
+ )
59
+ end
60
+
61
+ def languages language = nil
62
+ params = { target: language,
63
+ prettyprint: false }.delete_if { |_, v| v.nil? }
64
+
65
+ @client.execute(
66
+ api_method: @translate.languages.list,
67
+ parameters: params
68
+ )
69
+ end
70
+
71
+ def inspect
72
+ "#{self.class}(#{@project})"
73
+ end
74
+ end
75
+ end
76
+ end
@@ -0,0 +1,137 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ module Gcloud
17
+ module Translate
18
+ ##
19
+ # # Detection
20
+ #
21
+ # Represents a detect language query result. Returned by
22
+ # {Gcloud::Translate::Api#detect}.
23
+ #
24
+ # @see https://cloud.google.com/translate/v2/using_rest#detect-language
25
+ # Detect Language
26
+ #
27
+ # @example
28
+ # require "gcloud"
29
+ #
30
+ # gcloud = Gcloud.new
31
+ # translate = gcloud.translate
32
+ #
33
+ # detections = translate.detect "chien", "chat"
34
+ #
35
+ # detections.size #=> 2
36
+ # detections[0].text #=> "chien"
37
+ # detections[0].language #=> "fr"
38
+ # detections[0].confidence #=> 0.7109375
39
+ # detections[1].text #=> "chat"
40
+ # detections[1].language #=> "en"
41
+ # detections[1].confidence #=> 0.59922177
42
+ #
43
+ class Detection
44
+ ##
45
+ # The text upon which the language detection was performed.
46
+ #
47
+ # @return [String]
48
+ attr_reader :text
49
+
50
+ ##
51
+ # The list of detection results for the given text. The most likely
52
+ # language is listed first, and its attributes can be accessed through
53
+ # {#language} and {#confidence}.
54
+ #
55
+ # @return [Array<Detection::Result>]
56
+ attr_reader :results
57
+
58
+ ##
59
+ # @private Create a new object.
60
+ def initialize text, results
61
+ @text = text
62
+ @results = results
63
+ end
64
+
65
+ ##
66
+ # The confidence that the language detection result is correct. The closer
67
+ # this value is to 1, the higher the confidence in language detection.
68
+ #
69
+ # @return [Float] a value between 0 and 1
70
+ def confidence
71
+ return nil if results.empty?
72
+ results.first.confidence
73
+ end
74
+
75
+ ##
76
+ # The most likely language that was detected. This is an [ISO
77
+ # 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language
78
+ # code.
79
+ #
80
+ # @return [String] the language code
81
+ def language
82
+ return nil if results.empty?
83
+ results.first.language
84
+ end
85
+
86
+ ##
87
+ # @private New Detection from a DetectionsListResponse object as
88
+ # defined by the Google API Client object.
89
+ def self.from_response resp, text
90
+ res = text.zip(Array(resp.data.detections)).map do |txt, gapi_list|
91
+ results = gapi_list.map { |gapi| Result.from_gapi gapi }
92
+ new txt, results
93
+ end
94
+ return res.first if res.size == 1
95
+ res
96
+ end
97
+
98
+ ##
99
+ # # Result
100
+ #
101
+ # Represents an individual result in a {Gcloud::Translate::Detection}
102
+ # result.
103
+ #
104
+ class Result
105
+ ##
106
+ # The confidence that the language detection result is correct. The
107
+ # closer this value is to 1, the higher the confidence in language
108
+ # detection.
109
+ #
110
+ # @return [Float] a value between 0 and 1
111
+ attr_reader :confidence
112
+
113
+ ##
114
+ # The language detected. This is an [ISO
115
+ # 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language
116
+ # code.
117
+ #
118
+ # @return [String] the language code
119
+ attr_reader :language
120
+
121
+ ##
122
+ # @private Create a new object.
123
+ def initialize confidence, language
124
+ @confidence = confidence
125
+ @language = language
126
+ end
127
+
128
+ ##
129
+ # @private New Detection::Result from a DetectionsResource object as
130
+ # defined by the Google API Client object.
131
+ def self.from_gapi gapi
132
+ new gapi["confidence"], gapi["language"]
133
+ end
134
+ end
135
+ end
136
+ end
137
+ end