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

package/lib/templates/swimlane/core/resources/report.py

@@ -0,0 +1,259 @@
+import pendulum
+import json 
+
+
+from swimlane.core.cursor import PaginatedCursor
+from swimlane.core.fields.list import ListField
+from swimlane.core.resources.base import APIResource
+from swimlane.core.resources.record import Record, record_factory
+from swimlane.core.search import CONTAINS, EQ, EXCLUDES, NOT_EQ, LT, GT, LTE, GTE, ASC, DESC
+from swimlane.utils import validate_type
+
+ALLOWED_OPERATORS = ['Or', 'And']
+
+
+class Report(APIResource, PaginatedCursor):
+    """A report class used for searching
+
+    Can be iterated over to retrieve results
+
+    Notes:
+        Record retrieval is lazily evaluated and cached internally, adding a filter and attempting to iterate again will
+        not respect the additional filter and will return the same set of records each time
+
+    Examples:
+
+        Lazy retrieval of records with direct iteration over report
+
+        ::
+
+            report = app.reports.build('new-report')
+            report.filter('field_1', 'equals', 'value')
+
+            for record in report:
+                do_thing(record)
+
+        Full immediate retrieval of all records
+
+        ::
+
+            report = app.reports.build('new-report')
+            report.filter('field_1', 'doesNotEqual', 'value')
+
+            records = list(report)
+
+
+    Attributes:
+        name (str): Report name
+
+    Keyword Args:
+        limit (int): Max number of records to return from report/search
+        page_size (int): Max number of records per page
+        keywords (list(str)): List of keywords to use in report/search
+    """
+
+    _type = "Core.Models.Search.StatsReport, Core"
+
+    _FILTER_OPERANDS = (
+        EQ,
+        NOT_EQ,
+        CONTAINS,
+        EXCLUDES,
+        LT,
+        GT,
+        LTE,
+        GTE
+    )
+
+    _SORT_ORDERS = (
+        ASC,
+        DESC
+    )
+
+    default_limit = 50
+    default_page_start = None
+    default_page_end = None
+
+    def __init__(self, app, raw, **kwargs):
+        APIResource.__init__(self, app._swimlane, raw)
+        PaginatedCursor.__init__(self,
+                                 limit=kwargs.pop('limit', self.default_limit),
+                                 page_size=kwargs.pop('page_size', self.default_page_size),
+                                 page_start=kwargs.pop('page_start', self.default_page_start),
+                                 page_end=kwargs.pop('page_end', self.default_page_end)
+                                 )
+
+        self.name = self._raw['name']
+        self.keywords = kwargs.pop('keywords', [])
+
+        self._app = app
+
+        for field_id in self._app._fields_by_id.keys():
+            self._raw['columns'].append(field_id)
+
+    def filter_type(self, filter_type):
+        filter_type = filter_type.capitalize()
+        self.validateOperator(filter_type)
+        self.filter_type = filter_type
+
+    def validateOperator(self, operator):
+        if operator not in ALLOWED_OPERATORS:
+            raise ValueError('filter_type value not allowed')
+
+    def __str__(self):
+        return self.name
+
+    def _retrieve_raw_elements(self, page):
+        body = self._raw.copy()
+
+        body['pageSize'] = self.page_size
+        body['offset'] = page
+        if(type(self.filter_type) is str):
+            body['filterType'] = self.filter_type
+        body['keywords'] = ', '.join(self.keywords)
+
+        response = self._swimlane.request('post', 'search', json=body)
+        return response.json()['results'].get(self._app.id, [])
+
+    def _parse_raw_element(self, raw_element):
+        return Record(self._app, raw_element)
+
+    def filter(self, field_name, operand, value):
+        """Adds a filter to report
+
+        Notes:
+            1. All filters are currently AND'ed together.
+            2. None values work like a wildcard and will skip type verification.
+
+        Args:
+            field_name (str): Target field name to filter on
+            operand (str): Operand used in comparison. See `swimlane.core.search` for options
+            value: Target value used in comparison
+        """
+        if operand not in self._FILTER_OPERANDS:
+            raise ValueError('Operand must be one of {}'.format(', '.join(self._FILTER_OPERANDS)))
+
+        field = self._get_stub_field(field_name)
+        
+        validate_type(field, value)
+
+        value = self.parse_field_value(field, value)
+
+        self._raw['filters'].append({
+            "fieldId": field.id,
+            "filterType": operand,
+            "value": field.get_report(value)
+        })
+
+    def sort(self, field_name, order):
+        """Adds a sort to report
+
+        Args:
+            field_name (str): Target field name to sort by
+            order (str): Sort order
+        """
+        if (order not in self._SORT_ORDERS):
+            raise ValueError('Order must be one of {}'.format(', '.join(self._SORT_ORDERS)))
+
+        field = self._get_stub_field(field_name)
+
+        self._raw['sorts'][field.id] = order
+
+    def set_columns(self, *field_names):
+        """Set specified columns for report
+
+        Notes:
+            The Tracking Id column is always included
+
+        Args:
+            *field_names (str): Zero or more column names
+        """
+        self._raw['columns'] = []
+        for field_name in field_names:
+            field = self._get_stub_field(field_name)
+
+            self._raw['columns'].append(field.id)
+
+        if self._app.tracking_id not in self._raw['columns']:
+            self._raw['columns'].append(self._app.tracking_id)
+
+    def _get_stub_field(self, field_name):
+        if not field_name or not isinstance(field_name, str):
+            raise ValueError('field_name is of an invalid format, expected non-empty string')
+
+        # Use temp Record instance for target app to translate values into expected API format
+        record_stub = record_factory(self._app)
+        return record_stub.get_field(field_name)
+
+    def parse_field_value(self, field, value):
+        if isinstance(field, ListField):
+            type = self.get_field_list_type(field.input_type)
+            value = self.get_default_value(value, field.input_type)
+        if isinstance(field, ListField) and not isinstance(value, list) and value is not None:
+            self.validate_type(value, type, field.input_type)
+            return [value]
+        elif isinstance(field, ListField) and isinstance(value, list) and any(not isinstance(elem, type) for elem in value):
+            raise TypeError('Field item must be a {}.'.format(field.input_type))
+        return value
+
+    def validate_type(self, value, type, type_name=None):
+        if(not type_name):
+            type_name = type
+        if not isinstance(value, type):
+            raise TypeError('Field must be a {}.'.format(type_name))
+        
+    def get_default_value(self, value, field_type):
+        if(value == '' and field_type == 'text'):
+            value = None
+        return value
+
+    def get_field_list_type(self, field_type):
+        if field_type == 'text':
+            return str
+        elif field_type == 'numeric':
+            return (int, float)
+
+def report_factory(app, report_name, **kwargs):
+    """Report instance factory populating boilerplate raw data
+
+    Args:
+        app (App): Swimlane App instance
+        report_name (str): Generated Report name
+
+    Keyword Args
+        **kwargs: Kwargs to pass to the Report class
+    """
+    # pylint: disable=protected-access
+    created = pendulum.now().to_rfc3339_string()
+    user_model = app._swimlane.user.as_usergroup_selection()
+
+    return Report(
+        app,
+        {
+            "$type": Report._type,
+            "groupBys": [],
+            "aggregates": [],
+            "applicationIds": [app.id],
+            "columns": [],
+            "sorts": {
+                "$type": "System.Collections.Generic.Dictionary`2"
+                         "[[System.String, mscorlib],"
+                         "[Core.Models.Search.SortTypes, Core]], mscorlib",
+            },
+            "filters": [],
+            "defaultSearchReport": False,
+            "allowed": [],
+            "permissions": {
+                "$type": "Core.Models.Security.PermissionMatrix, Core"
+            },
+            "createdDate": created,
+            "modifiedDate": created,
+            "createdByUser": user_model,
+            "modifiedByUser": user_model,
+            "id": None,
+            "name": report_name,
+            "disabled": False,
+            "keywords": ""
+        },
+        **kwargs
+    )

package/lib/templates/swimlane/core/resources/revision_base.py

@@ -0,0 +1,69 @@
+import pendulum
+
+from swimlane.core.resources.base import APIResource
+from swimlane.core.resources.usergroup import UserGroup
+
+
+class RevisionBase(APIResource):
+    """
+    The base class representing a single revision returned from a History lookup.
+
+    Attributes:
+        Attributes:
+        modified_date: The date this revision was created.
+        revision_number: The revision number of this revision.
+        status: Indicates whether this revision is the current revision or a historical revision.
+        user: The user that saved this revision.
+    """
+
+    def __init__(self, swimlane, raw):
+        super(RevisionBase, self).__init__(swimlane, raw)
+
+        self._modified_date = pendulum.parse(self._raw['modifiedDate'])
+        self._revision_number = self._raw['revisionNumber']
+        self.status = self._raw['status']
+
+        # UserGroupSelection, can't set as User without additional lookup
+        self._user = UserGroup(self._swimlane, self._raw['userId'])
+
+        self._raw_version = self._raw['version']
+        self._version = None
+
+    def __str__(self):
+        return '{} ({})'.format(self.version, self.revision_number)
+
+    @property
+    def version(self):
+        raise NotImplementedError
+
+    def for_json(self):
+        """Return revision metadata"""
+        return {
+            'modifiedDate': self._raw['modifiedDate'],
+            'revisionNumber': self.revision_number,
+            'user': self.user.for_json()
+        }
+    
+    @property
+    def revision_number(self):
+        return self._revision_number
+    
+    @revision_number.setter
+    def revision_number(self, value):
+        raise AttributeError("can't set attribute")
+
+    @property
+    def modified_date(self):
+        return self._modified_date
+    
+    @modified_date.setter
+    def modified_date(self, value):
+        raise AttributeError("can't set attribute")
+    
+    @property
+    def user(self):
+        return self._user
+    
+    @user.setter
+    def user(self, value):
+        raise AttributeError("can't set attribute")

package/lib/templates/swimlane/core/resources/task.py

@@ -0,0 +1,16 @@
+from swimlane.core.resources.base import APIResource
+
+
+class Task(APIResource):
+    _type = 'Core.Models.Integrations.Task, Core'
+
+    def __init__(self, swimlane, raw):
+        super(Task, self).__init__(swimlane, raw)
+        self.app_id = raw.get('applicationId')
+        self.id = raw.get('id')
+        self.name = raw.get('name')
+        self.script = raw.get('action').get('script')
+    
+    def __str__(self):
+        return '{self.name}'.format(self=self)
+

package/lib/templates/swimlane/core/resources/usergroup.py

@@ -0,0 +1,166 @@
+from functools import total_ordering
+
+from swimlane.core.cursor import Cursor
+from swimlane.core.resolver import SwimlaneResolver
+from swimlane.core.resources.base import APIResource
+
+
+# pylint: disable=abstract-method
+@total_ordering
+class UserGroup(APIResource):
+    """Base class for Users and Groups
+
+    Notes:
+        Returned in some places where determining whether object is a User or Group is not possible without additional
+        requests. Use appropriate adapter on `swimlane` client to retrieve more specific instance using `id` as needed
+
+        Can be compared to User or Group instances directly without ensuring the classes are the same
+
+    Attributes:
+        id (str): Full user/group ID
+        name (str): User/group name
+    """
+
+    def __init__(self, swimlane, raw):
+        super(UserGroup, self).__init__(swimlane, raw)
+
+        self.id = self._raw['id']
+        self.name = self._raw['name']
+
+    def __str__(self):
+        return self.name
+
+    def __hash__(self):
+        return hash((self.id, self.name))
+
+    def __eq__(self, other):
+        """Override to allow equality comparisons across UserGroup, User, and Group instances"""
+        return isinstance(other, UserGroup) and hash(self) == hash(other)
+
+    def __lt__(self, other):
+        if not isinstance(other, UserGroup):
+            raise TypeError('Comparisons not supported between instances of "{}" and "{}"'.format(
+                other.__class__.__name__,
+                self.__class__.__name__
+            ))
+
+        return self.name < other.name
+
+    def resolve(self):
+        """Retrieve and return correct User or Group instance from UserGroup
+
+        .. versionadded:: 2.16.1
+
+        Returns:
+            User | Group: Resolved User or Group instance
+        """
+        # Skip resolving if not a generic instance
+        if self.__class__ is not UserGroup:
+            return self
+
+        else:
+            try:
+                return self._swimlane.users.get(id=self.id)
+            except ValueError:
+                return self._swimlane.groups.get(id=self.id)
+
+    def as_usergroup_selection(self):
+        """Converts UserGroup to raw UserGroupSelection for populating record
+
+        Returns:
+            dict: Formatted UserGroup data as used by selection fields
+        """
+        return {
+            '$type': 'Core.Models.Utilities.UserGroupSelection, Core',
+            'id': self.id,
+            'name': self.name
+        }
+
+    def for_json(self):
+        """Get JSON-compatible representation"""
+        return {
+            'id': self.id,
+            'name': self.name
+        }
+
+
+class Group(UserGroup):
+    """Swimlane group record
+
+    Attributes:
+        description (str): Group description
+        users (GroupUsersCursor): List of users belonging to group.
+    """
+
+    _type = 'Core.Models.Groups.Group, Core'
+
+    def __init__(self, swimlane, raw):
+        super(Group, self).__init__(swimlane, raw)
+        self.__user_ids = [item['id'] for item in self._raw.get('users')]
+        self.description = self._raw.get('description')
+        self.__users = None
+
+    @property
+    def users(self):
+        """Returns a GroupUsersCursor with list of User instances for this Group
+
+        .. versionadded:: 2.16.2
+        """
+        if self.__users is None:
+            self.__users = GroupUsersCursor(swimlane=self._swimlane, user_ids=self.__user_ids)
+        return self.__users
+
+    def get_cache_index_keys(self):
+        return {
+            'id': self.id,
+            'name': self.name
+        }
+
+
+class User(UserGroup):
+    """Swimlane user record
+
+    Attributes:
+        username (str): Unique username
+        display_name (str): User display name
+        email (str): User email
+    """
+
+    _type = 'Core.Models.Identity.ApplicationUser, Core'
+
+    def __init__(self, swimlane, raw):
+        super(User, self).__init__(swimlane, raw)
+
+        self.username = self._raw.get('userName')
+        self.display_name = self._raw.get('displayName')
+        self.email = self._raw.get('email')
+
+    def get_cache_index_keys(self):
+        return {
+            'id': self.id,
+            'username': self.username,
+            'display_name': self.display_name
+        }
+
+
+class GroupUsersCursor(SwimlaneResolver, Cursor):
+    """Handles retrieval for user endpoint"""
+
+    def __init__(self, swimlane, user_ids):
+        SwimlaneResolver.__init__(self, swimlane)
+        Cursor.__init__(self)
+        self.__user_ids = user_ids
+
+    def _evaluate(self):
+        """Lazily retrieve and build User instances from returned data"""
+        if self._elements:
+            for element in self._elements:
+                yield element
+        else:
+            for user_id in self.__user_ids:
+                try:
+                    element = self._swimlane.users.get(id=user_id)
+                    self._elements.append(element)
+                    yield element
+                except StopIteration:
+                    return

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

@@ -0,0 +1,31 @@
+"""Provides handful of constants used in record reports/searches"""
+
+# Filter
+EQ = "equals"
+NOT_EQ = "doesNotEqual"
+CONTAINS = "contains"
+EXCLUDES = "excludes"
+GT = "greaterThan"
+LT = "lessThan"
+LTE = "lessThanOrEqual"
+GTE = "greaterThanOrEqual"
+
+# Aggregate
+AVG = "average"
+COUNT = "count"
+SUM = "sum"
+MIN = "min"
+MAX = "max"
+
+# GroupBy
+GB = "groupBy"
+HOUR = "groupByHour"
+DAY = "groupByDay"
+WEEK = "groupByWeek"
+MONTH = "groupByMonth"
+QUARTER = "groupByQuarter"
+YEAR = "groupByYear"
+
+# Sorts
+ASC = "ascending"
+DESC = "descending"

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

@@ -0,0 +1,12 @@
+import requests
+
+class WrappedSession(requests.Session):
+    """A wrapper for requests.Session to override 'verify' property, ignoring REQUESTS_CA_BUNDLE environment variable.
+
+    This is a workaround for https://github.com/kennethreitz/requests/issues/3829 (will be fixed in requests 3.0.0)
+    """
+    def merge_environment_settings(self, url, proxies, stream, verify, *args, **kwargs):
+        if self.verify is False:
+            verify = False
+
+        return super(WrappedSession, self).merge_environment_settings(url, proxies, stream, verify, *args, **kwargs)