Skip to content

Commit fd6df73

Browse files
bshafferparthea
bshaffer
and
parthea
authored
feat(docs): publish Client libraries help to reference documentation (#16575)
b/450298584 Publishes documentation to https://cloud.google.com/python/docs/reference under "Client libraries help". This currently only contains the `README.rst` contents from the root of this repo. We will expand this to add more once we've confirmed this is deploying as expected. --------- Co-authored-by: Anthonios Partheniou <partheniou@google.com>
1 parent c513b39 commit fd6df73

3 files changed

Lines changed: 234 additions & 0 deletions

File tree

‎docs/devsite-help/getting-started.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Getting started with client libraries
2+
3+
The Google Cloud Libraries for Python are a mixture of handwritten and autogenerated
4+
libraries connecting to Google Cloud services. The handwritten libraries (such
5+
as [google-cloud-firestore](https://docs.cloud.google.com/python/docs/reference/firestore/latest) and
6+
[google-cloud-spanner](https://docs.cloud.google.com/python/docs/reference/spanner/latest))
7+
are mostly higher level abstractions over the underlying API. See the documentation
8+
for those individual libraries for details; the documentation here is primarily
9+
aimed at the autogenerated libraries.
10+
11+
If you haven't already found the library for the API you're interested in, please consult
12+
[the list of Python libraries](https://cloud.google.com/python/docs/reference) which shows both the package
13+
name and the link to the library-specific documentation. In particular, each library has:
14+
15+
- A "getting started" page which lists the client types within that library
16+
- Version history for the library
17+
- API reference documentation
18+
19+
This page demonstrates using the [google-cloud-translate](https://docs.cloud.google.com/python/docs/reference/translate/latest)
20+
API as a simple example; the steps required for other APIs are very similar.
21+
22+
## Prerequisites
23+
24+
All Google Cloud APIs require a Google Cloud project. If you haven't set one up already,
25+
please [create one](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
26+
You'll also need to [enable your chosen API](https://console.cloud.google.com/apis/library) if it hasn't
27+
already been used within that Google Cloud project.
28+
29+
There are no specific tools required to develop using the Google Cloud Libraries for Python. All
30+
development environments should work, but you should check that you're targeting a
31+
[supported version of Python](https://docs.cloud.google.com/python/docs/supported-python-versions).
32+
33+
We recommend installing the [gcloud CLI](https://cloud.google.com/sdk/gcloud).
34+
35+
## Install the library
36+
37+
All Google Cloud Libraries for Python are available from [PyPI](https://pypi.org) and can be installed
38+
using `pip`. If you wish to install a pre-release version, you can specify the version explicitly
39+
with the installation command.
40+
41+
The libraries can be installed in any regular environment, including virtual environments (recommended),
42+
containerized applications, and web frameworks like Django or Flask.
43+
44+
For the translation example, we'll create a new directory, set up a virtual environment,
45+
and install the package.
46+
47+
Note that for simplicity, the sample code below uses synchronous calls. Most libraries also provide
48+
asynchronous clients (usually with suffix `AsyncClient`, rather than `Client`) for use in naturally asynchronous environments
49+
using `asyncio`.
50+
51+
```sh
52+
mkdir TranslationExample
53+
cd TranslationExample
54+
python3 -m venv venv
55+
source venv/bin/activate
56+
pip install google-cloud-translate
57+
```
58+
59+
> **Dependencies**
60+
> If you install the library, you may notice
61+
> transitive dependencies being installed. This is entirely expected, but you may not recognize
62+
> some of those dependencies. The list below is not comprehensive, but highlights some of the packages
63+
> you'll see being installed.
64+
>
65+
> - protobuf: the library supporting the [Protocol Buffers](https://protobuf.dev) serialization format
66+
> - google-api-core: support libraries specifically tailored for the Google Cloud client libraries
67+
> - google-auth: authentication support for Google Cloud credentials
68+
> - grpcio: support for the [gRPC](https://grpc.io/) RPC protocol
69+
> - google-cloud-core: common helpers and support for [long-running operations](https://docs.cloud.google.com/python/docs/reference/google-cloud-core/latest)
70+
71+
## Create a client
72+
73+
The first step in making any API calls is to create a client. Some libraries have multiple clients
74+
for operations involving different resources; others have a single client. In the Translation API
75+
we're using, we use `TranslationServiceClient` which can be used to create a synchronous client.
76+
77+
Clients can be configured in a number of ways, but in many cases the defaults are fine. The most
78+
common reason to use an explicit configuration is to specify credentials for
79+
[authentication](https://cloud.google.com/docs/authentication/use-cases). For this example, we'll just use
80+
[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
81+
To set up ADC in your local environment, follow the instructions in
82+
[Local development environment](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
83+
When you create a client, it automatically detects and uses these credentials.
84+
85+
To create a client with default settings:
86+
87+
```python
88+
from google.cloud import translate_v3 as translate
89+
90+
client = translate.TranslationServiceClient()
91+
```
92+
93+
## Make requests
94+
95+
The Google Cloud Libraries use [Protocol Buffers](https://protobuf.dev)
96+
to represent requests and responses, with some additional types to make the APIs more
97+
convenient to work with.
98+
99+
Most APIs are expressed in terms of a single request returning a single response, although
100+
there are also streaming APIs requiring multiple requests and/or multiple responses.
101+
For our Translation API example, we'll create a simple request for the `translate_text` API.
102+
103+
```python
104+
from google.cloud import translate_v3 as translate
105+
106+
client = translate.TranslationServiceClient()
107+
108+
project_id = "your-project-id-here"
109+
location_id = "global"
110+
parent = f"projects/{project_id}/locations/{location_id}"
111+
request = translate.TranslateTextRequest(
112+
contents=["It is raining.", "It is sunny."],
113+
target_language_code="fr-FR",
114+
parent=parent
115+
)
116+
117+
response = client.translate_text(request=request)
118+
```
119+
120+
This example demonstrates a few features:
121+
122+
- Protocol Buffer messages are instantiated with keyword arguments representing the fields
123+
- Repeated fields (like `contents`) are represented as Python lists
124+
- The `parent` field is a string representation of a resource name. The library provides helper methods
125+
on the client to construct these paths, ensuring you don't need to concern yourself
126+
with the underlying resource name format.
127+
```python
128+
# produces the string `projects/your-project-id-here/locations/global`
129+
parent = client.location_path(project_id, location_id)
130+
```
131+
132+
The Google Cloud Libraries always expose methods accepting an API request object directly,
133+
but they also support passing keyword arguments directly to the method for convenience:
134+
135+
```python
136+
response = client.translate_text(
137+
contents=["It is raining.", "It is sunny."],
138+
target_language_code="fr-FR",
139+
parent=parent,
140+
)
141+
```
142+
143+
The response is also a Protocol Buffers message. You can inspect the structure of the response
144+
by printing it, or by accessing its attributes directly. In this case we'll look at the
145+
`translations` attribute:
146+
147+
```python
148+
print(f"Translations returned: {len(response.translations)}")
149+
print()
150+
for translation in response.translations:
151+
print(f"Detected language: {translation.detected_language_code}")
152+
print(f"Translated text: {translation.translated_text}")
153+
```
154+
155+
This produces output of:
156+
157+
```text
158+
Translations returned: 2
159+
160+
Detected language: en
161+
Translated text: Il pleut.
162+
163+
Detected language: en
164+
Translated text: Il fait beau.
165+
```
166+
167+
The complete code is:
168+
169+
```python
170+
from google.cloud import translate_v3 as translate
171+
172+
client = translate.TranslationServiceClient()
173+
174+
project_id = "your-project-id-here"
175+
location_id = "global"
176+
parent = f"projects/{project_id}/locations/{location_id}"
177+
178+
request = translate.TranslateTextRequest(
179+
contents=["It is raining.", "It is sunny."],
180+
target_language_code="fr-FR",
181+
parent=parent,
182+
)
183+
184+
response = client.translate_text(request=request)
185+
186+
print(f"Translations returned: {len(response.translations)}")
187+
print()
188+
for translation in response.translations:
189+
print(f"Detected language: {translation.detected_language_code}")
190+
print(f"Translated text: {translation.translated_text}")
191+
```
192+
193+
This is just a simple example, which hasn't touched on features like pagination
194+
or specifying call configurations like timeouts and retries.
195+

‎docs/devsite-help/toc.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
- uid: product-neutral-guides
2+
name: 'Client library help'
3+
items:
4+
-
5+
name: 'Getting Started'
6+
href: 'getting-started.md'

‎docs/generate-devsite-help.sh‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#!/bin/bash
2+
3+
set -e
4+
REPOROOT=$(git rev-parse --show-toplevel)
5+
6+
if [[ -z "$1" ]]
7+
then
8+
declare -r VERSION="1.0.0"
9+
else
10+
declare -r VERSION=$1
11+
fi
12+
13+
DEVSITE_STAGING_BUCKET=docs-staging-v2
14+
15+
rm -rf $REPOROOT/docs/output
16+
mkdir -p $REPOROOT/docs/output
17+
18+
cp $REPOROOT/docs/devsite-help/* $REPOROOT/docs/output
19+
cd $REPOROOT/docs/output
20+
21+
# Create the docs metadata.
22+
docuploader create-metadata \
23+
--name help \
24+
--version $VERSION \
25+
--language python
26+
27+
# Upload the
28+
docuploader upload . \
29+
--staging-bucket="$DEVSITE_STAGING_BUCKET" \
30+
--destination-prefix="docfx-" \
31+
--metadata-file="docs.metadata"
32+
33+
echo 'Done'

0 commit comments

Comments
 (0)