@sw-tsdk/plugin-connector 3.13.1 → 3.13.2-next.3dfd44a

package/lib/templates/swimlane/core/client.py

@@ -0,0 +1,466 @@
+"""Core Swimlane client class"""
+
+import logging
+
+import jwt
+import pendulum
+import requests
+import time
+from pyuri import URI
+from requests.compat import json
+from requests.packages import urllib3
+from requests.structures import CaseInsensitiveDict
+from requests.exceptions import ConnectionError
+from six.moves.urllib.parse import urljoin
+
+from swimlane.core.adapters import GroupAdapter, UserAdapter, AppAdapter, HelperAdapter
+from swimlane.core.cache import ResourcesCache
+from swimlane.core.resolver import SwimlaneResolver
+from swimlane.core.resources.usergroup import User
+from swimlane.exceptions import SwimlaneHTTP400Error, InvalidSwimlaneProductVersion
+from swimlane.utils.version import get_package_version, compare_versions
+from swimlane.core.wrappedsession import WrappedSession
+
+# Disable insecure request warnings
+urllib3.disable_warnings()
+
+logger = logging.getLogger(__name__)
+
+# pylint: disable=invalid-name
+_lib_full_version = get_package_version()
+_lib_major_version, _lib_minor_version = _lib_full_version.split('.')[0:2]
+
+
+class Swimlane(object):
+    """Swimlane API client
+
+    Core class used throughout library for all API requests and server interactions
+
+    Args:
+        host (str): Full RFC-1738 URL pointing to Swimlane host. Defaults will be provided for all parts
+        username (str): Authentication username
+        password (str): Authentication password
+        verify_ssl (bool): Verify SSL (ignored on HTTP). Disable to use self-signed certificates
+        default_timeout (int): Default request connect and read timeout in seconds for all requests
+        verify_server_version (bool): Verify server version has same major version as client package. May require
+            additional requests, set False to disable check
+        resource_cache_size (int): Maximum number of each resource type to keep in memory cache. Set 0 to disable
+            caching. Disabled by default
+        access_token (str): Authentication token, used in lieu of a username and password
+        write_to_read_only (bool): Enable the ability to write to Read-only fields
+        retry (bool): Retry request when error code is >= 500
+        max_retries (int): Maximum number of retry attempts
+        retry_interval (int): Time interval (in seconds) between two retry attempts
+
+    Attributes:
+        host (pyuri.URI): Full RFC-1738 URL pointing to Swimlane host
+        apps (AppAdapter): :class:`~swimlane.core.adapters.app.AppAdapter` configured for current Swimlane instance
+        users (UserAdapter): :class:`~swimlane.core.adapters.usergroup.UserAdapter` configured for current
+            Swimlane instance
+        groups (GroupAdapter): :class:`~swimlane.core.adapters.usergroup.GroupAdapter` configured for current
+            Swimlane instance
+        resources_cache (ResourcesCache): Cache checked by all supported adapters for current Swimlane instance
+
+    Examples:
+
+        ::
+
+            # Establish connection using username password
+            swimlane = Swimlane(
+                'https://192.168.1.1',
+                'username',
+                'password',
+                verify_ssl=False
+            )
+
+            # Or establish connection using personal access token
+            swimlane = Swimlane(
+                'https://192.168.1.1',
+                access_token='abcdefg',
+                verify_ssl=False
+            )
+
+            # Retrieve an app
+            app = swimlane.apps.get(name='Target App')
+
+    """
+
+    #_api_root = '/api/''
+    # Turbine variables
+    turbineAccountId = ""
+    turbineTenantId = ""
+    _api_root = f'/api/account/{turbineAccountId}/tenant/{turbineTenantId}/'
+    _execute_task_webhook_url = ""
+
+    def __init__(
+            self,
+            host,
+            username=None,
+            password=None,
+            verify_ssl=True,
+            default_timeout=60,
+            verify_server_version=True,
+            resource_cache_size=0,
+            access_token=None,
+            write_to_read_only: bool=False,
+            retry: bool=True,
+            max_retries: int=5,
+            retry_interval: int=5
+    ):
+        self.__verify_auth_params(username, password, access_token)
+
+        self.host = URI(host)
+        self.host.scheme = (self.host.scheme or 'https').lower()
+        self.host.path = None
+
+        self.resources_cache = ResourcesCache(resource_cache_size)
+
+        self.__settings = None
+        self.__user = None
+
+        self._write_to_read_only = write_to_read_only
+
+        self._default_timeout = default_timeout
+
+        self._session = WrappedSession()
+        self._session.verify = verify_ssl
+        
+        self.retry = retry
+        self.max_retries = max_retries
+        self.retry_interval = retry_interval
+
+        if username is not None and password is not None:
+            self._session.auth = SwimlaneJwtAuth(
+                self,
+                username,
+                password
+            )
+        else:
+            self._session.auth = SwimlaneTokenAuth(
+                self,
+                access_token
+            )
+
+        self.apps = AppAdapter(self)
+        self.users = UserAdapter(self)
+        self.groups = GroupAdapter(self)
+        self.helpers = HelperAdapter(self)
+
+        #if verify_server_version:
+        #    self.__verify_server_version()
+
+    @staticmethod
+    def __verify_auth_params(username, password, access_token):
+        """Verify that valid authentication parameters were passed to __init__"""
+
+        if all(v is not None for v in [username, password, access_token]):
+            raise ValueError('Cannot supply a username/password and a access token')
+
+        if (username is None or password is None) and access_token is None:
+            raise ValueError('Must supply a username/password or access token')
+
+    def __verify_server_version(self):
+        """Verify connected to supported server product version
+
+        Notes:
+            Logs warning if connecting to a newer minor server version
+
+        Raises:
+            swimlane.exceptions.InvalidServerVersion: If server major version is higher than package major version
+        """
+        if compare_versions('.'.join([_lib_major_version, _lib_minor_version]), self.product_version) > 0:
+            logger.warning('Client version {} connecting to server with newer minor release {}.'.format(
+                _lib_full_version,
+                self.product_version
+            ))
+
+        if compare_versions(_lib_major_version, self.product_version) != 0:
+            raise InvalidSwimlaneProductVersion(
+                self,
+                '{}.0'.format(_lib_major_version),
+                '{}.0'.format(str(int(_lib_major_version) + 1))
+            )
+
+    def __repr__(self):
+        return '<{cls}: {user} @ {host} v{version}>'.format(
+            cls=self.__class__.__name__,
+            user=self.user,
+            host=self.host,
+            version=self.version
+        )
+
+    def request(self, method, api_endpoint, **kwargs):
+        """Wrapper for underlying :class:`requests.Session`
+
+        Handles generating full API URL, session reuse and auth, request defaults, and invalid response status codes
+
+        Used throughout library as the core underlying request/response method for all interactions with server
+
+        Args:
+            method (str): Request method (get, post, put, etc.)
+            api_endpoint (str): Portion of URL matching API endpoint route as listed in platform /docs help page
+            **kwargs (dict): Remaining arguments passed through to actual request call
+
+        Notes:
+            All other provided kwargs are passed to underlying ``requests.Session.request()`` call
+
+        Raises:
+            swimlane.exceptions.SwimlaneHTTP400Error: On 400 responses with additional context about the exception
+            requests.HTTPError: Any other 4xx/5xx HTTP responses
+
+        Returns:
+            requests.Response: Successful response instances
+
+        Examples:
+
+            Request and parse server settings endpoint response
+
+            >>> server_settings = swimlane.request('get', 'settings').json()
+        """
+        while api_endpoint.startswith('/'):
+            api_endpoint = api_endpoint[1:]
+
+        # Ensure a timeout is set
+        kwargs.setdefault('timeout', self._default_timeout)
+
+        # Manually grab and dump json data to have full control over serialization
+        # Emulate default requests behavior
+        json_data = kwargs.pop('json', None)
+        if json_data is not None:
+            headers = CaseInsensitiveDict(kwargs.get('headers', {}))
+            headers.setdefault('Content-Type', 'application/json')
+            kwargs['headers'] = headers
+
+            kwargs['data'] = json.dumps(json_data, sort_keys=True, separators=(',', ':'))
+        
+        # Retry logic
+        req_retry = kwargs.pop('retry', self.retry)
+        
+        req_max_retries = kwargs.pop('max_retries', self.max_retries)
+        if not isinstance(req_max_retries, int):
+            raise TypeError('max_retries should be an integer')
+        if req_max_retries <= 0:
+            raise ValueError('max_retries should be a positive integer')
+        
+        req_retry_interval = kwargs.pop('retry_interval', self.retry_interval)
+        if not isinstance(req_retry_interval, int):
+            raise TypeError('retry_interval should be an integer')
+        if req_retry_interval <= 0:
+            raise ValueError('retry_interval should be a positive integer')
+        
+        while not req_max_retries<0:
+            if api_endpoint == 'tenant/api/users/login':
+                response = self._session.request(method, urljoin(str(self.host), api_endpoint), **kwargs)
+            else:
+                response = self._session.request(method, urljoin(str(self.host) + self._api_root, api_endpoint), **kwargs)
+
+            # Roll 400 errors up into SwimlaneHTTP400Errors with specific Swimlane error code support
+            try:
+                response.raise_for_status()
+                # Exit loop on successful request
+                req_max_retries = -1 
+            except requests.HTTPError as error:
+                if error.response.status_code == 400:
+                    raise SwimlaneHTTP400Error(error)
+                else:
+                    if req_retry and req_max_retries>0 and error.response.status_code>=500:
+                        req_max_retries -= 1
+                        time.sleep(req_retry_interval)
+                        continue
+                    elif req_max_retries == 0:
+                        raise ConnectionError(f'Max retries exceeded. Caused by ({error})')
+                    raise error
+
+        return response
+
+    @property
+    def settings(self):
+        """Retrieve and cache settings from server"""
+        if not self.__settings:
+            self.__settings = self.request('get', 'settings').json()
+        return self.__settings
+
+    @property
+    def version(self):
+        """Full Swimlane version, <product_version>+<build_version>+<build_number>"""
+        return self.settings['apiVersion']
+
+    @property
+    def product_version(self):
+        """Swimlane product version"""
+        version_separator = '+'
+        if version_separator in self.version:
+            # Post product/build version separation
+            return self.version.split(version_separator)[0]
+        # Pre product/build version separation
+        return self.version.split('-')[0]
+
+    @property
+    def build_version(self):
+        """Swimlane semantic build version
+
+        Falls back to product version in pre-2.18 releases
+        """
+        version_separator = '+'
+        if version_separator in self.version:
+            # Post product/build version separation
+            # This will handle <product_version>+<build_version>+<build_number>
+            # or <build_version>+<build_number> formats of the version
+            return self.version.split(version_separator)[-2]
+        # Pre product/build version separation
+        return self.product_version
+
+    @property
+    def build_number(self):
+        """Swimlane build number"""
+        version_separator = '+'
+        if version_separator in self.version:
+            # Post product/build version separation
+            return self.version.split(version_separator)[2]
+        # Pre product/build version separation
+        return self.version.split('-')[1]
+
+    @property
+    def user(self):
+        """User record instance for authenticated user"""
+        return self._session.auth.user
+
+
+class SwimlaneTokenAuth(SwimlaneResolver):
+    """Handles token authentication for all requests
+
+    .. versionadded:: 4.1.0
+    """
+
+    def __init__(self, swimlane, access_token):
+        super(SwimlaneTokenAuth, self).__init__(swimlane)
+
+        self._access_token = access_token
+        self.user = None
+    
+    def __call__(self, request):
+        """Attach necessary headers to all requests"""
+
+        headers = {
+            'Private-Token': self._access_token
+        }
+
+        request.headers.update(headers)
+
+        # Only make the call to user/authorize to get the user's profile if we haven't retrieved it
+        # already
+        if self.user is not None:
+            return request
+
+        # Temporarily remove auth from Swimlane session for auth request to avoid recursive loop during the request
+        self._swimlane._session.auth = None
+        resp = self._swimlane.request(
+            'get',
+            'user/authorize',
+            headers=headers
+        )
+        self._swimlane._session.auth = self
+        
+        json_content = resp.json()
+        self.user = User(self._swimlane, _user_raw_from_login_content(json_content))
+        
+        return request
+
+
+class SwimlaneJwtAuth(SwimlaneResolver):
+    """Handles authentication for all requests"""
+
+    _token_expiration_buffer = pendulum.Duration(minutes=5)
+
+    def __init__(self, swimlane, username, password):
+        super(SwimlaneJwtAuth, self).__init__(swimlane)
+
+        self._username = username
+        self._password = password
+
+        self.user = None
+        self._login_headers = {}
+        self._token_expiration = pendulum.now()
+
+    def __call__(self, request):
+        """Attach necessary headers to all requests
+
+        Automatically reauthenticate before sending request when nearing token expiration
+        """
+
+        # Refresh token if it expires soon
+        if pendulum.now() + self._token_expiration_buffer >= self._token_expiration:
+            self.authenticate()
+
+        request.headers.update(self._login_headers)
+
+        return request
+
+    def authenticate(self):
+        """Send login request and update User instance, login headers, and token expiration"""
+
+        # Temporarily remove auth from Swimlane session for auth request to avoid recursive loop during login request
+        self._swimlane._session.auth = None
+        resp = self._swimlane.request(
+            'post',
+            #'user/login',
+            '/tenant/api/users/login',
+            json={
+                'userName': self._username,
+                'password': self._password
+            },
+        )
+        self._swimlane._session.auth = self
+
+        # Get JWT from response content
+        json_content = resp.json()
+        token = json_content.pop('token', None)
+
+        # Grab token expiration
+        token_data = jwt.decode(token, algorithms=[''], options={'verify_signature': False})
+        token_expiration = pendulum.from_timestamp(token_data['exp'])
+
+        headers = {
+            'Authorization': 'Bearer {}'.format(token)
+        }
+
+        # Create User instance for authenticating user from login response data
+        user = User(self._swimlane, _user_raw_from_login_content(json_content))
+
+        self._login_headers = headers
+        self.user = user
+        self._token_expiration = token_expiration
+
+
+def _user_raw_from_login_content(login_content):
+    """Returns a User instance with appropriate raw data parsed from login response content"""
+    matching_keys = [
+        'displayName',
+        'lastLogin',
+        'active',
+        'name',
+        'isMe',
+        'lastPasswordChangedDate',
+        'passwordResetRequired',
+        'groups',
+        'roles',
+        'email',
+        'isAdmin',
+        'createdDate',
+        'modifiedDate',
+        'createdByUser',
+        'modifiedByUser',
+        'userName',
+        'id',
+        'disabled'
+    ]
+
+    raw_data = {
+        '$type': User._type,
+    }
+
+    for key in matching_keys:
+        if key in login_content:
+            raw_data[key] = login_content[key]
+
+    return raw_data

package/lib/templates/swimlane/core/cursor.py

@@ -0,0 +1,100 @@
+import itertools
+
+
+class Cursor(object):
+
+    def __init__(self):
+        self._elements = []
+
+    def __len__(self):
+        return len(list(self._evaluate()))
+
+    def __iter__(self):
+        for element in self._evaluate():
+            yield element
+
+    def __getitem__(self, item):
+        return self._evaluate()[item]
+
+    def _evaluate(self):
+        """Hook to allow lazy evaluation or retrieval of cursor's elements
+
+        Defaults to simply returning list of self._elements
+        """
+        return self._elements
+
+
+class PaginatedCursor(Cursor):
+    """Handle paginated lists, exposes hooks to simplify retrieval and parsing of paginated data"""
+
+    default_limit = 0
+    default_page_size = 10
+    default_page_start = None
+    default_page_end = None
+
+    def __init__(self, limit=default_limit, page_size=default_page_size,
+                 page_start=default_page_start, page_end=default_page_end):
+        super(PaginatedCursor, self).__init__()
+
+        self.__limit = limit
+        self.page_size = page_size
+        self.page_start = page_start
+        self.page_end = page_end
+
+        if self.__limit:
+            self.page_size = min(self.page_size, self.__limit)
+
+        if self.page_start and self.page_start <= 0:
+            raise ValueError('page_start should be greater than 0')
+
+        if self.page_end and self.page_end <= 0:
+            raise ValueError('page_end should be greater than 0')
+
+        if (self.page_start and self.page_end) and (self.page_start > self.page_end):
+            raise ValueError('page_end cannot be less than page_start')
+
+        if (self.page_start or self.page_end) and self.__limit != 0:
+            raise ValueError(' page_start or page_end param is applicable only when limit is 0')
+
+    def _evaluate(self):
+        """Lazily retrieve and paginate report results and build Record instances from returned data"""
+        if self._elements:
+            for element in self._elements:
+                yield element
+        else:
+            # Determine pagination range based on parameters
+            if self.page_start and self.page_end:
+                page_range = range(self.page_start-1, self.page_end)
+            elif self.page_start:
+                page_range = itertools.count(self.page_start-1)
+            elif self.page_end:
+                page_range = range(0, self.page_end)
+            else:
+                page_range = itertools.count()
+
+            for page in page_range:
+                raw_elements = self._retrieve_raw_elements(page)
+
+                for raw_element in raw_elements:
+                    element = self._parse_raw_element(raw_element)
+                    self._elements.append(element)
+                    yield element
+
+                    if self.__limit and len(self._elements) >= self.__limit:
+                        break
+
+                # Break conditions for ending pagination
+                if any([
+                    len(raw_elements) < self.page_size,
+                    self.__limit and len(self._elements) >= self.__limit,
+                    self.page_size == 0
+                ]):
+                    break
+
+    def _retrieve_raw_elements(self, page):
+        """Send request and return response for single page of data"""
+        raise NotImplementedError
+
+    def _parse_raw_element(self, raw_element):
+        """Hook to override parsing individual raw elements just before yielding"""
+        return raw_element

package/lib/templates/swimlane/core/fields/__init__.py

@@ -0,0 +1,46 @@
+"""Abstractions for Swimlane app field types to simplify getting/setting values on records"""
+
+from six import string_types as _string_types
+
+from swimlane.core.fields.base import Field
+from swimlane.utils import (
+    get_recursive_subclasses as _get_recursive_subclasses,
+    import_submodules as _import_submodules
+)
+
+_import_submodules(__name__)
+
+
+def _build_field_type_map(base_class):
+    """Create mapping from all $type values to their respective Field classes"""
+    mapping = {}
+
+    for cls in _get_recursive_subclasses(base_class):
+        if cls.field_type:
+            if isinstance(cls.field_type, tuple):
+                for field_type in cls.field_type:
+                    mapping[field_type] = cls
+            elif isinstance(cls.field_type, _string_types):
+                mapping[cls.field_type] = cls
+            else:
+                raise ValueError('Field type must be str or tuple, cannot understand type "{}" on class "{}"'.format(
+                    type(cls.field_type),
+                    cls
+                ))
+
+    return mapping
+
+
+_FIELD_TYPE_MAP = _build_field_type_map(Field)
+
+
+def resolve_field_class(field_definition):
+    """Return field class most fitting of provided Swimlane field definition"""
+    try:
+        return _FIELD_TYPE_MAP[field_definition['$type']]
+    except KeyError as error:
+        error.message = 'No field available to handle Swimlane $type "{}"'.format(field_definition)
+        raise
+
+
+__all__ = ['resolve_field_class'] + [f.__class__.__name__ for f in _FIELD_TYPE_MAP.values()]

package/lib/templates/swimlane/core/fields/attachment.py

@@ -0,0 +1,82 @@
+import io
+import mimetypes
+
+from swimlane.core.fields.base import MultiSelectField, FieldCursor
+from swimlane.core.resources.attachment import Attachment
+from swimlane.utils.str_validator import validate_str
+
+
+class AttachmentCursor(FieldCursor):
+    """Allows creation and iteration of attachments"""
+
+    def add(self, filename, stream, content_type=None):
+        """Upload a new attachment, and add it to current fields raw data to be persisted on save
+
+        Can optionally manually set the content_type, will be guessed by provided filename extension and default to 
+        application/octet-stream if it cannot be guessed
+        """
+        validate_str(filename, 'filename')
+        self.validate_stream(stream, 'stream')
+
+        # Guess file Content-Type or default
+        content_type = content_type or mimetypes.guess_type(
+            filename)[0] or 'application/octet-stream'
+        response = self._record._swimlane.request(
+            'post',
+            'attachment/{appId}/{fieldId}'.format(
+                appId=self._record.app.id, fieldId=self._field.id),
+            files={
+                'file': (filename, stream, content_type)
+            },
+        )
+
+        # Returns raw attachment data as list with single element
+        raw_attachment_data = response.json()[0]
+
+        attachment = Attachment(self._record._swimlane, raw_attachment_data, self._record.id, self._field.id)
+        self._elements.append(attachment)
+
+        self._sync_field()
+
+        return attachment
+
+
+    def validate_stream(self, stream, key):
+        if not isinstance(stream, io.IOBase):
+            raise ValueError('{} must be a stream value.'.format(key))
+
+
+class AttachmentsField(MultiSelectField):
+
+    field_type = (
+        'Core.Models.Fields.AttachmentField, Core',
+        'Core.Models.Fields.Attachment.AttachmentField, Core'
+    )
+    cursor_class = AttachmentCursor
+    supported_types = [Attachment]
+    bulk_modify_support = False
+
+    def __init__(self, *args, **kwargs):
+        """Override to force-set multiselect to always True"""
+        super(AttachmentsField, self).__init__(*args, **kwargs)
+        self.multiselect = True
+
+    def get_initial_elements(self):
+        raw_value = self.get_swimlane() or []
+
+        return [self.cast_to_python(raw) for raw in raw_value]
+
+    def get_batch_representation(self):
+        """Return best batch process representation of field value"""
+        return self.get_swimlane()
+
+    def _set(self, value):
+        """Override setter, allow clearing cursor"""
+        super(AttachmentsField, self)._set(value)
+        self._cursor = None
+
+    def cast_to_python(self, value):
+        return Attachment(self._swimlane, value, self.record.id, self.id)
+
+    def cast_to_swimlane(self, value):
+        return value._raw