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

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

@@ -0,0 +1,70 @@
+import six
+
+from swimlane.exceptions import ValidationError
+from .base import MultiSelectField
+
+
+class ValuesListField(MultiSelectField):
+
+    field_type = (
+        'Core.Models.Fields.ValuesListField, Core',
+        'Core.Models.Fields.ValuesList.ValuesListField, Core'
+    )
+    supported_types = six.string_types
+
+    def __init__(self, *args, **kwargs):
+        """Map names to IDs for use in field rehydration"""
+        super(ValuesListField, self).__init__(*args, **kwargs)
+        self.selection_to_id_map = {f['name']: f['id'] for f in self.field_definition['values']}
+
+    def validate_value(self, value):
+        """Validate provided value is one of the valid options"""
+        super(ValuesListField, self).validate_value(value)
+
+        if value is not None:
+            if value not in self.selection_to_id_map:
+                raise ValidationError(
+                    self.record,
+                    'Field "{}" invalid value "{}". Valid options: {}'.format(
+                        self.name,
+                        value,
+                        ', '.join(self.selection_to_id_map.keys())
+                    )
+                )
+
+    def get_batch_representation(self):
+        """Return best batch process representation of field value"""
+        return self.get_swimlane()
+
+    def cast_to_python(self, value):
+        """Store actual value as internal representation"""
+        if value is not None:
+            if value['value'] in self.selection_to_id_map:
+                return value['value']
+
+        return None
+
+    def cast_to_swimlane(self, value):
+        """Rehydrate value back as full JSON representation"""
+        if value is None:
+            return value
+        if value not in self.selection_to_id_map:
+            return None
+
+        return {
+            '$type': 'Core.Models.Record.ValueSelection, Core',
+            'id': self.selection_to_id_map[value],
+            'value': value
+        }
+
+    def cast_to_report(self, value):
+        """Report format uses only the value's id"""
+        value = super(ValuesListField, self).cast_to_report(value)
+
+        if value:
+            return value['id']
+
+    def cast_to_bulk_modify(self, value):
+        """Bulk modify uses the normal Swimlane representation"""
+        self.validate_value(value)
+        return self.cast_to_swimlane(value)

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

@@ -0,0 +1,46 @@
+import weakref
+
+
+class SwimlaneResolver(object):
+    """Provides automatic weakref resolution for Swimlane client to avoid circular references and 
+    memory leaks """
+
+    def __init__(self, swimlane):
+        self.__ref_swimlane = weakref.ref(swimlane) if swimlane else swimlane
+
+    @property
+    def _swimlane(self):
+        """Transparently resolve the swimlane weakref"""
+        if not self.__ref_swimlane:
+            referent = self.__ref_swimlane
+        else:
+            referent = self.__ref_swimlane()
+        if referent is None:
+            raise ReferenceError("The swimlane object has been garbage collected. The Swimlane "
+                                 "object uses weak references to avoid memory leaks. The object "
+                                 "gets garbage collected when there are no more references to it. "
+                                 "See the weakref documentation for more information.")
+        return referent
+
+
+class AppResolver(SwimlaneResolver):
+    """Provides automatic weakref resolution for Swimlane client and App instance"""
+
+    def __init__(self, app):
+        super(AppResolver, self).__init__(app._swimlane)
+
+        self.__ref_app = weakref.ref(app) if app else app
+
+    @property
+    def _app(self):
+        if not self.__ref_app:
+            referent = self.__ref_app
+        else:
+            referent = self.__ref_app()
+        if referent is None:
+            raise ReferenceError(
+                "The App object of the Swimlane Object has been garbage collected. Both the App "
+                "object and the Swimlane object use weak references to avoid memory leaks. The "
+                "instance gets garbage collected when there are no more strong references to it. "
+                "See the weakref documentation for more information.")
+        return referent

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

@@ -0,0 +1,136 @@
+from functools import total_ordering
+
+import six
+import pendulum
+
+from swimlane.exceptions import UnknownField
+from .base import APIResource
+
+
+@total_ordering
+class App(APIResource):
+    """A single App record instance
+
+    Used lookup field definitions and retrieve/create child Record instances
+
+    Attributes:
+        name (str): App name
+        acronym (str): App acronym
+        description (str): App description
+        id (str): Full App ID
+        tracking_id (str): App tracking ID
+        records (RecordAdapter): :class:`~swimlane.core.adapters.record.RecordAdapter` configured for current App
+        reports (ReportAdapter): :class:`~swimlane.core.adapters.report.ReportAdapter` configured for current App
+    """
+
+    _type = 'Core.Models.Application.Application, Core'
+
+    def __init__(self, swimlane, raw):
+        super(App, self).__init__(swimlane, raw)
+
+        self.acronym = self._raw['acronym']
+        self.name = self._raw['name']
+        self.description = self._raw.get('description', '')
+        self.id = self._raw['id']
+        self.tracking_id = self._raw.get('trackingFieldId')
+
+        self._fields_by_id = dict()
+        self._fields_by_name = dict()
+        self._defaults = dict()
+
+        for field in self._raw['fields']:
+            self._fields_by_id[field['id']] = field
+            self._fields_by_name[field['name']] = field
+            if 'fieldType' in field and field['fieldType'] == "valuesList":
+                selection_type = field['selectionType']
+                for value in field['values']:
+                    if 'selected' in value and value['selected']:
+                        if selection_type == 'single':
+                            self._defaults[field['name']] = value['name']
+                            break
+                        else:
+                            default = self._defaults.get(field['name'], list())
+                            default.extend([value['name']])
+                            self._defaults[field['name']] = default
+            if 'fieldType' in field and field['fieldType'] == "date":
+                default_value_type = field['defaultValueType']
+                if default_value_type == 'specific':
+                    self._defaults[field['name']] = pendulum.parse(field['defaultValue'])
+
+        self._keys_to_field_names = {}
+        for name, field_def in six.iteritems(self._fields_by_name):
+            # Include original name to simplify name resolution
+            self._keys_to_field_names[name] = name
+            key = field_def.get('key')
+            if key:
+                self._keys_to_field_names[key] = name
+
+        # Avoid circular import
+        from swimlane.core.adapters import RecordAdapter, ReportAdapter, AppRevisionAdapter
+        self.records = RecordAdapter(self)
+        self.reports = ReportAdapter(self)
+        self.revisions = AppRevisionAdapter(self)
+
+    def __str__(self):
+        return '{self.name} ({self.acronym})'.format(self=self)
+
+    def __hash__(self):
+        return hash((self.id, self.name))
+
+    def __lt__(self, other):
+        if not isinstance(other, self.__class__):
+            raise TypeError('Comparisons not supported between instances of "{}" and "{}"'.format(
+                other.__class__.__name__,
+                self.__class__.__name__
+            ))
+
+        return self.name < other.name
+
+    def get_cache_index_keys(self):
+        """Return all fields available when retrieving apps"""
+        return {
+            'id': self.id,
+            'name': self.name,
+            'acroynm': self.acronym
+        }
+
+    def resolve_field_name(self, field_key):
+        """Return the field name matching the given key or None. Searches field keys first, falls back to field names"""
+        return self._keys_to_field_names.get(field_key)
+
+    def get_field_definition_by_name(self, field_name):
+        """Get JSON field definition for field matching provided name or key
+
+        .. versionchanged:: 4.1.0
+            Added support for field keys
+
+        Args:
+            field_name (str): Target field name or key to get definition for
+
+        Raises:
+            swimlane.exceptions.UnknownField: Raised when given a field name not found in App
+
+        Returns:
+            dict: Field metadata definition
+        """
+        try:
+            return self._fields_by_name[self.resolve_field_name(field_name)]
+        except KeyError:
+            raise UnknownField(self, field_name, self._fields_by_name.keys())
+
+    def get_field_definition_by_id(self, field_id):
+        """Get JSON field definition for field matching provided id
+
+        Args:
+            field_id (str): Target field ID to get definition for
+
+        Raises:
+            swimlane.exceptions.UnknownField: Raised when given a field ID not found in App
+
+        Returns:
+            dict: Field metadata definition
+        """
+        try:
+            return self._fields_by_id[field_id]
+        except KeyError:
+            raise UnknownField(self, field_id, self._fields_by_id.keys())

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

@@ -0,0 +1,43 @@
+from swimlane.core.resources.app import App
+from swimlane.core.resources.revision_base import RevisionBase
+
+
+class AppRevision(RevisionBase):
+    """
+    Encapsulates a single revision returned from a History lookup.
+
+    Attributes:
+        Attributes:
+        modified_date: The date this app revision was created.
+        revision_number: The revision number of this app revision.
+        status: Indicates whether this revision is the current revision or a historical revision.
+        user: The user that saved this revision of the record.
+        version: The App corresponding to the data contained in this app revision.
+    """
+
+    # Separator for unique ids. Unlikely to be found in application ids. Although technically we do not currently
+    # validate app ids in the backend for specific characters so this sequence could be found.
+    SEPARATOR = ' --- '
+
+    @staticmethod
+    def get_unique_id(app_id, revision_number):
+        """Returns the unique identifier for the given AppRevision."""
+        return '{0}{1}{2}'.format(app_id, AppRevision.SEPARATOR, revision_number)
+
+    @staticmethod
+    def parse_unique_id(unique_id):
+        """Returns an array containing two items: the app_id and revision number parsed from the given unique_id."""
+        return unique_id.split(AppRevision.SEPARATOR)
+
+    @property
+    def version(self):
+        """Returns an App from the _raw_version info in this app revision. Lazy loaded. Overridden from base class."""
+        if not self._version:
+            self._version = App(self._swimlane, self._raw_version)
+        return self._version
+
+    def get_cache_index_keys(self):
+        """Returns cache index keys for this AppRevision."""
+        return {
+            'app_id_revision': self.get_unique_id(self.version.id, self.revision_number)
+        }

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

@@ -0,0 +1,64 @@
+from io import BytesIO
+
+import pendulum
+
+from swimlane.core.resources.base import APIResource
+
+
+class Attachment(APIResource):
+    """Abstraction of an attachment from an AttachmentsField
+
+    Attributes:
+        file_id (str): Full file ID used in download request URL
+        filename (str): Attachment filename
+        upload_date (pendulum.DateTime): Pendulum datetime when attachment was uploaded
+        record_id (str): Associated record ID used in download request URL
+        field_id (str): Assocated field ID used in download request URL
+    """
+
+    _type = 'Core.Models.Record.Attachment, Core'
+
+    def __init__(self, swimlane, raw, record_id, field_id):
+        super(Attachment, self).__init__(swimlane, raw)
+
+        self.file_id = self._raw['fileId']
+        self.filename = self._raw['filename']
+        self.upload_date = pendulum.parse(self._raw['uploadDate'])
+        self.record_id = record_id
+        self.field_id = field_id
+
+    def __str__(self):
+        return str(self.filename)
+
+    def __hash__(self):
+        return hash(self.file_id)
+
+    def download(self, chunk_size=1024):
+        """Download attachment
+
+        Args:
+            chunk_size (int): Byte-size of chunked download request stream
+
+        Returns:
+            BytesIO: Stream ready for reading containing the attachment file contents
+        """
+        stream = BytesIO()
+
+        response = self._swimlane.request(
+            'get',
+            'attachment/{}/{}/{}'.format(self.record_id, self.field_id, self.file_id),
+            stream=True
+        )
+
+        for chunk in response.iter_content(chunk_size):
+            stream.write(chunk)
+
+        stream.seek(0)
+
+        return stream
+
+    def for_json(self):
+        """Return metadata for JSON-compatible representation"""
+        return_value = self._raw.copy()
+        return_value.pop('$type')
+        return return_value

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

@@ -0,0 +1,55 @@
+import six
+
+from swimlane.core.resolver import SwimlaneResolver
+
+
+class APIResourceMetaclass(type):
+    """Metaclass for all APIResource classes"""
+
+    def __call__(cls, *args, **kwargs):
+        """Hook __init__ call to push resource instance into Swimlane client ResourceCache after instantiation"""
+        resource_instance = type.__call__(cls, *args, **kwargs)
+
+        resource_instance._swimlane.resources_cache.cache(resource_instance)
+
+        return resource_instance
+
+
+class APIResource(six.with_metaclass(APIResourceMetaclass, SwimlaneResolver)):
+    """Base class for all API resources with an associated $type and/or raw data"""
+
+    _type = None
+
+    def __init__(self, swimlane, raw):
+        super(APIResource, self).__init__(swimlane)
+        self._raw = raw
+
+        raw_type = self._raw.get('$type')
+        if self._type and raw_type != self._type:
+            raise TypeError('Expected $type = "{}", received "{}"'.format(self._type, raw_type))
+
+    def __repr__(self):
+        return '<{self.__class__.__name__}: {self!s}>'.format(self=self)
+
+    def __str__(self):
+        return ''
+
+    def __hash__(self):
+        """Added for py2+3 compat"""
+        return int(id(self) / 16)
+
+    def __eq__(self, other):
+        """Determine if an APIResource is of the same type and has the same hash value"""
+        return isinstance(other, self.__class__) and hash(self) == hash(other)
+
+    def __ne__(self, other):
+        # Default __ne__ for python 2 compat
+        return not self == other
+
+    def get_cache_internal_key(self):
+        """Return real internal cache key for resource instance"""
+        return hash(self)
+
+    def get_cache_index_keys(self):
+        """Return dict of key/value pairs used by ResourceCache to map resource values to internal cache instance"""
+        raise NotImplementedError

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

@@ -0,0 +1,33 @@
+import pendulum
+
+from swimlane.core.resources.base import APIResource
+from swimlane.core.resources.usergroup import UserGroup
+
+
+class Comment(APIResource):
+    """Abstraction of a single comment from a comment field
+
+    Attributes:
+        user (UserGroup): UserGroup instance of user who created the comment
+        created_date (pendulum.DateTime): Pendulum datetime of when comment was created
+        message (str): Comment message body
+    """
+
+    def __init__(self, swimlane, raw):
+        super(Comment, self).__init__(swimlane, raw)
+
+        self.user = UserGroup(swimlane, self._raw['createdByUser'])
+        self.created_date = pendulum.parse(self._raw['createdDate'])
+        self.message = self._raw['message']
+        self.is_rich_text = self._raw.get('isRichText', False)
+
+    def __str__(self):
+        return self.message
+
+    def for_json(self):
+        """Called by CommentField.for_json(), returns relevant Comment attributes in JSON-compatible format"""
+        return {
+            'message': self.message,
+            'createdDate': self._raw['createdDate'],
+            'createdByUser': self.user.for_json()
+        }