0
# Client Management
1

2
Core client classes for interacting with the Google Cloud Natural Language API. The library provides both synchronous and asynchronous clients with configurable transport layers, authentication options, and error handling.
3

4
## Capabilities
5

6
### Synchronous Client
7

8
The primary client class for making synchronous API calls to Google Cloud Natural Language service.
9

10
```python { .api }
11
class LanguageServiceClient:
12
    def __init__(
13
        self,
14
        *,
15
        credentials: ga_credentials.Credentials = None,
16
        transport: Union[str, LanguageServiceTransport] = None,
17
        client_options: Union[client_options_lib.ClientOptions, dict] = None,
18
        client_info: gapic_v1.client_info.ClientInfo = None,
19
    ):
20
        """
21
        Instantiates the language service client.
22
        
23
        Args:
24
            credentials: The credentials to use for authentication
25
            transport: Transport to use for communication ('grpc', 'rest', or transport instance)
26
            client_options: Custom options for the client
27
            client_info: Client information for user agent
28
        """
29
```
30

31
#### Usage Example
32

33
```python
34
from google.cloud import language
35
from google.oauth2 import service_account
36

37
# Initialize with default credentials
38
client = language.LanguageServiceClient()
39

40
# Initialize with service account credentials
41
credentials = service_account.Credentials.from_service_account_file(
42
    "path/to/service-account-key.json"
43
)
44
client = language.LanguageServiceClient(credentials=credentials)
45

46
# Initialize with custom transport
47
client = language.LanguageServiceClient(transport='rest')
48
```
49

50
### Asynchronous Client
51

52
Asynchronous client for non-blocking API calls using async/await patterns.
53

54
```python { .api }
55
class LanguageServiceAsyncClient:
56
    def __init__(
57
        self,
58
        *,
59
        credentials: ga_credentials.Credentials = None,
60
        transport: Union[str, LanguageServiceAsyncTransport] = None,
61
        client_options: Union[client_options_lib.ClientOptions, dict] = None,
62
        client_info: gapic_v1.client_info.ClientInfo = None,
63
    ):
64
        """
65
        Instantiates the asynchronous language service client.
66
        
67
        Args:
68
            credentials: The credentials to use for authentication
69
            transport: Transport to use for communication ('grpc_asyncio' or transport instance)
70
            client_options: Custom options for the client
71
            client_info: Client information for user agent
72
        """
73
```
74

75
#### Async Methods
76

77
All client methods are available in async versions:
78

79
```python { .api }
80
async def analyze_sentiment(
81
    self,
82
    request: Optional[Union[AnalyzeSentimentRequest, dict]] = None,
83
    *,
84
    document: Optional[Document] = None,
85
    encoding_type: Optional[EncodingType] = None,
86
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
87
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
88
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
89
) -> AnalyzeSentimentResponse: ...
90

91
async def analyze_entities(
92
    self,
93
    request: Optional[Union[AnalyzeEntitiesRequest, dict]] = None,
94
    *,
95
    document: Optional[Document] = None,
96
    encoding_type: Optional[EncodingType] = None,
97
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
98
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
99
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
100
) -> AnalyzeEntitiesResponse: ...
101

102
async def classify_text(
103
    self,
104
    request: Optional[Union[ClassifyTextRequest, dict]] = None,
105
    *,
106
    document: Optional[Document] = None,
107
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
108
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
109
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
110
) -> ClassifyTextResponse: ...
111

112
async def moderate_text(
113
    self,
114
    request: Optional[Union[ModerateTextRequest, dict]] = None,
115
    *,
116
    document: Optional[Document] = None,
117
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
118
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
119
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
120
) -> ModerateTextResponse: ...
121

122
async def annotate_text(
123
    self,
124
    request: Optional[Union[AnnotateTextRequest, dict]] = None,
125
    *,
126
    document: Optional[Document] = None,
127
    features: Optional[AnnotateTextRequest.Features] = None,
128
    encoding_type: Optional[EncodingType] = None,
129
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
130
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
131
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
132
) -> AnnotateTextResponse: ...
133
```
134

135
#### Additional Async Methods (v1/v1beta2 only)
136

137
```python { .api }
138
async def analyze_entity_sentiment(
139
    self,
140
    request: Optional[Union[AnalyzeEntitySentimentRequest, dict]] = None,
141
    *,
142
    document: Optional[Document] = None,
143
    encoding_type: Optional[EncodingType] = None,
144
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
145
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
146
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
147
) -> AnalyzeEntitySentimentResponse: ...
148

149
async def analyze_syntax(
150
    self,
151
    request: Optional[Union[AnalyzeSyntaxRequest, dict]] = None,
152
    *,
153
    document: Optional[Document] = None,
154
    encoding_type: Optional[EncodingType] = None,
155
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
156
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
157
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
158
) -> AnalyzeSyntaxResponse: ...
159
```
160

161
#### Usage Example
162

163
```python
164
import asyncio
165
from google.cloud import language
166

167
async def main():
168
    # Initialize async client
169
    client = language.LanguageServiceAsyncClient()
170
    
171
    # Create document
172
    document = language.Document(
173
        content="This is a great product!",
174
        type_=language.Document.Type.PLAIN_TEXT
175
    )
176
    
177
    # Perform async analysis
178
    response = await client.analyze_sentiment(
179
        request={"document": document}
180
    )
181
    
182
    print(f"Sentiment: {response.document_sentiment.score}")
183

184
# Run async function
185
asyncio.run(main())
186
```
187

188
### Transport Options
189

190
The library supports multiple transport mechanisms for communicating with the API.
191

192
#### gRPC Transport (Default)
193

194
```python { .api }
195
class LanguageServiceGrpcTransport:
196
    def __init__(
197
        self,
198
        *,
199
        host: str = "language.googleapis.com",
200
        credentials: ga_credentials.Credentials = None,
201
        credentials_file: str = None,
202
        scopes: Sequence[str] = None,
203
        channel: grpc.Channel = None,
204
        api_mtls_endpoint: str = None,
205
        client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
206
        ssl_channel_credentials: grpc.ChannelCredentials = None,
207
        client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
208
        quota_project_id: Optional[str] = None,
209
        client_info: gapic_v1.client_info.ClientInfo = None,
210
        always_use_jwt_access: Optional[bool] = False,
211
        api_audience: Optional[str] = None,
212
    ): ...
213
```
214

215
#### gRPC Async Transport
216

217
```python { .api }
218
class LanguageServiceGrpcAsyncIOTransport:
219
    def __init__(
220
        self,
221
        *,
222
        host: str = "language.googleapis.com",
223
        credentials: ga_credentials.Credentials = None,
224
        credentials_file: str = None,
225
        scopes: Sequence[str] = None,
226
        channel: aio.Channel = None,
227
        api_mtls_endpoint: str = None,
228
        client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
229
        ssl_channel_credentials: grpc.ChannelCredentials = None,
230
        client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
231
        quota_project_id: Optional[str] = None,
232
        client_info: gapic_v1.client_info.ClientInfo = None,
233
        always_use_jwt_access: Optional[bool] = False,
234
        api_audience: Optional[str] = None,
235
    ): ...
236
```
237

238
#### REST Transport
239

240
```python { .api }
241
class LanguageServiceRestTransport:
242
    def __init__(
243
        self,
244
        *,
245
        host: str = "language.googleapis.com",
246
        credentials: ga_credentials.Credentials = None,
247
        credentials_file: str = None,
248
        scopes: Sequence[str] = None,
249
        client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
250
        quota_project_id: Optional[str] = None,
251
        client_info: gapic_v1.client_info.ClientInfo = None,
252
        always_use_jwt_access: Optional[bool] = False,
253
        url_scheme: str = "https",
254
        interceptor: Optional[LanguageServiceRestInterceptor] = None,
255
        api_audience: Optional[str] = None,
256
    ): ...
257
```
258

259
### Client Configuration
260

261
Common configuration options for customizing client behavior.
262

263
#### Client Options
264

265
```python { .api }
266
from google.api_core import client_options
267

268
# Configure API endpoint
269
options = client_options.ClientOptions(
270
    api_endpoint="custom-language-endpoint.googleapis.com"
271
)
272

273
client = language.LanguageServiceClient(client_options=options)
274
```
275

276
#### Retry Configuration
277

278
```python
279
from google.api_core import retry
280

281
# Custom retry configuration
282
custom_retry = retry.Retry(
283
    predicate=retry.if_exception_type(
284
        core_exceptions.ServiceUnavailable,
285
        core_exceptions.DeadlineExceeded,
286
    ),
287
    deadline=60.0,
288
)
289

290
# Use with API calls
291
response = client.analyze_sentiment(
292
    request={"document": document},
293
    retry=custom_retry
294
)
295
```
296

297
#### Timeout Configuration
298

299
```python
300
# Set timeout for API calls
301
response = client.analyze_sentiment(
302
    request={"document": document},
303
    timeout=30.0  # 30 seconds
304
)
305
```
306

307
### Authentication Scopes
308

309
Required OAuth2 scopes for accessing the Cloud Natural Language API.
310

311
```python { .api }
312
AUTH_SCOPES = (
313
    "https://www.googleapis.com/auth/cloud-language",
314
    "https://www.googleapis.com/auth/cloud-platform",
315
)
316
```
317

318
### Constants
319

320
```python { .api }
321
DEFAULT_HOST = "language.googleapis.com"
322
DEFAULT_MTLS_HOST = "language.mtls.googleapis.com"
323
```