From 0d868ba0ba58f1bdf4e75d8651d894c39d1f69ff Mon Sep 17 00:00:00 2001 From: Brett Smith Date: Mon, 25 Sep 2023 16:26:46 -0400 Subject: [PATCH] 20885: Update PySDK docstrings after pdoc migration Arvados-DCO-1.1-Signed-off-by: Brett Smith --- sdk/python/arvados/api.py | 120 ++++++++++++++++------------------ sdk/python/arvados/retry.py | 58 ++++++++-------- sdk/python/arvados/util.py | 5 +- sdk/python/discovery2pydoc.py | 4 +- 4 files changed, 88 insertions(+), 99 deletions(-) diff --git a/sdk/python/arvados/api.py b/sdk/python/arvados/api.py index c51be82b20..94b8013997 100644 --- a/sdk/python/arvados/api.py +++ b/sdk/python/arvados/api.py @@ -207,45 +207,41 @@ def api_client( Arguments: - version: str - : A string naming the version of the Arvados API to use. + * version: str --- A string naming the version of the Arvados API to use. - discoveryServiceUrl: str - : The URL used to discover APIs passed directly to - `googleapiclient.discovery.build`. + * discoveryServiceUrl: str --- The URL used to discover APIs passed + directly to `googleapiclient.discovery.build`. - token: str - : The authentication token to send with each API call. + * token: str --- The authentication token to send with each API call. Keyword-only arguments: - cache: bool - : If true, loads the API discovery document from, or saves it to, a cache - on disk (located at `~/.cache/arvados/discovery`). + * cache: bool --- If true, loads the API discovery document from, or + saves it to, a cache on disk (located at + `~/.cache/arvados/discovery`). - http: httplib2.Http | None - : The HTTP client object the API client object will use to make requests. - If not provided, this function will build its own to use. Either way, the - object will be patched as part of the build process. + * http: httplib2.Http | None --- The HTTP client object the API client + object will use to make requests. If not provided, this function will + build its own to use. Either way, the object will be patched as part + of the build process. - insecure: bool - : If true, ignore SSL certificate validation errors. Default `False`. + * insecure: bool --- If true, ignore SSL certificate validation + errors. Default `False`. - num_retries: int - : The number of times to retry each API request if it encounters a - temporary failure. Default 10. + * num_retries: int --- The number of times to retry each API request if + it encounters a temporary failure. Default 10. - request_id: str | None - : Default `X-Request-Id` header value for outgoing requests that - don't already provide one. If `None` or omitted, generate a random - ID. When retrying failed requests, the same ID is used on all - attempts. + * request_id: str | None --- Default `X-Request-Id` header value for + outgoing requests that don't already provide one. If `None` or + omitted, generate a random ID. When retrying failed requests, the same + ID is used on all attempts. - timeout: int - : A timeout value for HTTP requests in seconds. Default 300 (5 minutes). + * timeout: int --- A timeout value for HTTP requests in seconds. Default + 300 (5 minutes). Additional keyword arguments will be passed directly to `googleapiclient.discovery.build`. + """ if http is None: http = httplib2.Http( @@ -322,22 +318,19 @@ def normalize_api_kwargs( Arguments: - version: str | None - : A string naming the version of the Arvados API to use. If not specified, - the code will log a warning and fall back to 'v1'. + * version: str | None --- A string naming the version of the Arvados API + to use. If not specified, the code will log a warning and fall back to + 'v1'. - discoveryServiceUrl: str | None - : The URL used to discover APIs passed directly to - `googleapiclient.discovery.build`. It is an error to pass both - `discoveryServiceUrl` and `host`. + * discoveryServiceUrl: str | None --- The URL used to discover APIs + passed directly to `googleapiclient.discovery.build`. It is an error + to pass both `discoveryServiceUrl` and `host`. - host: str | None - : The hostname and optional port number of the Arvados API server. Used to - build `discoveryServiceUrl`. It is an error to pass both - `discoveryServiceUrl` and `host`. + * host: str | None --- The hostname and optional port number of the + Arvados API server. Used to build `discoveryServiceUrl`. It is an + error to pass both `discoveryServiceUrl` and `host`. - token: str - : The authentication token to send with each API call. + * token: str --- The authentication token to send with each API call. Additional keyword arguments will be included in the return value. """ @@ -378,14 +371,15 @@ def api_kwargs_from_config(version=None, apiconfig=None, **kwargs): Arguments: - version: str | None - : A string naming the version of the Arvados API to use. If not specified, - the code will log a warning and fall back to 'v1'. + * version: str | None --- A string naming the version of the Arvados API + to use. If not specified, the code will log a warning and fall back to + 'v1'. - apiconfig: Mapping[str, str] | None - : A mapping with entries for `ARVADOS_API_HOST`, `ARVADOS_API_TOKEN`, and - optionally `ARVADOS_API_HOST_INSECURE`. If not provided, calls - `arvados.config.settings` to get these parameters from user configuration. + * apiconfig: Mapping[str, str] | None --- A mapping with entries for + `ARVADOS_API_HOST`, `ARVADOS_API_TOKEN`, and optionally + `ARVADOS_API_HOST_INSECURE`. If not provided, calls + `arvados.config.settings` to get these parameters from user + configuration. Additional keyword arguments will be included in the return value. """ @@ -428,19 +422,18 @@ def api(version=None, cache=True, host=None, token=None, insecure=False, Arguments: - version: str | None - : A string naming the version of the Arvados API to use. If not specified, - the code will log a warning and fall back to 'v1'. + * version: str | None --- A string naming the version of the Arvados API + to use. If not specified, the code will log a warning and fall back to + 'v1'. - host: str | None - : The hostname and optional port number of the Arvados API server. + * host: str | None --- The hostname and optional port number of the + Arvados API server. - token: str | None - : The authentication token to send with each API call. + * token: str | None --- The authentication token to send with each API + call. - discoveryServiceUrl: str | None - : The URL used to discover APIs passed directly to - `googleapiclient.discovery.build`. + * discoveryServiceUrl: str | None --- The URL used to discover APIs + passed directly to `googleapiclient.discovery.build`. If `host`, `token`, and `discoveryServiceUrl` are all omitted, `host` and `token` will be loaded from the user's configuration. Otherwise, you must @@ -479,14 +472,15 @@ def api_from_config(version=None, apiconfig=None, **kwargs): Arguments: - version: str | None - : A string naming the version of the Arvados API to use. If not specified, - the code will log a warning and fall back to 'v1'. + * version: str | None --- A string naming the version of the Arvados API + to use. If not specified, the code will log a warning and fall back to + 'v1'. - apiconfig: Mapping[str, str] | None - : A mapping with entries for `ARVADOS_API_HOST`, `ARVADOS_API_TOKEN`, and - optionally `ARVADOS_API_HOST_INSECURE`. If not provided, calls - `arvados.config.settings` to get these parameters from user configuration. + * apiconfig: Mapping[str, str] | None --- A mapping with entries for + `ARVADOS_API_HOST`, `ARVADOS_API_TOKEN`, and optionally + `ARVADOS_API_HOST_INSECURE`. If not provided, calls + `arvados.config.settings` to get these parameters from user + configuration. Other arguments are passed directly to `api_client`. See that function's docstring for more information about their meaning. diff --git a/sdk/python/arvados/retry.py b/sdk/python/arvados/retry.py index 2168146a4b..ea8a6f65af 100644 --- a/sdk/python/arvados/retry.py +++ b/sdk/python/arvados/retry.py @@ -49,34 +49,29 @@ class RetryLoop(object): Arguments: - num_retries: int - : The maximum number of times to retry the loop if it - doesn't succeed. This means the loop body could run at most + * num_retries: int --- The maximum number of times to retry the loop if + it doesn't succeed. This means the loop body could run at most `num_retries + 1` times. - success_check: Callable - : This is a function that will be called each - time the loop saves a result. The function should return - `True` if the result indicates the code succeeded, `False` if it - represents a permanent failure, and `None` if it represents a - temporary failure. If no function is provided, the loop will - end after any result is saved. - - backoff_start: float - : The number of seconds that must pass before the loop's second - iteration. Default 0, which disables all waiting. - - backoff_growth: float - : The wait time multiplier after each iteration. - Default 2 (i.e., double the wait time each time). - - save_results: int - : Specify a number to store that many saved results from the loop. - These are available through the `results` attribute, oldest first. - Default 1. - - max_wait: float - : Maximum number of seconds to wait between retries. Default 60. + * success_check: Callable --- This is a function that will be called + each time the loop saves a result. The function should return `True` + if the result indicates the code succeeded, `False` if it represents a + permanent failure, and `None` if it represents a temporary failure. + If no function is provided, the loop will end after any result is + saved. + + * backoff_start: float --- The number of seconds that must pass before + the loop's second iteration. Default 0, which disables all waiting. + + * backoff_growth: float --- The wait time multiplier after each + iteration. Default 2 (i.e., double the wait time each time). + + * save_results: int --- Specify a number to store that many saved + results from the loop. These are available through the `results` + attribute, oldest first. Default 1. + + * max_wait: float --- Maximum number of seconds to wait between + retries. Default 60. """ def __init__(self, num_retries, success_check=lambda r: True, backoff_start=0, backoff_growth=2, save_results=1, @@ -138,8 +133,8 @@ class RetryLoop(object): Arguments: - result: Any - : The result from this loop attempt to check and save. + * result: Any --- The result from this loop attempt to check and + save. """ if not self.running(): raise arvados.errors.AssertionError( @@ -207,8 +202,7 @@ def check_http_response_success(status_code): Arguments: - status_code: int - : A numeric HTTP response code + * status_code: int --- A numeric HTTP response code """ if status_code in _HTTP_SUCCESSES: return True @@ -229,8 +223,8 @@ def retry_method(orig_func): Arguments: - orig_func: Callable - : A class or instance method that accepts a `num_retries` keyword argument + * orig_func: Callable --- A class or instance method that accepts a + `num_retries` keyword argument """ @functools.wraps(orig_func) def num_retries_setter(self, *args, **kwargs): diff --git a/sdk/python/arvados/util.py b/sdk/python/arvados/util.py index 16f2999ca8..1ee5f6355a 100644 --- a/sdk/python/arvados/util.py +++ b/sdk/python/arvados/util.py @@ -74,16 +74,17 @@ def _deprecated(version=None, preferred=None): func_doc = re.sub(r'\n\s*$', '', func.__doc__ or '') match = re.search(r'\n([ \t]+)\S', func_doc) indent = '' if match is None else match.group(1) + warning_doc = f'\n\n{indent}.. WARNING:: Deprecated\n{indent} {warning_msg}' # Make the deprecation notice the second "paragraph" of the # docstring if possible. Otherwise append it. docstring, count = re.subn( rf'\n[ \t]*\n{indent}', - f'\n\n{indent}DEPRECATED: {warning_msg}\n\n{indent}', + f'{warning_doc}\n\n{indent}', func_doc, count=1, ) if not count: - docstring = f'{func_doc}\n\n{indent}DEPRECATED: {warning_msg}'.lstrip() + docstring = f'{func_doc.lstrip()}{warning_doc}' deprecated_wrapper.__doc__ = docstring return deprecated_wrapper return deprecated_decorator diff --git a/sdk/python/discovery2pydoc.py b/sdk/python/discovery2pydoc.py index 9f7f87d988..c827de5e86 100755 --- a/sdk/python/discovery2pydoc.py +++ b/sdk/python/discovery2pydoc.py @@ -49,8 +49,8 @@ _ALIASED_METHODS = frozenset([ ]) _DEPRECATED_NOTICE = ''' -!!! deprecated - This resource is deprecated in the Arvados API. +.. WARNING:: Deprecated + This resource is deprecated in the Arvados API. ''' _DEPRECATED_RESOURCES = frozenset([ 'Humans', -- 2.39.5