X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/df893c906a6387ade4767425ad8c68e2289ca359..f65d320d9f4dda35dcf90c294c494b059b4c36a6:/sdk/python/arvados/api.py diff --git a/sdk/python/arvados/api.py b/sdk/python/arvados/api.py index d2a705b903..8a17e42fcb 100644 --- a/sdk/python/arvados/api.py +++ b/sdk/python/arvados/api.py @@ -9,12 +9,7 @@ niceties such as caching, X-Request-Id header for tracking, and more. The main client constructors are `api` and `api_from_config`. """ -from __future__ import absolute_import -from future import standard_library -standard_library.install_aliases() -from builtins import range import collections -import http.client import httplib2 import json import logging @@ -28,6 +23,14 @@ import threading import time import types +from typing import ( + Any, + Dict, + List, + Mapping, + Optional, +) + import apiclient import apiclient.http from apiclient import discovery as apiclient_discovery @@ -43,13 +46,12 @@ _logger = logging.getLogger('arvados.api') _googleapiclient_log_lock = threading.Lock() MAX_IDLE_CONNECTION_DURATION = 30 - -# These constants supported our own retry logic that we've since removed in -# favor of using googleapiclient's num_retries. They're kept here purely for -# API compatibility, but set to 0 to indicate no retries happen. -RETRY_DELAY_INITIAL = 0 -RETRY_DELAY_BACKOFF = 0 -RETRY_COUNT = 0 +""" +Number of seconds that API client HTTP connections should be allowed to idle +in keepalive state before they are forced closed. Client code can adjust this +constant, and it will be used for all Arvados API clients constructed after +that point. +""" # An unused HTTP 5xx status code to request a retry internally. # See _intercept_http_request. This should not be user-visible. @@ -58,25 +60,6 @@ _RETRY_4XX_STATUS = 545 if sys.version_info >= (3,): httplib2.SSLHandshakeError = None -class OrderedJsonModel(apiclient.model.JsonModel): - """Model class for JSON that preserves the contents' order. - - .. WARNING:: Deprecated - This model is redundant now that Python dictionaries preserve insertion - ordering. Code that passes this model to API constructors can remove it. - - In Python versions before 3.6, API clients that cared about preserving the - order of fields in API server responses could use this model to do so. - Typical usage looked like: - - from arvados.api import OrderedJsonModel - client = arvados.api('v1', ..., model=OrderedJsonModel()) - """ - @util._deprecated(preferred="the default model and rely on Python's built-in dictionary ordering") - def __init__(self, data_wrapper=False): - return super().__init__(data_wrapper) - - _orig_retry_request = apiclient.http._retry_request def _retry_request(http, num_retries, *args, **kwargs): try: @@ -172,7 +155,19 @@ def _new_http_error(cls, *args, **kwargs): errors.ApiError, *args, **kwargs) apiclient_errors.HttpError.__new__ = staticmethod(_new_http_error) -def http_cache(data_type): +def http_cache(data_type: str) -> cache.SafeHTTPCache: + """Set up an HTTP file cache + + This function constructs and returns an `arvados.cache.SafeHTTPCache` + backed by the filesystem under `~/.cache/arvados/`, or `None` if the + directory cannot be set up. The return value can be passed to + `httplib2.Http` as the `cache` argument. + + Arguments: + + * data_type: str --- The name of the subdirectory under `~/.cache/arvados` + where data is cached. + """ try: homedir = pathlib.Path.home() except RuntimeError: @@ -185,18 +180,18 @@ def http_cache(data_type): return cache.SafeHTTPCache(str(path), max_age=60*60*24*2) def api_client( - version, - discoveryServiceUrl, - token, + version: str, + discoveryServiceUrl: str, + token: str, *, - cache=True, - http=None, - insecure=False, - num_retries=10, - request_id=None, - timeout=5*60, - **kwargs, -): + cache: bool=True, + http: Optional[httplib2.Http]=None, + insecure: bool=False, + num_retries: int=10, + request_id: Optional[str]=None, + timeout: int=5*60, + **kwargs: Any, +) -> apiclient_discovery.Resource: """Build an Arvados API client This function returns a `googleapiclient.discovery.Resource` object @@ -240,7 +235,6 @@ def api_client( Additional keyword arguments will be passed directly to `googleapiclient.discovery.build`. - """ if http is None: http = httplib2.Http( @@ -302,12 +296,12 @@ def api_client( return svc def normalize_api_kwargs( - version=None, - discoveryServiceUrl=None, - host=None, - token=None, - **kwargs, -): + version: Optional[str]=None, + discoveryServiceUrl: Optional[str]=None, + host: Optional[str]=None, + token: Optional[str]=None, + **kwargs: Any, +) -> Dict[str, Any]: """Validate kwargs from `api` and build kwargs for `api_client` This method takes high-level keyword arguments passed to the `api` @@ -360,7 +354,11 @@ def normalize_api_kwargs( **kwargs, } -def api_kwargs_from_config(version=None, apiconfig=None, **kwargs): +def api_kwargs_from_config( + version: Optional[str]=None, + apiconfig: Optional[Mapping[str, str]]=None, + **kwargs: Any +) -> Dict[str, Any]: """Build `api_client` keyword arguments from configuration This function accepts a mapping with Arvados configuration settings like @@ -403,9 +401,18 @@ def api_kwargs_from_config(version=None, apiconfig=None, **kwargs): **kwargs, ) -def api(version=None, cache=True, host=None, token=None, insecure=False, - request_id=None, timeout=5*60, *, - discoveryServiceUrl=None, **kwargs): +def api( + version: Optional[str]=None, + cache: bool=True, + host: Optional[str]=None, + token: Optional[str]=None, + insecure: bool=False, + request_id: Optional[str]=None, + timeout: int=5*60, + *, + discoveryServiceUrl: Optional[str]=None, + **kwargs: Any, +) -> 'arvados.safeapi.ThreadSafeApiCache': """Dynamically build an Arvados API client This function provides a high-level "do what I mean" interface to build an @@ -457,7 +464,11 @@ def api(version=None, cache=True, host=None, token=None, insecure=False, from .safeapi import ThreadSafeApiCache return ThreadSafeApiCache({}, {}, kwargs, version) -def api_from_config(version=None, apiconfig=None, **kwargs): +def api_from_config( + version: Optional[str]=None, + apiconfig: Optional[Mapping[str, str]]=None, + **kwargs: Any +) -> 'arvados.safeapi.ThreadSafeApiCache': """Build an Arvados API client from a configuration mapping This function builds an Arvados API client from a mapping with user @@ -485,3 +496,49 @@ def api_from_config(version=None, apiconfig=None, **kwargs): docstring for more information about their meaning. """ return api(**api_kwargs_from_config(version, apiconfig, **kwargs)) + +class OrderedJsonModel(apiclient.model.JsonModel): + """Model class for JSON that preserves the contents' order + + .. WARNING:: Deprecated + This model is redundant now that Python dictionaries preserve insertion + ordering. Code that passes this model to API constructors can remove it. + + In Python versions before 3.6, API clients that cared about preserving the + order of fields in API server responses could use this model to do so. + Typical usage looked like: + + from arvados.api import OrderedJsonModel + client = arvados.api('v1', ..., model=OrderedJsonModel()) + """ + @util._deprecated(preferred="the default model and rely on Python's built-in dictionary ordering") + def __init__(self, data_wrapper=False): + return super().__init__(data_wrapper) + + +RETRY_DELAY_INITIAL = 0 +""" +.. WARNING:: Deprecated + This constant was used by retry code in previous versions of the Arvados SDK. + Changing the value has no effect anymore. + Prefer passing `num_retries` to an API client constructor instead. + Refer to the constructor docstrings for details. +""" + +RETRY_DELAY_BACKOFF = 0 +""" +.. WARNING:: Deprecated + This constant was used by retry code in previous versions of the Arvados SDK. + Changing the value has no effect anymore. + Prefer passing `num_retries` to an API client constructor instead. + Refer to the constructor docstrings for details. +""" + +RETRY_COUNT = 0 +""" +.. WARNING:: Deprecated + This constant was used by retry code in previous versions of the Arvados SDK. + Changing the value has no effect anymore. + Prefer passing `num_retries` to an API client constructor instead. + Refer to the constructor docstrings for details. +"""