FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add documentation for google.api.core modules (#4203) · googleapis/google-cloud-python@16f6566 · GitHub

/ google-cloud-python Public

Commit 16f6566

Browse files
Jon Wayne Parrott
authored
Add documentation for google.api.core modules (#4203)
1 parent 915238d commit 16f6566

19 files changed

Lines changed: 159 additions & 92 deletions

‎core/google/api/core/exceptions.py‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -150,8 +150,8 @@ class TemporaryRedirect(Redirection):
150150
class ResumeIncomplete(Redirection):
151151
"""Exception mapping a ``308 Resume Incomplete`` response.
152152
153-
.. note:: :ref:`http_client.PERMANENT_REDIRECT` is ``308``, but Google APIs
154-
differ in their use of this status code.
153+
.. note:: :attr:`http_client.PERMANENT_REDIRECT` is ``308``, but Google
154+
APIs differ in their use of this status code.
155155
"""
156156
code = 308
157157

@@ -166,20 +166,20 @@ class BadRequest(ClientError):
166166

167167

168168
class InvalidArgument(BadRequest):
169-
"""Exception mapping a :prop:`grpc.StatusCode.INVALID_ARGUMENT` error."""
169+
"""Exception mapping a :attr:`grpc.StatusCode.INVALID_ARGUMENT` error."""
170170
grpc_status_code = (
171171
grpc.StatusCode.INVALID_ARGUMENT if grpc is not None else None)
172172

173173

174174
class FailedPrecondition(BadRequest):
175-
"""Exception mapping a :prop:`grpc.StatusCode.FAILED_PRECONDITION`
175+
"""Exception mapping a :attr:`grpc.StatusCode.FAILED_PRECONDITION`
176176
error."""
177177
grpc_status_code = (
178178
grpc.StatusCode.FAILED_PRECONDITION if grpc is not None else None)
179179

180180

181181
class OutOfRange(BadRequest):
182-
"""Exception mapping a :prop:`grpc.StatusCode.OUT_OF_RANGE` error."""
182+
"""Exception mapping a :attr:`grpc.StatusCode.OUT_OF_RANGE` error."""
183183
grpc_status_code = (
184184
grpc.StatusCode.OUT_OF_RANGE if grpc is not None else None)
185185

@@ -190,7 +190,7 @@ class Unauthorized(ClientError):
190190

191191

192192
class Unauthenticated(Unauthorized):
193-
"""Exception mapping a :prop:`grpc.StatusCode.UNAUTHENTICATED` error."""
193+
"""Exception mapping a :attr:`grpc.StatusCode.UNAUTHENTICATED` error."""
194194
grpc_status_code = (
195195
grpc.StatusCode.UNAUTHENTICATED if grpc is not None else None)
196196

@@ -201,14 +201,14 @@ class Forbidden(ClientError):
201201

202202

203203
class PermissionDenied(Forbidden):
204-
"""Exception mapping a :prop:`grpc.StatusCode.PERMISSION_DENIED` error."""
204+
"""Exception mapping a :attr:`grpc.StatusCode.PERMISSION_DENIED` error."""
205205
grpc_status_code = (
206206
grpc.StatusCode.PERMISSION_DENIED if grpc is not None else None)
207207

208208

209209
class NotFound(ClientError):
210210
"""Exception mapping a ``404 Not Found`` response or a
211-
:prop:`grpc.StatusCode.NOT_FOUND` error."""
211+
:attr:`grpc.StatusCode.NOT_FOUND` error."""
212212
code = http_client.NOT_FOUND
213213
grpc_status_code = (
214214
grpc.StatusCode.NOT_FOUND if grpc is not None else None)
@@ -225,13 +225,13 @@ class Conflict(ClientError):
225225

226226

227227
class AlreadyExists(Conflict):
228-
"""Exception mapping a :prop:`grpc.StatusCode.ALREADY_EXISTS` error."""
228+
"""Exception mapping a :attr:`grpc.StatusCode.ALREADY_EXISTS` error."""
229229
grpc_status_code = (
230230
grpc.StatusCode.ALREADY_EXISTS if grpc is not None else None)
231231

232232

233233
class Aborted(Conflict):
234-
"""Exception mapping a :prop:`grpc.StatusCode.ABORTED` error."""
234+
"""Exception mapping a :attr:`grpc.StatusCode.ABORTED` error."""
235235
grpc_status_code = (
236236
grpc.StatusCode.ABORTED if grpc is not None else None)
237237

@@ -258,13 +258,13 @@ class TooManyRequests(ClientError):
258258

259259

260260
class ResourceExhausted(TooManyRequests):
261-
"""Exception mapping a :prop:`grpc.StatusCode.RESOURCE_EXHAUSTED` error."""
261+
"""Exception mapping a :attr:`grpc.StatusCode.RESOURCE_EXHAUSTED` error."""
262262
grpc_status_code = (
263263
grpc.StatusCode.RESOURCE_EXHAUSTED if grpc is not None else None)
264264

265265

266266
class Cancelled(ClientError):
267-
"""Exception mapping a :prop:`grpc.StatusCode.CANCELLED` error."""
267+
"""Exception mapping a :attr:`grpc.StatusCode.CANCELLED` error."""
268268
# This maps to HTTP status code 499. See
269269
# https://github.com/googleapis/googleapis/blob/master/google/rpc\
270270
# /code.proto
@@ -278,24 +278,24 @@ class ServerError(GoogleAPICallError):
278278

279279
class InternalServerError(ServerError):
280280
"""Exception mapping a ``500 Internal Server Error`` response. or a
281-
:prop:`grpc.StatusCode.INTERNAL` error."""
281+
:attr:`grpc.StatusCode.INTERNAL` error."""
282282
code = http_client.INTERNAL_SERVER_ERROR
283283
grpc_status_code = grpc.StatusCode.INTERNAL if grpc is not None else None
284284

285285

286286
class Unknown(ServerError):
287-
"""Exception mapping a :prop:`grpc.StatusCode.UNKNOWN` error."""
287+
"""Exception mapping a :attr:`grpc.StatusCode.UNKNOWN` error."""
288288
grpc_status_code = grpc.StatusCode.UNKNOWN if grpc is not None else None
289289

290290

291291
class DataLoss(ServerError):
292-
"""Exception mapping a :prop:`grpc.StatusCode.DATA_LOSS` error."""
292+
"""Exception mapping a :attr:`grpc.StatusCode.DATA_LOSS` error."""
293293
grpc_status_code = grpc.StatusCode.DATA_LOSS if grpc is not None else None
294294

295295

296296
class MethodNotImplemented(ServerError):
297297
"""Exception mapping a ``501 Not Implemented`` response or a
298-
:prop:`grpc.StatusCode.UNIMPLEMENTED` error."""
298+
:attr:`grpc.StatusCode.UNIMPLEMENTED` error."""
299299
code = http_client.NOT_IMPLEMENTED
300300
grpc_status_code = (
301301
grpc.StatusCode.UNIMPLEMENTED if grpc is not None else None)
@@ -308,7 +308,7 @@ class BadGateway(ServerError):
308308

309309
class ServiceUnavailable(ServerError):
310310
"""Exception mapping a ``503 Service Unavailable`` response or a
311-
:prop:`grpc.StatusCode.UNAVAILABLE` error."""
311+
:attr:`grpc.StatusCode.UNAVAILABLE` error."""
312312
code = http_client.SERVICE_UNAVAILABLE
313313
grpc_status_code = (
314314
grpc.StatusCode.UNAVAILABLE if grpc is not None else None)
@@ -320,7 +320,7 @@ class GatewayTimeout(ServerError):
320320

321321

322322
class DeadlineExceeded(GatewayTimeout):
323-
"""Exception mapping a :prop:`grpc.StatusCode.DEADLINE_EXCEEDED` error."""
323+
"""Exception mapping a :attr:`grpc.StatusCode.DEADLINE_EXCEEDED` error."""
324324
grpc_status_code = (
325325
grpc.StatusCode.DEADLINE_EXCEEDED if grpc is not None else None)
326326

@@ -332,7 +332,7 @@ def exception_class_for_http_status(status_code):
332332
status_code (int): The HTTP status code.
333333
334334
Returns:
335-
type: the appropriate subclass of :class:`GoogleAPICallError`.
335+
:func:`type`: the appropriate subclass of :class:`GoogleAPICallError`.
336336
"""
337337
return _HTTP_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError)
338338

@@ -395,7 +395,7 @@ def exception_class_for_grpc_status(status_code):
395395
status_code (grpc.StatusCode): The gRPC status code.
396396
397397
Returns:
398-
type: the appropriate subclass of :class:`GoogleAPICallError`.
398+
:func:`type`: the appropriate subclass of :class:`GoogleAPICallError`.
399399
"""
400400
return _GRPC_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError)
401401

‎core/google/api/core/gapic_v1/config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ def _exception_class_for_grpc_status_name(name):
3939
``UNAVAILABLE``.
4040
4141
Returns:
42-
type: The appropriate subclass of
42+
:func:`type`: The appropriate subclass of
4343
:class:`google.api.core.exceptions.GoogleAPICallError`.
4444
"""
4545
return exceptions.exception_class_for_grpc_status(

‎core/google/api/core/operation.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,9 @@ class Operation(polling.PollingFuture):
5757
latest state of the operation.
5858
cancel (Callable[[], None]): A callable that tries to cancel
5959
the operation.
60-
result_type (type): The protobuf type for the operation's result.
61-
metadata_type (type): The protobuf type for the operation's
60+
result_type (func:`type`): The protobuf type for the operation's
61+
result.
62+
metadata_type (func:`type`): The protobuf type for the operation's
6263
metadata.
6364
"""
6465

@@ -200,7 +201,7 @@ def from_http_json(operation, api_request, result_type, **kwargs):
200201
api_request (Callable): A callable used to make an API request. This
201202
should generally be
202203
:meth:`google.cloud._http.Connection.api_request`.
203-
result_type (type): The protobuf result type.
204+
result_type (:func:`type`): The protobuf result type.
204205
kwargs: Keyword args passed into the :class:`Operation` constructor.
205206
206207
Returns:
@@ -256,7 +257,7 @@ def from_grpc(operation, operations_stub, result_type, **kwargs):
256257
operation (google.longrunning.operations_pb2.Operation): The operation.
257258
operations_stub (google.longrunning.operations_pb2.OperationsStub):
258259
The operations stub.
259-
result_type (type): The protobuf result type.
260+
result_type (:func:`type`): The protobuf result type.
260261
kwargs: Keyword args passed into the :class:`Operation` constructor.
261262
262263
Returns:
@@ -283,7 +284,7 @@ def from_gapic(operation, operations_client, result_type, **kwargs):
283284
operation (google.longrunning.operations_pb2.Operation): The operation.
284285
operations_client (google.api.core.operations_v1.OperationsClient):
285286
The operations client.
286-
result_type (type): The protobuf result type.
287+
result_type (:func:`type`): The protobuf result type.
287288
kwargs: Keyword args passed into the :class:`Operation` constructor.
288289
289290
Returns:

‎core/google/api/core/page_iterator.py‎

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
https://cloud.google.com/apis/design/design_patterns#list_pagination
2424
2525
API clients that have methods that follow the list pagination pattern can
26-
return an :class:`Iterator`. You can use this iterator to get **all** of
26+
return an :class:`.Iterator`. You can use this iterator to get **all** of
2727
the results across all pages::
2828
2929
>>> results_iterator = client.list_resources()
@@ -88,12 +88,14 @@ class Page(object):
8888
"""Single page of results in an iterator.
8989
9090
Args:
91-
parent (Iterator): The iterator that owns the current page.
91+
parent (google.api.core.page_iterator.Iterator): The iterator that owns
92+
the current page.
9293
items (Sequence[Any]): An iterable (that also defines __len__) of items
9394
from a raw API response.
94-
item_to_value (Callable[Iterator, Any]): Callable to convert an item
95-
from the type in the raw API response into the native object. Will
96-
be called with the iterator and a single item.
95+
item_to_value (Callable[google.api.core.page_iterator.Iterator, Any]):
96+
Callable to convert an item from the type in the raw API response
97+
into the native object. Will be called with the iterator and a
98+
single item.
9799
"""
98100

99101
def __init__(self, parent, items, item_to_value):
@@ -143,9 +145,10 @@ class Iterator(object):
143145
144146
Args:
145147
client(google.cloud.client.Client): The API client.
146-
item_to_value (Callable[Iterator, Any]): Callable to convert an item
147-
from the type in the raw API response into the native object. Will
148-
be called with the iterator and a single item.
148+
item_to_value (Callable[google.api.core.page_iterator.Iterator, Any]):
149+
Callable to convert an item from the type in the raw API response
150+
into the native object. Will be called with the iterator and a
151+
single item.
149152
page_token (str): A token identifying a page in a result set to start
150153
fetching results from.
151154
max_results (int): The maximum number of results to fetch.
@@ -167,7 +170,8 @@ def pages(self):
167170
"""Iterator of pages in the response.
168171
169172
returns:
170-
types.GeneratorType[Page]: A generator of :class:`Page` instances.
173+
types.GeneratorType[google.api.core.page_iterator.Page]: A
174+
generator of page instances.
171175
172176
raises:
173177
ValueError: If the iterator has already been started.
@@ -260,20 +264,23 @@ class HTTPIterator(Iterator):
260264
Generally, this will be
261265
:meth:`google.cloud._http.JSONConnection.api_request`.
262266
path (str): The method path to query for the list of items.
263-
item_to_value (Callable[Iterator, Any]): Callable to convert an item
264-
from the type in the JSON response into a native object. Will
265-
be called with the iterator and a single item.
267+
item_to_value (Callable[google.api.core.page_iterator.Iterator, Any]):
268+
Callable to convert an item from the type in the JSON response into
269+
a native object. Will be called with the iterator and a single
270+
item.
266271
items_key (str): The key in the API response where the list of items
267272
can be found.
268273
page_token (str): A token identifying a page in a result set to start
269274
fetching results from.
270275
max_results (int): The maximum number of results to fetch.
271276
extra_params (dict): Extra query string parameters for the
272277
API call.
273-
page_start (Callable[Iterator, Page, dict]): Callable to provide any
274-
special behavior after a new page has been created. Assumed
275-
signature takes the :class:`Iterator` that started the page,
276-
the :class:`Page` that was started and the dictionary containing
278+
page_start (Callable[
279+
google.api.core.page_iterator.Iterator,
280+
google.api.core.page_iterator.Page, dict]): Callable to provide
281+
any special behavior after a new page has been created. Assumed
282+
signature takes the :class:`.Iterator` that started the page,
283+
the :class:`.Page` that was started and the dictionary containing
277284
the page response.
278285
next_token (str): The name of the field used in the response for page
279286
tokens.
@@ -442,8 +449,8 @@ class GRPCIterator(Iterator):
442449
request (protobuf.Message): The request message.
443450
items_field (str): The field in the response message that has the
444451
items for the page.
445-
item_to_value (Callable[Iterator, Any]): Callable to convert an item
446-
from the type in the JSON response into a native object. Will
452+
item_to_value (Callable[GRPCIterator, Any]): Callable to convert an
453+
item from the type in the JSON response into a native object. Will
447454
be called with the iterator and a single item.
448455
request_token_field (str): The field in the request message used to
449456
specify the page token.
@@ -479,8 +486,8 @@ def _next_page(self):
479486
"""Get the next page in the iterator.
480487
481488
Returns:
482-
Page: The next page in the iterator or :data:`None` if there are no
483-
pages left.
489+
Page: The next page in the iterator or :data:`None` if
490+
there are no pages left.
484491
"""
485492
if not self._has_next_page():
486493
return None

‎core/google/api/core/retry.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@
1414

1515
"""Helpers for retrying functions with exponential back-off.
1616
17-
The :cls:`Retry` decorator can be used to retry functions that raise exceptions
18-
using exponential backoff. Because a exponential sleep algorithm is used,
19-
the retry is limited by a `deadline`. The deadline is the maxmimum amount of
20-
time a method can block. This is used instead of total number of retries
17+
The :class:`Retry` decorator can be used to retry functions that raise
18+
exceptions using exponential backoff. Because a exponential sleep algorithm is
19+
used, the retry is limited by a `deadline`. The deadline is the maxmimum amount
20+
of time a method can block. This is used instead of total number of retries
2121
because it is difficult to ascertain the amount of time a function can block
2222
when using total number of retries and exponential backoff.
2323
@@ -79,7 +79,8 @@ def if_exception_type(*exception_types):
7979
"""Creates a predicate to check if the exception is of a given type.
8080
8181
Args:
82-
exception_types (Sequence[type]): The exception types to check for.
82+
exception_types (Sequence[:func:`type`]): The exception types to check
83+
for.
8384
8485
Returns:
8586
Callable[Exception]: A predicate that returns True if the provided
@@ -148,7 +149,7 @@ def retry_target(target, predicate, sleep_generator, deadline, on_error=None):
148149
predicate (Callable[Exception]): A callable used to determine if an
149150
exception raised by the target should be considered retryable.
150151
It should return True to retry or False otherwise.
151-
sleep_generator (Iterator[float]): An infinite iterator that determines
152+
sleep_generator (Iterable[float]): An infinite iterator that determines
152153
how long to sleep between retries.
153154
deadline (float): How long to keep retrying the target.
154155
on_error (Callable): A function to call while processing a retryable

‎docs/core/client.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Base Client
2+
===========
3+
4+
.. automodule:: google.cloud.client
5+
:members:
6+
:show-inheritance:

‎docs/core/config.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,3 +58,11 @@ using the ``gcloud`` CLI tool to change the configuration.
5858
.. code-block:: bash
5959
6060
$ gcloud config set project my-new-default-project
61+
62+
63+
Environment Variables
64+
=====================
65+
66+
.. automodule:: google.cloud.environment_vars
67+
:members:
68+
:show-inheritance:

‎docs/core/exceptions.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Exceptions
2+
==========
3+
4+
.. automodule:: google.api.core.exceptions
5+
:members:
6+
:show-inheritance:

‎docs/core/helpers.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
Helpers
2+
=======
3+
4+
5+
General Helpers
6+
---------------
7+
8+
.. automodule:: google.api.core.general_helpers
9+
:members:
10+
:show-inheritance:
11+
12+
13+
Datetime Helpers
14+
----------------
15+
16+
.. automodule:: google.api.core.datetime_helpers
17+
:members:
18+
:show-inheritance:
19+
20+
21+
gRPC Helpers
22+
------------
23+
24+
.. automodule:: google.api.core.grpc_helpers
25+
:members:
26+
:show-inheritance:

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL