Module arvados.api

def api(version=None, cache=True, host=None, token=None, insecure=False,
        request_id=None, timeout=10, **kwargs):
    """Return an apiclient Resources object for an Arvados instance.

    :version:
      A string naming the version of the Arvados API to use (for
      example, 'v1').

    :cache:
      Use a cache (~/.cache/arvados/discovery) for the discovery
      document.

    :host:
      The Arvados API server host (and optional :port) to connect to.

    :token:
      The authentication token to send with each API call.

    :insecure:
      If True, ignore SSL certificate validation errors.

    :timeout:
      A timeout value for http requests.

    :request_id:
      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.

    Additional keyword arguments will be passed directly to
    `apiclient_discovery.build` if a new Resource object is created.
    If the `discoveryServiceUrl` or `http` keyword arguments are
    missing, this function will set default values for them, based on
    the current Arvados configuration settings.

    """

    if not version:
        version = 'v1'
        _logger.info("Using default API version. " +
                     "Call arvados.api('%s') instead." %
                     version)
    if 'discoveryServiceUrl' in kwargs:
        if host:
            raise ValueError("both discoveryServiceUrl and host provided")
        # Here we can't use a token from environment, config file,
        # etc. Those probably have nothing to do with the host
        # provided by the caller.
        if not token:
            raise ValueError("discoveryServiceUrl provided, but token missing")
    elif host and token:
        pass
    elif not host and not token:
        return api_from_config(
            version=version, cache=cache, request_id=request_id, **kwargs)
    else:
        # Caller provided one but not the other
        if not host:
            raise ValueError("token argument provided, but host missing.")
        else:
            raise ValueError("host argument provided, but token missing.")

    if host:
        # Caller wants us to build the discoveryServiceUrl
        kwargs['discoveryServiceUrl'] = (
            'https://%s/discovery/v1/apis/{api}/{apiVersion}/rest' % (host,))

    if 'http' not in kwargs:
        http_kwargs = {'ca_certs': util.ca_certs_path()}
        if cache:
            http_kwargs['cache'] = http_cache('discovery')
        if insecure:
            http_kwargs['disable_ssl_certificate_validation'] = True
        kwargs['http'] = httplib2.Http(**http_kwargs)

    if kwargs['http'].timeout is None:
        kwargs['http'].timeout = timeout

    kwargs['http'] = _patch_http_request(kwargs['http'], token)

    svc = apiclient_discovery.build('arvados', version, cache_discovery=False, **kwargs)
    svc.api_token = token
    svc.insecure = insecure
    svc.request_id = request_id
    svc.config = lambda: util.get_config_once(svc)
    kwargs['http'].max_request_size = svc._rootDesc.get('maxRequestSize', 0)
    kwargs['http'].cache = None
    kwargs['http']._request_id = lambda: svc.request_id or util.new_request_id()
    return svc

def api_from_config(version=None, apiconfig=None, **kwargs):
    """Return an apiclient Resources object enabling access to an Arvados server
    instance.

    :version:
      A string naming the version of the Arvados REST API to use (for
      example, 'v1').

    :apiconfig:
      If provided, this should be a dict-like object (must support the get()
      method) with entries for ARVADOS_API_HOST, ARVADOS_API_TOKEN, and
      optionally ARVADOS_API_HOST_INSECURE.  If not provided, use
      arvados.config (which gets these parameters from the environment by
      default.)

    Other keyword arguments such as `cache` will be passed along `api()`

    """
    # Load from user configuration or environment
    if apiconfig is None:
        apiconfig = config.settings()

    errors = []
    for x in ['ARVADOS_API_HOST', 'ARVADOS_API_TOKEN']:
        if x not in apiconfig:
            errors.append(x)
    if errors:
        raise ValueError(" and ".join(errors)+" not set.\nPlease set in %s or export environment variable." % config.default_config_file)
    host = apiconfig.get('ARVADOS_API_HOST')
    token = apiconfig.get('ARVADOS_API_TOKEN')
    insecure = config.flag_is_true('ARVADOS_API_HOST_INSECURE', apiconfig)

    return api(version=version, host=host, token=token, insecure=insecure, **kwargs)

def http_cache(data_type):
    homedir = os.environ.get('HOME')
    if not homedir or len(homedir) == 0:
        return None
    path = homedir + '/.cache/arvados/' + data_type
    try:
        util.mkdir_dash_p(path)
    except OSError:
        return None
    return cache.SafeHTTPCache(path, max_age=60*60*24*2)

class OrderedJsonModel(apiclient.model.JsonModel):
    """Model class for JSON that preserves the contents' order.

    API clients that care about preserving the order of fields in API
    server responses can use this model to do so, like this::

        from arvados.api import OrderedJsonModel
        client = arvados.api('v1', ..., model=OrderedJsonModel())
    """

    def deserialize(self, content):
        # This is a very slightly modified version of the parent class'
        # implementation.  Copyright (c) 2010 Google.
        content = content.decode('utf-8')
        body = json.loads(content, object_pairs_hook=collections.OrderedDict)
        if self._data_wrapper and isinstance(body, dict) and 'data' in body:
            body = body['data']
        return body