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

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

@@ -0,0 +1,15 @@
+"""Base classes used to build field abstractions"""
+from .cursor import CursorField, FieldCursor
+from .field import Field
+from .multiselect import MultiSelectField, MultiSelectCursor
+
+
+class ReadOnly(Field):
+    """Mixin explicitly disabling setting value via python"""
+
+    def __init__(self, *args, **kwargs):
+        super(ReadOnly, self).__init__(*args, **kwargs)
+
+        self.readonly = True
+
+

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

@@ -0,0 +1,90 @@
+import weakref
+
+from swimlane.core.cursor import Cursor
+from swimlane.core.resolver import SwimlaneResolver
+from .field import Field
+
+
+class FieldCursor(Cursor, SwimlaneResolver):
+    """Base class for encapsulating a field instance's complex logic
+    
+    Useful in abstracting away extra request(s), lazy evaluation, pagination, intensive calculations, etc.
+    """
+
+    def __init__(self, field, initial_elements=None):
+        SwimlaneResolver.__init__(self, field.record._swimlane)
+        Cursor.__init__(self)
+
+        self._elements = initial_elements or self._elements
+
+        self.__field_name = field.name
+        self.__record_ref = weakref.ref(field.record)
+        self.__field_ref = weakref.ref(field)
+
+    def __repr__(self):
+        # pylint: disable=missing-format-attribute
+        return '<{self.__class__.__name__}: {self._record!r}["{self._field.name}"] ({length})>'.format(
+            self=self,
+            length=len(self)
+        )
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and other._record.id == self._record.id
+
+    def _sync_field(self):
+        """Set source field value to current cursor value"""
+        self._field.set_python(self._evaluate())
+
+    @property
+    def _record(self):
+        return self.__record_ref()
+
+    @property
+    def _field(self):
+        field = self.__field_ref()
+        # Occurs when a record is saved and reinitialized, creating new Field instances and losing the existing weakref
+        # Update weakref to point to new Field instance of the same name
+        if field is None:
+            field = self._record.get_field(self.__field_name)
+            self.__field_ref = weakref.ref(field)
+        return field
+
+
+class CursorField(Field):
+    """Returns a proxy-like FieldCursor instance to support additional functionality"""
+
+    cursor_class = None
+
+    def __init__(self, *args, **kwargs):
+        super(CursorField, self).__init__(*args, **kwargs)
+
+        self._cursor = None
+
+    def get_initial_elements(self):
+        """Return initial elements to be passed with cursor instantiation"""
+        return self._get()
+
+    def _set(self, value):
+        self._cursor = None
+        super(CursorField, self)._set(value)
+
+    @property
+    def cursor(self):
+        """Cache and return cursor_class instance"""
+        if self._cursor is None:
+            # pylint: disable=not-callable
+            self._cursor = self.cursor_class(self, self.get_initial_elements())
+
+        return self._cursor
+
+    def get_python(self):
+        """Create, cache, and return the appropriate cursor instance"""
+        return self.cursor
+
+    def for_json(self):
+        """Return list of all cursor items, calling .for_json() if available for best representations"""
+        cursor = super(CursorField, self).for_json()
+        if cursor is not None:
+            # Lambda called immediately, false-positive from pylint on closure scope warning
+            # pylint: disable=cell-var-from-loop
+            return [getattr(item, 'for_json', lambda: item)() for item in cursor]

package/lib/templates/swimlane/core/fields/base/field.py

@@ -0,0 +1,149 @@
+import weakref
+
+from swimlane.core.resolver import SwimlaneResolver
+from swimlane.exceptions import ValidationError
+
+
+class Field(SwimlaneResolver):
+    """Base class for abstracting Swimlane complex types"""
+
+    field_type = None
+
+    # Sentinel representing a field that has no current value
+    _unset = object()
+
+    # List of supported types, leave blank to disable type validation
+    supported_types = []
+
+    # Checks if bulk modify is supported for field
+    bulk_modify_support = True
+
+    def __init__(self, name, record):
+        """Value not included during instantiation to prevent ambiguity between python and swimlane representations"""
+        super(Field, self).__init__(record._swimlane)
+
+        self.name = name
+        self.__record_ref = weakref.ref(record)
+        self._value = self._unset
+
+        self.field_definition = self.record.app.get_field_definition_by_name(self.name)
+        self.key = self.field_definition.get('key')
+        self.id = self.field_definition['id']
+        self.input_type = self.field_definition.get('inputType')
+        self.required = self.field_definition.get('required', False)
+        self.readonly = bool(self.field_definition.get('formula', self.field_definition.get('readOnly', False)))
+        self.multiselect = self.field_definition.get('selectionType', 'single') == 'multi'
+
+    def __repr__(self):
+        return '<{class_name}: {py!r}>'.format(class_name=self.__class__.__name__, py=self.get_python())
+
+    @property
+    def record(self):
+        """Resolve weak reference to parent record"""
+        return self.__record_ref()
+
+    def _get(self):
+        """Default getter used for both representations unless overridden"""
+        return self._value
+
+    def get_item(self):
+        """Return best python representation of field value for get attribute method"""
+        return self.get_python()
+
+    def get_python(self):
+        """Return best python representation of field value"""
+        return self._get()
+
+    def get_batch_representation(self):
+        """Return best batch process representation of field value"""
+        return self._get()
+
+    def get_swimlane(self):
+        """Return best swimlane representation of field value"""
+        return self.cast_to_swimlane(self._get())
+
+    def get_report(self, value):
+        """Return provided field Python value formatted for use in report filter"""
+        if self.multiselect:
+            value = value or []
+            try:
+                list_vars = vars(value)
+                if "multiselect" in list_vars:
+                    pass
+            except :
+                if not isinstance(value, list) :
+                    raise TypeError("Value Expected a list, but got something else.")
+            children = []
+
+            for child in value:
+                id = self.cast_to_report(child)
+                if id:
+                    children.append(id)
+
+            return children
+
+        return self.cast_to_report(value)
+
+    def get_bulk_modify(self, value):
+        """Return value in format for bulk modify"""
+        if self.multiselect:
+            value = value or []
+            return [self.cast_to_bulk_modify(child) for child in value]
+
+        return self.cast_to_bulk_modify(value)
+
+    def cast_to_python(self, value):
+        """Called during set_swimlane, should accept a single raw value as provided from API
+
+        Defaults to no-op
+        """
+        return value
+
+    def cast_to_swimlane(self, value):
+        """Called during get_swimlane, should accept a python value and return swimlane representation
+
+        Defaults to no-op
+        """
+        return value
+
+    def cast_to_report(self, value):
+        """Cast single value to report format, defaults to cast_to_swimlane(value)"""
+        return self.cast_to_swimlane(value)
+
+    def cast_to_bulk_modify(self, value):
+        """Cast single value to bulk modify format, defaults to cast_to_report with added validation"""
+        self.validate_value(value)
+        return self.cast_to_report(value)
+
+    def validate_value(self, value):
+        """Validate value is an acceptable type during set_python operation"""
+        if self.readonly and not self._swimlane._write_to_read_only:
+            raise ValidationError(self.record, 'Cannot set readonly field "{}"'.format(self.name))
+        if value not in (None, self._unset):
+            if self.supported_types and not isinstance(value, tuple(self.supported_types)):
+                raise ValidationError(self.record, 'Field "{}" expects one of {}, got "{}" instead'.format(
+                    self.name,
+                    ', '.join([repr(t.__name__) for t in self.supported_types]),
+                    type(value).__name__)
+                )
+
+    def _set(self, value):
+        """Default setter used for both representations unless overridden"""
+        self._value = value
+        self.record._raw['values'][self.id] = self.get_swimlane()
+
+    def set_python(self, value):
+        """Set field internal value from the python representation of field value"""
+        self.validate_value(value)
+        return self._set(value)
+
+    def set_swimlane(self, value):
+        """Set field internal value from the swimlane representation of field value"""
+        return self._set(self.cast_to_python(value))
+
+    def for_json(self):
+        """Return json.dump()-compatible representation of field value
+
+        .. versionadded:: 4.1.0
+        """
+        return self.get_python()

package/lib/templates/swimlane/core/fields/base/multiselect.py

@@ -0,0 +1,116 @@
+from sortedcontainers import SortedSet
+
+from swimlane.core.resources.usergroup import User
+
+from .cursor import CursorField, FieldCursor
+
+
+class MultiSelectCursor(FieldCursor):
+    """Cursor allowing setting and unsetting values on a MultiSelectField
+
+    Respects parent field's validation
+    """
+
+    def __init__(self, *args, **kwargs):
+        super(MultiSelectCursor, self).__init__(*args, **kwargs)
+
+        self._elements = filter(lambda e: e is not None, self._elements)
+        self._elements = SortedSet(self._elements)
+
+    def select(self, element):
+        """Add an element to the set of selected elements
+
+        Proxy to internal set.add and sync field
+        """
+        self._field.validate_value(element)
+        self._elements.add(element)
+        self._sync_field()
+
+    def deselect(self, element):
+        """Remove an element from the set of selected elements
+
+        Proxy to internal set.remove and sync field
+        """
+        self._elements.remove(element)
+        self._sync_field()
+
+
+class MultiSelectField(CursorField):
+    """Base class for fields that can be multi-selection or single-selection field"""
+
+    cursor_class = MultiSelectCursor
+
+    def get_python(self):
+        """Only return cursor instance if configured for multiselect"""
+        if self.multiselect:
+            return super(MultiSelectField, self).get_python()
+
+        return self._get()
+
+    def get_swimlane(self):
+        """Handle multi-select and single-select modes"""
+        if self.multiselect:
+            value = self._get()
+            children = []
+            if value:
+                for child in value:
+                        children.append(self.cast_to_swimlane(child))
+                return children
+            return None
+        return super(MultiSelectField, self).get_swimlane()
+
+    def _set(self, value):
+        """Override to treat empty lists as None"""
+        return super(MultiSelectField, self)._set(value or None)
+
+    def set_python(self, value):
+        """Override to remove key from raw data when empty to work with server 2.16+ validation"""
+        if self.multiselect:
+            value = value or []
+            elements = []
+
+            if not isinstance(
+                value,
+                (
+                    list,
+                    MultiSelectCursor,
+                    SortedSet,
+                    User,
+                ),
+            ):
+                value = [value]
+
+            for element in value:
+                self.validate_value(element)
+                elements.append(element)
+
+            value = elements
+        else:
+            self.validate_value(value)
+
+        self._set(value)
+
+    def set_swimlane(self, value):
+        """Cast all multi-select elements to correct internal type like single-select mode"""
+        if self.multiselect:
+            value = value or []
+            children = []
+
+            for child in value:
+                children.append(self.cast_to_python(child))
+
+            return self._set(children)
+
+        return super(MultiSelectField, self).set_swimlane(value)
+
+    def for_json(self):
+        """Handle multi-select vs single-select"""
+
+        if self.multiselect:
+            return super(MultiSelectField, self).for_json()
+
+        value = self.get_python()
+        if hasattr(value, 'for_json'):
+            return value.for_json()
+
+        return value

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

@@ -0,0 +1,48 @@
+import pendulum
+
+from swimlane.core.resources.comment import Comment
+from .base import CursorField, FieldCursor, ReadOnly
+
+
+class CommentCursor(FieldCursor):
+    """Returned by CommentField to allow iteration and creation of Comment instances"""
+
+    def comment(self, message, rich_text=False):
+        """Add new comment to record comment field"""
+        message = str(message)
+        if not isinstance(rich_text, bool):
+            raise ValueError('rich_text must be a boolean value.')
+
+        sw_repr = {
+            '$type': 'Core.Models.Record.Comments, Core',
+            'createdByUser': self._record._swimlane.user.as_usergroup_selection(),
+            'createdDate': pendulum.now().to_rfc3339_string(),
+            'message': message,
+            'isRichText': rich_text
+        }
+
+        comment = Comment(self._swimlane, sw_repr)
+        self._elements.append(comment)
+
+        self._record._raw['comments'].setdefault(self._field.id, [])
+        self._record._raw['comments'][self._field.id].append(comment._raw)
+
+        # Tracking comment changes for patch endpoint
+        self._record._comments_modified = True
+
+        return comment
+
+
+class CommentsField(ReadOnly, CursorField):
+
+    field_type = (
+        'Core.Models.Fields.CommentsField, Core',
+        'Core.Models.Fields.Comments.CommentsField, Core'
+    )
+    cursor_class = CommentCursor
+    bulk_modify_support = False
+
+    def get_initial_elements(self):
+        raw_comments = self.record._raw['comments'].get(self.id, [])
+
+        return [Comment(self.record._swimlane, raw) for raw in raw_comments]

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

@@ -0,0 +1,112 @@
+from __future__ import absolute_import
+from swimlane.utils.date_validator import is_datetime
+
+from datetime import date, datetime, time, timedelta
+
+import math
+import pendulum
+
+from .base import Field
+
+UTC = pendulum.timezone('UTC')
+
+
+class DatetimeField(Field):
+
+    field_type = 'Core.Models.Fields.Date.DateField, Core'
+
+    datetime_format = '%Y-%m-%dT%H:%M:%S.%fZ'
+
+    _type_date = 'date'
+    _type_time = 'time'
+    _type_interval = 'timespan'
+
+    # All others default to datetime
+    _input_type_map = {
+        _type_interval: [timedelta],
+        _type_date: [datetime, date],
+        _type_time: [datetime, time]
+    }
+
+    def __init__(self, *args, **kwargs):
+        super(DatetimeField, self).__init__(*args, **kwargs)
+
+        # Determine supported_types after inspecting input subtype
+        self.supported_types = self._input_type_map.get(self.input_type, [datetime])
+
+    def _set(self, value):
+        # Force to appropriate Pendulum instance for consistency
+        if value is not None:
+            if self.input_type != self._type_interval:
+                if self.input_type == self._type_date:
+                    # Pendulum date
+                    if isinstance(value, date):
+                        value = pendulum.DateTime.combine(value, pendulum.time(0))
+                elif self.input_type == self._type_time:
+                    # Pendulum time
+                    if isinstance(value, time):
+                        value = pendulum.DateTime.combine(pendulum.today().date(), value)
+
+                # Convert to Pendulum instance in UTC
+                value = UTC.convert(pendulum.instance(value))
+                # Drop nanosecond precision to match Mongo precision
+                value = value.set(microsecond=int(math.floor(value.microsecond / 1000) * 1000))
+
+        return super(DatetimeField, self)._set(value)
+
+    def cast_to_python(self, value):
+        if value is not None:
+            if self.input_type == self._type_interval:
+                value = pendulum.duration(milliseconds=int(value))
+            else:
+                value = pendulum.parse(value)
+
+        return value
+
+    def get_python(self):
+        """Coerce to best date type representation for the field subtype"""
+        value = super(DatetimeField, self).get_python()
+
+        if value is not None:
+            # Handle subtypes with matching Pendulum types
+            if self.input_type == self._type_time:
+                value = value.time()
+            if self.input_type == self._type_date:
+                value = value.date()
+
+        return value
+
+    @classmethod
+    def format_datetime(cls, target_datetime):
+        """Format datetime as expected by Swimlane API"""
+        if not is_datetime(target_datetime):
+            target_datetime = datetime.combine(target_datetime, datetime.min.time())
+        return UTC.convert(target_datetime).strftime(cls.datetime_format)
+
+    def cast_to_swimlane(self, value):
+        """Return datetimes formatted as expected by API and timespans as millisecond epochs"""
+        if value is None:
+            return value
+
+        if self.input_type == self._type_interval:
+            return value.in_seconds() * 1000
+
+        return self.format_datetime(value)
+
+    def get_batch_representation(self):
+        """Return best batch process representation of field value"""
+        return self.get_swimlane()
+
+    def for_json(self):
+        """Return date ISO8601 string formats for datetime, date, and time values, milliseconds for intervals"""
+        value = super(DatetimeField, self).for_json()
+
+        # Order of instance checks matters for proper inheritance checks
+        if isinstance(value, pendulum.Duration):
+            return value.in_seconds() * 1000
+        if isinstance(value, datetime):
+            return self.format_datetime(value)
+        if isinstance(value, pendulum.Time):
+            return str(value)
+        if isinstance(value, pendulum.Date):
+            return value.to_date_string()

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

@@ -0,0 +1,28 @@
+from .base import CursorField, FieldCursor, ReadOnly
+
+
+class RevisionCursor(FieldCursor):
+    """An iterable object that automatically lazy retrieves and caches history data for a record from API"""
+
+    def __init__(self, *args, **kwargs):
+        super(RevisionCursor, self).__init__(*args, **kwargs)
+        self.__retrieved = False
+
+    def _evaluate(self):
+        """Lazily retrieves, caches, and returns the list of record _revisions"""
+        if not self.__retrieved:
+            self._elements = self._retrieve_revisions()
+            self.__retrieved = True
+
+        return super(RevisionCursor, self)._evaluate()
+
+    def _retrieve_revisions(self):
+        """Populate RecordRevision instances."""
+        return self._record.revisions.get_all()
+
+
+class HistoryField(ReadOnly, CursorField):
+
+    field_type = 'Core.Models.Fields.History.HistoryField, Core'
+    cursor_class = RevisionCursor
+    bulk_modify_support = False