flywheel-sdk 21.2.0__py3-none-any.whl

flywheel/client.py

@@ -0,0 +1,291 @@
+import json
+import os
+import sys
+
+from .util import params_to_dict
+from .flywheel import Flywheel
+from .view_builder import ViewBuilder
+from .rest import ApiException
+
+def get_api_key_from_cli(path):
+    try:
+        with open(path) as fp:
+            api_key = json.load(fp).get('key')
+    except FileNotFoundError:
+        raise Exception('Must login with flywheel command-line interface')
+    return api_key
+
+class Client(object):
+    def __init__(self, api_key=None, **kwargs):
+        """Initialize Flywheel Client
+
+        Note: If you are initializing the client with a drone or device key,
+        you will need to set disable_auth_check to True
+
+        Args:
+            api_key: API key to Flywheel
+            kwargs: Other keyword arguments
+                disable_auth_check (bool): Disable authentication check. 
+                    Default False.
+
+        Returns:
+            Initialized Flywheel Client
+
+        Raises:
+            flywheel.rest.ApiException: If disable_auth_check is False and 
+                authentication fails.
+        """
+        if not api_key:
+            api_key = get_api_key_from_cli(os.path.expanduser('~/.config/flywheel/user.json'))
+        disable_auth_check = kwargs.pop('disable_auth_check', False)
+
+        self._fw = Flywheel(api_key, minimum_supported_major_version=11,
+                            **kwargs)
+
+        if not disable_auth_check:
+            self._fw.get_auth_status()
+
+
+    def shutdown(self):
+        """Release any outstanding resources"""
+        self._fw.shutdown()
+
+    def add_user(self, *args, **kwargs):  # noqa: E501
+        """Add a new user"""
+        body = params_to_dict('add_user', args, kwargs)
+        return self._fw.add_user(body)
+
+    def add_group(self, *args, **kwargs):
+        """Add a group"""
+        body = params_to_dict('add_group', args, kwargs)
+        return self._fw.add_group(body)
+
+    def add_collection(self, *args, **kwargs):
+        """Create a collection"""
+        body = params_to_dict('add_collection', args, kwargs)
+        return self._fw.add_collection(body, **kwargs)
+
+    def add_gear(self, gear_name, body, **kwargs):
+        """Create or update a gear.
+
+        If no existing gear is found, one will be created Otherwise, the specified gear will be updated
+
+        :param str gear_name: Name of the gear to interact with (required)
+        :param GearDocumentLegacyInput body: (required)
+        :param bool async_: Perform the request asynchronously
+        :return: GearDocument
+        """
+        return self._fw.add_gear(gear_name, body, **kwargs)
+
+    def add_job(self, body, **kwargs):
+        """Add a job
+
+        :param Job body: (required)
+        :return: CommonObjectCreated
+        """
+        return self._fw.add_job(body, **kwargs)
+
+    def get_config(self, **kwargs):
+        """Return public Scitran configuration information
+
+        :return: ConfigOut
+        """
+        return self._fw.get_config(**kwargs)
+
+    def get_gear(self, gear_id, **kwargs):
+        """Return a gear referenced by gear_id
+
+        :param str gear_id: (required) The id of the gear to lookup
+        :return: Gear
+        """
+        return self._fw.get_gear(gear_id, **kwargs)
+
+    def get_version(self, **kwargs):
+        """Get server and database schema version info
+
+        :return: VersionOutput
+        """
+        return self._fw.get_version(**kwargs)
+
+    def get_current_user(self, **kwargs):
+        """Get current logged-in user
+
+        :return: User
+        """
+        return self._fw.get_current_user(**kwargs)
+
+    def get_modality(self, modality_id, **kwargs):
+        """Get a modality's classification specification
+
+        :param str modality_id: (required)
+        :return: Modality
+        """
+        return self._fw.get_modality(modality_id, **kwargs)
+
+    def get(self, id, **kwargs):
+        """Retrieve the specified object by id.
+
+        Objects that can be retrieved in this way are:
+            group, project, session, subject, acquisition, analysis and collection
+
+        :param str id: The id of the object to retrieve
+        :return: ContainerOutput
+        """
+        return self._fw.get(id, **kwargs)
+
+    def resolve(self, path):
+        """Perform a path based lookup of nodes in the Flywheel hierarchy.
+
+        :param str path: (required) The path to resolve
+        :return: ResolverOutput
+        """
+        return self._fw.resolve(path)
+
+    def lookup(self, path):
+        """Perform a path based lookup of a single node in the Flywheel hierarchy.
+
+        :param str path: (required) The path to resolve
+        :return: ResolverOutput
+        """
+        return self._fw.lookup(path)
+
+    def file_url(self, path):
+        """Perform a path based lookup of a file in the Flywheel hierarchy, and return a single-use download URL.
+
+        :param str path: (required) The path to resolve
+        :return: The file URL if found, otherwise raises an error
+        """
+        return self._fw.file_url(path)
+
+    def download_tar(self, containers, dest_file, include_types=None, exclude_types=None):
+        """Download the given set of containers as a tarball to dest_file.
+
+        Supports downloading Projects, Sessions, Acquisitions and/or Analyses.
+
+        :param containers: (required) The container, or list of containers to download.
+        :param str dest_file: (required) The destination file on disk
+        :param list include_types: The optional list of types to include in the download (e.g. ['nifti'])
+        :param list exclude_types: The optional list of types to exclude from the download (e.g. ['dicom'])
+        :return: A summary of the download
+        """
+        return self._fw.download_tar(containers, dest_file, include_types=include_types, exclude_types=exclude_types)
+
+    def download_zip(self, containers, dest_file, include_types=None, exclude_types=None):
+        """Download the given set of containers as a zip archive to dest_file.
+
+        Supports downloading Projects, Sessions, Acquisitions and/or Analyses.
+
+        :param containers: (required) The container, or list of containers to download.
+        :param str dest_file: (required) The destination file on disk
+        :param list include_types: The optional list of types to include in the download (e.g. ['nifti'])
+        :param list exclude_types: The optional list of types to exclude from the download (e.g. ['dicom'])
+        :return: A summary of the download
+        """
+        return self._fw.download_zip(containers, dest_file, include_types=include_types, exclude_types=exclude_types)
+
+    @property
+    def users(self):
+        """Returns the users finder object"""
+        return self._fw.users
+
+    @property
+    def groups(self):
+        """Returns the groups finder object"""
+        return self._fw.groups
+
+    @property
+    def projects(self):
+        """Returns the projects finder object"""
+        return self._fw.projects
+
+    @property
+    def subjects(self):
+        """Returns the subjects finder object"""
+        return self._fw.subjects
+
+    @property
+    def sessions(self):
+        """Returns the sessions finder object"""
+        return self._fw.sessions
+
+    @property
+    def acquisitions(self):
+        """Returns the acquisitions finder object"""
+        return self._fw.acquisitions
+
+    @property
+    def jobs(self):
+        """Returns the jobs finder object"""
+        return self._fw.jobs
+
+    @property
+    def gears(self):
+        """Returns the gears finder object"""
+        return self._fw.gears
+
+    @property
+    def collections(self):
+        """Returns the collections finder object"""
+        return self._fw.collections
+
+    @property
+    def data_view_executions(self):
+        """Returns the data_view_executions finder object"""
+        return self._fw.data_view_executions
+
+    def View(self, **kwargs):
+        """Short-hand for ``flywheel.ViewBuilder(**kwargs).build()``
+
+        :param kwargs: The arguments to pass directly to ViewBuilder
+        :return: The built data view
+        """
+        return ViewBuilder(**kwargs).build()
+
+    def print_view_columns(self, file=sys.stdout):
+        """Print a list of column aliases that can be used in data views.
+
+        :param file-like file: The file to print to
+        """
+        return self._fw.print_view_columns(file=file)
+
+    def read_view_data(self, view, container_id, decode=True, **kwargs):
+        """Execute a data view against container, and return a file-like object that can be streamed.
+
+        :param view: The view id or DataView object to execute.
+        :type view: str or DataView
+        :param str container_id: The id of the container to execute the view against
+        :param bool decode: Whether or not to decode the stream to utf-8 (default is true)
+        :param kwargs: Additional arguments to pass to the evaluate_view call. (e.g. format='csv')
+        :return: A file-like object where the contents can be read
+        """
+        return self._fw.read_view_data(view, container_id, decode=decode, **kwargs)
+
+    def read_view_dataframe(self, view, container_id, opts=None, **kwargs):
+        """Execute a data view against container, and return a DataFrame.
+
+        NOTE: This requires that the pandas module be installed on the system.
+
+        :param view: The view id or DataView object to execute.
+        :type view: str or DataView
+        :param str container_id: The id of the container to execute the view against
+        :param object opts: Additional options to pass to the pandas read_json function
+        :param kwargs: Additional arguments to pass to the evaluate_view call.
+        :return: A pandas DataFrame
+        """
+        return self._fw.read_view_dataframe(view, container_id, opts=opts, **kwargs)
+
+
+    def save_view_data(self, view, container_id, dest_file, **kwargs):
+        """Execute a data view against container, and save the results to disk.
+
+        :param view: The view id or DataView object to execute.
+        :type view: str or DataView
+        :param str container_id: The id of the container to execute the view against
+        :param str dest_file: The destination file path
+        :param kwargs: Additional arguments to pass to the evaluate_view call. (e.g. format='csv')
+        """
+        return self._fw.save_view_data(view, container_id, dest_file, **kwargs)
+
+    def __getattr__(self, name):
+        # By default return flywheel attributes, but don't auto-complete them
+        return getattr(self._fw, name)

flywheel/configuration.py

@@ -0,0 +1,308 @@
+# coding: utf-8
+
+"""
+    Flywheel
+
+    No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)  # noqa: E501
+
+    OpenAPI spec version: 0.0.1
+    
+    Generated by: https://github.com/swagger-api/swagger-codegen.git
+"""
+
+
+from __future__ import absolute_import
+
+import copy
+import logging
+import multiprocessing
+import sys
+import urllib3
+
+import six
+from six.moves import http_client as httplib
+
+
+class TypeWithDefault(type):
+    def __init__(cls, name, bases, dct):
+        super(TypeWithDefault, cls).__init__(name, bases, dct)
+        cls._default = None
+
+    def __call__(cls):
+        if cls._default is None:
+            cls._default = type.__call__(cls)
+        return copy.copy(cls._default)
+
+    def set_default(cls, default):
+        cls._default = copy.copy(default)
+
+
+class Configuration(six.with_metaclass(TypeWithDefault, object)):
+    """NOTE: This class is auto generated by the swagger code generator program.
+
+    Ref: https://github.com/swagger-api/swagger-codegen
+    Do not edit the class manually.
+    """
+
+    def __init__(self):
+        """Constructor"""
+        # Property defaults
+        self.__debug = False
+        self.__logger_file = None
+        self.__logger_format = None
+        self.logger_formatter = None
+        self.__logging_filters = list()
+
+        # Default Base url
+        self.host = "https://dev.flywheel.io/api"
+        # Temp file folder for downloading files
+        self.temp_folder_path = None
+
+        # Authentication Settings
+        # dict to store API key(s)
+        self.api_key = {}
+        # dict to store API prefix (e.g. Bearer)
+        self.api_key_prefix = {}
+        # Username for HTTP basic authentication
+        self.username = ""
+        # Password for HTTP basic authentication
+        self.password = ""
+        # Logging Settings
+        self.logger = {}
+        self.logger["package_logger"] = logging.getLogger("flywheel")
+        self.logger["urllib3_logger"] = logging.getLogger("urllib3")
+        self.logger["http_client_logger"] = logging.getLogger("http.client")
+        # Log format
+        self.logger_format = '%(asctime)s %(levelname)s %(message)s'
+        # Log stream handler
+        self.logger_stream_handler = None
+        # Log file handler
+        self.logger_file_handler = None
+        # Debug file location
+        self.logger_file = None
+        # Debug switch
+        self.debug = False
+
+        # SSL/TLS verification
+        # Set this to false to skip verifying SSL certificate when calling API
+        # from https server.
+        self.verify_ssl = True
+        # Set this to customize the certificate file to verify the peer.
+        self.ssl_ca_cert = None
+        # client certificate file
+        self.cert_file = None
+        # client key file
+        self.key_file = None
+        # Set this to True/False to enable/disable SSL hostname verification.
+        self.assert_hostname = None
+
+        # urllib3 connection pool's maximum number of connections saved
+        # per pool. urllib3 uses 1 connection as default value, but this is
+        # not the best value when you are making a lot of possibly parallel
+        # requests to the same host, which is often the case here.
+        # cpu_count * 5 is used as default value to increase performance.
+        self.connection_pool_maxsize = multiprocessing.cpu_count() * 5
+
+        # Proxy URL
+        self.proxy = None
+        # Safe chars for path_param
+        self.safe_chars_for_path_param = ''
+
+    @property
+    def logger_file(self):
+        """The logger file.
+
+        If the logger_file is None, then add stream handler and remove file
+        handler. Otherwise, add file handler and remove stream handler.
+
+        :param value: The logger_file path.
+        :type: str
+        """
+        return self.__logger_file
+
+    @logger_file.setter
+    def logger_file(self, value):
+        """The logger file.
+
+        If the logger_file is None, then add stream handler and remove file
+        handler. Otherwise, add file handler and remove stream handler.
+
+        :param value: The logger_file path.
+        :type: str
+        """
+        self.__logger_file = value
+        if self.__logger_file:
+            # If set logging file,
+            # then add file handler and remove stream handler.
+            self.logger_file_handler = logging.FileHandler(self.__logger_file)
+            self.logger_file_handler.setFormatter(self.logger_formatter)
+            for _, logger in six.iteritems(self.logger):
+                logger.addHandler(self.logger_file_handler)
+                if self.logger_stream_handler:
+                    logger.removeHandler(self.logger_stream_handler)
+        else:
+            # If not set logging file,
+            # then add stream handler and remove file handler.
+            self.logger_stream_handler = logging.StreamHandler()
+            self.logger_stream_handler.setFormatter(self.logger_formatter)
+            for _, logger in six.iteritems(self.logger):
+                logger.addHandler(self.logger_stream_handler)
+                if self.logger_file_handler:
+                    logger.removeHandler(self.logger_file_handler)
+
+    @property
+    def debug(self):
+        """Debug status
+
+        :param value: The debug status, True or False.
+        :type: bool
+        """
+        return self.__debug
+
+    @debug.setter
+    def debug(self, value):
+        """Debug status
+
+        :param value: The debug status, True or False.
+        :type: bool
+        """
+        self.__debug = value
+        if self.__debug:
+            # if debug status is True, turn on debug logging
+            for _, logger in six.iteritems(self.logger):
+                logger.setLevel(logging.DEBUG)
+            # turn on httplib debug
+            httplib.HTTPConnection.debuglevel = 1
+            httpclient_logger = self.logger["http_client_logger"]
+            httplib.print = lambda *args: httpclient_logger.log(
+                logging.DEBUG, " ".join(map(str, args)))
+        else:
+            # if debug status is False, turn off debug logging,
+            # setting log level to default `logging.WARNING`
+            for _, logger in six.iteritems(self.logger):
+                logger.setLevel(logging.WARNING)
+            # turn off httplib debug
+            httplib.HTTPConnection.debuglevel = 0
+            if hasattr(httplib, "print"):
+                delattr(httplib, "print")
+
+    @property
+    def logger_format(self):
+        """The logger format.
+
+        The logger_formatter will be updated when sets logger_format.
+
+        :param value: The format string.
+        :type: str
+        """
+        return self.__logger_format
+
+    @logger_format.setter
+    def logger_format(self, value):
+        """The logger format.
+
+        The logger_formatter will be updated when sets logger_format.
+
+        :param value: The format string.
+        :type: str
+        """
+        self.__logger_format = value
+        self.logger_formatter = logging.Formatter(self.__logger_format)
+
+    def get_api_key_with_prefix(self, identifier):
+        """Gets API key (with prefix if set).
+
+        :param identifier: The identifier of apiKey.
+        :return: The token for api key authentication.
+        """
+        if (self.api_key.get(identifier) and
+                self.api_key_prefix.get(identifier)):
+            return self.api_key_prefix[identifier] + ' ' + self.api_key[identifier]  # noqa: E501
+        elif self.api_key.get(identifier):
+            return self.api_key[identifier]
+
+    def get_basic_auth_token(self):
+        """Gets HTTP basic authentication header (string).
+
+        :return: The token for basic HTTP authentication.
+        """
+        return urllib3.util.make_headers(
+            basic_auth=self.username + ':' + self.password
+        ).get('authorization')
+
+    def auth_settings(self):
+        """Gets Auth Settings dict for api client.
+
+        :return: The Auth Settings information dict.
+        """
+        return {
+            'ApiKey':
+                {
+                    'type': 'api_key',
+                    'in': 'header',
+                    'key': 'Authorization',
+                    'value': self.get_api_key_with_prefix('Authorization')
+                },
+        }
+
+    def to_debug_report(self):
+        """Gets the essential information for debugging.
+
+        :return: The report for debugging.
+        """
+        return "Python SDK Debug Report:\n"\
+               "OS: {env}\n"\
+               "Python Version: {pyversion}\n"\
+               "Version of the API: 21.2.0\n"\
+               "SDK Package Version: 21.2.0".\
+               format(env=sys.platform, pyversion=sys.version)
+
+    def enable_message_cutoff(self, message_cutoff):
+        self.__logging_filters[:] = []
+
+        class SendFilter(logging.Filter):
+            def __init__(self, cutoff):
+                self.cutoff = cutoff
+
+            def filter(self, record):
+                # http.client lib doesn't use formatting strings
+                if record.msg.startswith("send: b'") and record.msg.endswith("'"):
+                    data = record.msg[8:-1].encode("utf8").decode("unicode_escape")
+                    data_len = len(data)
+                    if data_len > self.cutoff:
+                        first_part = data[:(self.cutoff//2)]
+                        last_part = data[-(self.cutoff//2):]
+                        shortened = f"{first_part}...[{data_len} bytes total]...{last_part}"
+                        shortened_bytes = shortened.encode("utf8")
+                        record.msg = f"send: {shortened_bytes!r}"
+                return True
+
+        filt = SendFilter(message_cutoff)
+        logger = logging.getLogger("http.client")
+        logger.addFilter(filt)
+        self.__logging_filters.append((logger, filt))
+
+        class ReceiveFilter(logging.Filter):
+            def __init__(self, cutoff):
+                self.cutoff = cutoff
+
+            def filter(self, record):
+                if record.msg == "response body: %s" and len(record.args) == 1:
+                    body = record.args[0]
+                    body_len = len(body)
+                    if body_len > self.cutoff:
+                        first_part = body[:(self.cutoff//2)]
+                        last_part = body[-(self.cutoff//2):]
+                        shortened = f"{first_part}...[{body_len} bytes total]...{last_part}"
+                        record.args = (shortened,)
+                return True
+
+        filt = ReceiveFilter(message_cutoff)
+        logger = logging.getLogger("flywheel.rest")
+        logger.addFilter(filt)
+        self.__logging_filters.append((logger, filt))
+
+    def disable_message_cutoff(self):
+        for logger, filt in self.__logging_filters:
+            logger.removeFilter(filt)
+        self.__logging_filters[:] = []

flywheel/drone_login.py

@@ -0,0 +1,65 @@
+"""Provides Drone-based login credentials"""
+
+import requests
+
+from . import util
+from .client import Client
+from .rest import ApiException
+
+
+def create_drone_client(host, secret, method, name, port=443, **kwargs):
+    """Create a Client instance using drone credentials.
+
+    :param str host: The hostname of the flywheel instance
+    :param str secret: The drone secret
+    :param str method: The method (device type)
+    :param str name: The name of the device
+    :param int port: The optional port (if not 443)
+    :param kwargs: Additional arguments to pass to the created Client instance
+    :return: The authorized Client instance
+    :rtype: flywheel.Client
+    """
+    with requests.Session() as session:
+        util.set_verify_ssl(session)
+
+        # Get auth status to determine device id
+        force_insecure = kwargs.pop("_force_insecure", False) is True
+        if force_insecure:
+            base_uri = "http://{}:{}/api".format(host, port)
+        else:
+            base_uri = "https://{}:{}/api".format(host, port)
+
+        session.headers.update(
+            {
+                "X-SciTran-Auth": secret,
+                "X-SciTran-Method": method,
+                "X-SciTran-Name": name,
+            }
+        )
+
+        # Get the status
+        resp = session.get(base_uri + "/auth/status")
+        if not resp.ok:
+            raise ApiException(http_resp=resp)
+
+        status = resp.json()
+        if not status["is_device"] or not status.get("origin", {}).get("id"):
+            raise RuntimeError("Provided login is not a device login")
+
+        # Get the device, with API key
+        device_id = status["origin"]["id"]
+        resp = session.get(base_uri + "/devices/" + device_id)
+        if not resp.ok:
+            raise ApiException(http_resp=resp)
+
+        device = resp.json()
+        if "key" not in device:
+            raise RuntimeError("Got device, but could not get key!")
+
+        # NOTE: _force_insecure is not recommended nor supported for general consumption
+        if force_insecure:
+            api_key = "{}:{}:__force_insecure:{}".format(host, port, device["key"])
+        else:
+            api_key = "{}:{}:{}".format(host, port, device["key"])
+
+    return Client(api_key, **kwargs)