sdk/python/arvados/__init__.py

   1 # Copyright (C) The Arvados Authors. All rights reserved.
   2 #
   3 # SPDX-License-Identifier: Apache-2.0
   4 """Arvados Python SDK
   5
   6 This module provides the entire Python SDK for Arvados. The most useful modules
   7 include:
   8
   9 * arvados.api - This module provides the `arvados.api.api` function to
  10   construct an Arvados REST API client, as well as other classes and functions
  11   that support it. You can call the `arvados.api` module just like a function
  12   as a shortcut for calling `arvados.api.api`.
  13
  14 * arvados.api_resources - The methods on an Arvados REST API client are
  15   generated dynamically at runtime. This module documents those methods and
  16   return values for the current version of Arvados. This module does not
  17   implement anything so you don't need to import it, but it's a helpful
  18   reference to understand how to use the Arvados REST API client.
  19
  20 * arvados.collection - The `arvados.collection.Collection` class provides a
  21   high-level interface to read and write collections. It coordinates sending
  22   data to and from Keep, and synchronizing updates with the collection object.
  23
  24 * arvados.util - Utility functions to use mostly in conjunction with the API
  25   client object and the results it returns.
  26
  27 Other submodules provide lower-level functionality.
  28 """
  29
  30 import logging as stdliblog
  31 import os
  32 import sys
  33 import types
  34
  35 from collections import UserDict
  36
  37 from . import api, errors, util
  38 from .api import api_from_config, http_cache
  39 from .collection import CollectionReader
  40 from arvados.keep import *
  41 from .logging import log_format, log_date_format, log_handler
  42 from .retry import RetryLoop
  43
  44 # Backwards compatibility shims: these modules used to get pulled in after
  45 # `import arvados` with previous versions of the SDK. We must keep the names
  46 # accessible even though there's no longer any functional need for them.
  47 from . import cache
  48 from . import safeapi
  49
  50 # Previous versions of the PySDK used to say `from .api import api`.  This
  51 # made it convenient to call the API client constructor, but difficult to
  52 # access the rest of the `arvados.api` module. The magic below fixes that
  53 # bug while retaining backwards compatibility: `arvados.api` is now the
  54 # module and you can import it normally, but we make that module callable so
  55 # all the existing code that says `arvados.api('v1', ...)` still works.
  56 class _CallableAPIModule(api.__class__):
  57     __call__ = staticmethod(api.api)
  58 api.__class__ = _CallableAPIModule
  59
  60 # Override logging module pulled in via `from ... import *`
  61 # so users can `import arvados.logging`.
  62 logging = sys.modules['arvados.logging']
  63
  64 # Set up Arvados logging based on the user's configuration.
  65 # All Arvados code should log under the arvados hierarchy.
  66 logger = stdliblog.getLogger('arvados')
  67 logger.addHandler(log_handler)
  68 logger.setLevel(stdliblog.DEBUG if config.get('ARVADOS_DEBUG')
  69                 else stdliblog.WARNING)