Skip to content
This repository was archived by the owner on Mar 31, 2026. It is now read-only.

Commit d8ad3ee

Browse files
tseavertseaver
committed
docs: streamline docstrings for conditional parmas
Link to new narrative docs. Also, move 'timeout' argument to end (just before 'retry', if present) for consistency. Closes #460.
1 parent b4f7fe9 commit d8ad3ee

5 files changed

Lines changed: 322 additions & 459 deletions

File tree

‎google/cloud/storage/_helpers.py‎

Lines changed: 42 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -140,11 +140,11 @@ def reload(
140140
self,
141141
client=None,
142142
projection="noAcl",
143-
timeout=_DEFAULT_TIMEOUT,
144143
if_generation_match=None,
145144
if_generation_not_match=None,
146145
if_metageneration_match=None,
147146
if_metageneration_not_match=None,
147+
timeout=_DEFAULT_TIMEOUT,
148148
retry=DEFAULT_RETRY,
149149
):
150150
"""Reload properties from Cloud Storage.
@@ -161,31 +161,26 @@ def reload(
161161
Defaults to ``'noAcl'``. Specifies the set of
162162
properties to return.
163163
164-
:type timeout: float or tuple
165-
:param timeout:
166-
(Optional) The amount of time, in seconds, to wait
167-
for the server response. See: :ref:`configuring_timeouts`
168-
169164
:type if_generation_match: long
170-
:param if_generation_match: (Optional) Make the operation conditional on whether
171-
the blob's current generation matches the given value.
172-
Setting to 0 makes the operation succeed only if there
173-
are no live versions of the blob.
165+
:param if_generation_match:
166+
(Optional) See :ref:`using-if-generation-match`
174167
175168
:type if_generation_not_match: long
176-
:param if_generation_not_match: (Optional) Make the operation conditional on whether
177-
the blob's current generation does not match the given
178-
value. If no live blob exists, the precondition fails.
179-
Setting to 0 makes the operation succeed only if there
180-
is a live version of the blob.
169+
:param if_generation_not_match:
170+
(Optional) See :ref:`using-if-generation-not-match`
181171
182172
:type if_metageneration_match: long
183-
:param if_metageneration_match: (Optional) Make the operation conditional on whether the
184-
blob's current metageneration matches the given value.
173+
:param if_metageneration_match:
174+
(Optional) See :ref:`using-if-metageneration-match`
185175
186176
:type if_metageneration_not_match: long
187-
:param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
188-
blob's current metageneration does not match the given value.
177+
:param if_metageneration_not_match:
178+
(Optional) See :ref:`using-if-metageneration-not-match`
179+
180+
:type timeout: float or tuple
181+
:param timeout:
182+
(Optional) The amount of time, in seconds, to wait
183+
for the server response. See: :ref:`configuring_timeouts`
189184
190185
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
191186
:param retry:
@@ -244,11 +239,11 @@ def _set_properties(self, value):
244239
def patch(
245240
self,
246241
client=None,
247-
timeout=_DEFAULT_TIMEOUT,
248242
if_generation_match=None,
249243
if_generation_not_match=None,
250244
if_metageneration_match=None,
251245
if_metageneration_not_match=None,
246+
timeout=_DEFAULT_TIMEOUT,
252247
retry=DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED,
253248
):
254249
"""Sends all changed properties in a PATCH request.
@@ -262,31 +257,26 @@ def patch(
262257
:param client: the client to use. If not passed, falls back to the
263258
``client`` stored on the current object.
264259
265-
:type timeout: float or tuple
266-
:param timeout:
267-
(Optional) The amount of time, in seconds, to wait
268-
for the server response. See: :ref:`configuring_timeouts`
269-
270260
:type if_generation_match: long
271-
:param if_generation_match: (Optional) Make the operation conditional on whether
272-
the blob's current generation matches the given value.
273-
Setting to 0 makes the operation succeed only if there
274-
are no live versions of the blob.
261+
:param if_generation_match:
262+
(Optional) See :ref:`using-if-generation-match`
275263
276264
:type if_generation_not_match: long
277-
:param if_generation_not_match: (Optional) Make the operation conditional on whether
278-
the blob's current generation does not match the given
279-
value. If no live blob exists, the precondition fails.
280-
Setting to 0 makes the operation succeed only if there
281-
is a live version of the blob.
265+
:param if_generation_not_match:
266+
(Optional) See :ref:`using-if-generation-not-match`
282267
283268
:type if_metageneration_match: long
284-
:param if_metageneration_match: (Optional) Make the operation conditional on whether the
285-
blob's current metageneration matches the given value.
269+
:param if_metageneration_match:
270+
(Optional) See :ref:`using-if-metageneration-match`
286271
287272
:type if_metageneration_not_match: long
288-
:param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
289-
blob's current metageneration does not match the given value.
273+
:param if_metageneration_not_match:
274+
(Optional) See :ref:`using-if-metageneration-not-match`
275+
276+
:type timeout: float or tuple
277+
:param timeout:
278+
(Optional) The amount of time, in seconds, to wait
279+
for the server response. See: :ref:`configuring_timeouts`
290280
291281
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
292282
:param retry:
@@ -320,11 +310,11 @@ def patch(
320310
def update(
321311
self,
322312
client=None,
323-
timeout=_DEFAULT_TIMEOUT,
324313
if_generation_match=None,
325314
if_generation_not_match=None,
326315
if_metageneration_match=None,
327316
if_metageneration_not_match=None,
317+
timeout=_DEFAULT_TIMEOUT,
328318
retry=DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED,
329319
):
330320
"""Sends all properties in a PUT request.
@@ -338,31 +328,26 @@ def update(
338328
:param client: the client to use. If not passed, falls back to the
339329
``client`` stored on the current object.
340330
341-
:type timeout: float or tuple
342-
:param timeout:
343-
(Optional) The amount of time, in seconds, to wait
344-
for the server response. See: :ref:`configuring_timeouts`
345-
346331
:type if_generation_match: long
347-
:param if_generation_match: (Optional) Make the operation conditional on whether
348-
the blob's current generation matches the given value.
349-
Setting to 0 makes the operation succeed only if there
350-
are no live versions of the blob.
332+
:param if_generation_match:
333+
(Optional) See :ref:`using-if-generation-match`
351334
352335
:type if_generation_not_match: long
353-
:param if_generation_not_match: (Optional) Make the operation conditional on whether
354-
the blob's current generation does not match the given
355-
value. If no live blob exists, the precondition fails.
356-
Setting to 0 makes the operation succeed only if there
357-
is a live version of the blob.
336+
:param if_generation_not_match:
337+
(Optional) See :ref:`using-if-generation-not-match`
358338
359339
:type if_metageneration_match: long
360-
:param if_metageneration_match: (Optional) Make the operation conditional on whether the
361-
blob's current metageneration matches the given value.
340+
:param if_metageneration_match:
341+
(Optional) See :ref:`using-if-metageneration-match`
362342
363343
:type if_metageneration_not_match: long
364-
:param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
365-
blob's current metageneration does not match the given value.
344+
:param if_metageneration_not_match:
345+
(Optional) See :ref:`using-if-metageneration-not-match`
346+
347+
:type timeout: float or tuple
348+
:param timeout:
349+
(Optional) The amount of time, in seconds, to wait
350+
for the server response. See: :ref:`configuring_timeouts`
366351
367352
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
368353
:param retry:

0 commit comments

Comments
 (0)