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

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

@@ -0,0 +1,183 @@
+from six.moves.urllib.parse import quote_plus
+
+from swimlane.core.cache import check_cache
+from swimlane.core.cursor import PaginatedCursor
+from swimlane.core.resolver import SwimlaneResolver
+from swimlane.core.resources.usergroup import Group, User
+from swimlane.utils import one_of_keyword_only
+
+
+class GroupListCursor(SwimlaneResolver, PaginatedCursor):
+    """Handles retrieval and pagination of group list endpoint"""
+
+    def __init__(self, swimlane, limit=None):
+        SwimlaneResolver.__init__(self, swimlane)
+        PaginatedCursor.__init__(self, limit)
+
+    def _parse_raw_element(self, raw_element):
+        return Group(self._swimlane, raw_element)
+
+    def _retrieve_raw_elements(self, page):
+        response = self._swimlane.request(
+            'get',
+            'groups',
+            params={
+                'size': self.page_size,
+                'pageNumber': page
+            }
+        )
+        return response.json().get('items', [])
+
+
+class GroupAdapter(SwimlaneResolver):
+    """Handles retrieval of Swimlane Group resources"""
+
+    def list(self, limit=None):
+        """Retrieve list of all groups
+
+        Returns:
+            :class:`list` of :class:`~swimlane.core.resources.usergroup.Group`: List of all Groups
+        Raises:
+            ValueError: If limit is not of type integer or None
+        """
+
+        if (isinstance(limit, int) and limit > 0) or limit is None:
+            return GroupListCursor(swimlane=self._swimlane, limit=limit)
+
+        raise ValueError('Limit should be a positive whole number greater than 0')
+
+    @check_cache(Group)
+    @one_of_keyword_only('id', 'name')
+    def get(self, key, value):
+        """Retrieve single group record by id or name
+
+        Supports resource cache
+
+        Keyword Args:
+            id (str): Full Group ID
+            name (str): Group name
+
+        Raises:
+            TypeError: Unexpected or more than one keyword argument provided
+            ValueError: No matching group found based on provided inputs
+            ValueError: The lookup value is empty or None
+
+        Returns:
+            Group: Group instance matching provided inputs
+        """
+        if not value:
+            raise ValueError('The value provided for the key "{0}" cannot be empty or None'.format(key))
+
+        if key == 'id':
+            response = self._swimlane.request('get', 'groups/{}'.format(value))
+            return Group(self._swimlane, response.json())
+
+        else:
+            response = self._swimlane.request('get', 'groups/lookup?name={}'.format(value))
+            matched_groups = response.json()
+
+            for group_data in matched_groups:
+                if group_data.get('name') == value:
+                    return Group(self._swimlane, group_data)
+
+            raise ValueError('Unable to find group with name "{}"'.format(value))
+
+
+class UserListCursor(SwimlaneResolver, PaginatedCursor):
+    """Handles retrieval and pagination for user list endpoint"""
+
+    def __init__(self, swimlane, limit=None):
+        SwimlaneResolver.__init__(self, swimlane)
+        PaginatedCursor.__init__(self, limit)
+
+    def _parse_raw_element(self, raw_element):
+        return User(self._swimlane, raw_element)
+
+    def _retrieve_raw_elements(self, page):
+        response = self._swimlane.request(
+            'get',
+            'user',
+            params={
+                'size': self.page_size,
+                'pageNumber': page
+            }
+        )
+        return response.json().get('items', [])
+
+
+class UserAdapter(SwimlaneResolver):
+    """Handles retrieval of Swimlane User resources"""
+
+    def list(self, limit=None):
+        """Retrieve all users
+
+        Returns:
+            :class:`UserListCursor`: Paginated cursor yielding :class:`User` instances
+
+        Raises:
+            ValueError: If limit is not of type integer or None
+        """
+
+        if (isinstance(limit, int) and limit > 0) or limit is None:
+            return UserListCursor(swimlane=self._swimlane, limit=limit)
+
+        raise ValueError('Limit should be a positive whole number greater than 0')
+
+    @check_cache(User)
+    @one_of_keyword_only('id', 'display_name')
+    def get(self, arg, value):
+        """Retrieve single user record by id or username
+
+        Warnings:
+            User display names are not unique. If using `display_name`, method will fail if multiple Users are returned
+            with the same display name
+
+        Keyword Args:
+            id (str): Full User ID
+            display_name (str): User display name
+
+        Returns:
+            User: User instance matching provided inputs
+
+        Raises:
+            TypeError: Unexpected or more than one keyword argument provided
+            ValueError: No matching user found based on provided inputs, or multiple Users with same display name
+            ValueError: The lookup value is empty or None
+        """
+        if not value:
+            raise ValueError('The value provided for the key "{0}" cannot be empty or None'.format(arg))
+
+        if arg == 'id':
+            response = self._swimlane.request('get', 'user/{}'.format(value))
+
+            try:
+                user_data = response.json()
+            except ValueError:
+                raise ValueError('Unable to find user with ID "{}"'.format(value))
+
+            return User(self._swimlane, user_data)
+
+        else:
+            response = self._swimlane.request('get', 'user/search?query={}'.format(quote_plus(value)))
+            matched_users = response.json()
+
+            # Display name not unique, fail if multiple users share the same target display name
+            target_matches = []
+
+            for user_data in matched_users:
+                user_display_name = user_data.get('displayName')
+                if user_display_name == value:
+                    target_matches.append(user_data)
+
+            # No matches
+            if not target_matches:
+                raise ValueError('Unable to find user with display name "{}"'.format(value))
+
+            # Multiple matches
+            if len(target_matches) > 1:
+                raise ValueError('Multiple users returned with display name "{}". Matching user IDs: {}'.format(
+                    value,
+                    ', '.join(['"{}"'.format(r['id']) for r in target_matches])
+                ))
+
+            return User(self._swimlane, target_matches[0])

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

@@ -0,0 +1,48 @@
+"""Helpers for bulk methods"""
+
+
+class _BulkModificationOperation(object):
+    """Base class for bulk_modify value modification operators
+
+    Acts as container to wrap the modification type with the target value for the bulk operation
+
+    Examples:
+
+        swimlane.records.bulk_modify(
+            record,
+            values={
+                'Field A': 'new value',
+                'Field B': Append('new value'),
+                'Field C': Clear(),
+                ...
+            }
+        )
+    """
+
+    type = None
+
+    def __init__(self, value):
+        self.value = value
+
+
+class Replace(_BulkModificationOperation):
+    """Bulk modification 'Replace with'/'Replace all with' operation"""
+    type = 'create'
+
+
+class Clear(_BulkModificationOperation):
+    """Bulk modification 'Clear field' operation"""
+    type = 'delete'
+
+    def __init__(self):
+        super(Clear, self).__init__(None)
+
+
+class Append(_BulkModificationOperation):
+    """Bulk modification 'Add to existing' operation"""
+    type = 'append'
+
+
+class Remove(_BulkModificationOperation):
+    """Bulk modification 'Find and remove these' operation"""
+    type = 'subtract'

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

@@ -0,0 +1,165 @@
+"""Module providing support for automatic APIResource caching
+
+A ResourcesCache instance is provided on all Swimlane client instances automatically
+
+.. versionadded:: 2.16.2
+"""
+import copy
+import functools
+import logging
+try:
+    from collections.abc import defaultdict
+except ImportError:
+    from collections import defaultdict
+
+from cachetools import LFUCache
+
+from swimlane.core.resources.base import APIResource
+
+
+logger = logging.getLogger(__name__)
+
+
+class ResourcesCache(object):
+    """Universal APIResource instance cache
+
+    Uses separate caches per APIResource type, and provides mapping between available cache keys and real cache
+    primary key automatically
+    """
+
+    def __init__(self, per_cache_max_size):
+        self.__cache_max_size = per_cache_max_size
+        self.__caches = defaultdict(self.__cache_factory)
+        self.__cache_index_key_map = {}
+
+        if self.__cache_max_size == 0:
+            logger.debug('Cache size set to 0, resource caching disabled')
+
+    def __len__(self):
+        """Return sum of all cache sizes"""
+        return sum(c.currsize for c in self.__caches.values())
+
+    def __contains__(self, item):
+        """Check if resource is in cache, expects same 3-length tuple key as __getitem__"""
+        index_key = get_cache_index_key(item)
+        cache_key = self.__cache_index_key_map.get(index_key)
+        target_cache = self.__caches[index_key[0]]
+        return cache_key in target_cache
+
+    def __getitem__(self, item):
+        """Get cached resource, expects item to be 3-length tuple of (resource class, target key, target value)"""
+        key = get_cache_index_key(item)
+        cls = key[0]
+
+        # Check if in any fields index
+        cache_internal_key = self.__cache_index_key_map[key]
+
+        try:
+            # Return copy of cached object
+            return copy.copy(self.__caches[cls][cache_internal_key])
+        except KeyError:
+            # Internal cache miss for target resource, quietly remove from cache key map and let error bubble
+            self.__cache_index_key_map.pop(key, None)
+            raise
+
+    def __delitem__(self, resource):
+        """Remove resource instance from internal cache"""
+        self.__caches[type(resource)].pop(resource.get_cache_internal_key(), None)
+
+    def __cache_factory(self):
+        """Build and return a new cache instance"""
+        return LFUCache(self.__cache_max_size)
+
+    def cache(self, resource):
+        """Insert a resource instance into appropriate resource cache"""
+        if not isinstance(resource, APIResource):
+            raise TypeError('Cannot cache "{!r}", can only cache APIResource instances'.format(resource))
+
+        # Disable inserts to cache when disabled
+        if self.__cache_max_size == 0:
+            return
+
+        try:
+            cache_internal_key = resource.get_cache_internal_key()
+            cache_index_keys = resource.get_cache_index_keys().items()
+        except NotImplementedError:
+            logger.warning(
+                'Not caching "{!r}", resource did not provide all necessary cache details'.format(resource)
+            )
+        else:
+            resource_type = type(resource)
+
+            for key, value in cache_index_keys:
+                self.__cache_index_key_map[(resource_type, key, value)] = cache_internal_key
+
+            self.__caches[resource_type][cache_internal_key] = resource
+
+            logger.debug('Cached "{!r}"'.format(resource))
+
+    def clear(self, *resource_types):
+        """Clear cache for each provided APIResource class, or all resources if no classes are provided"""
+        resource_types = resource_types or tuple(self.__caches.keys())
+
+        for cls in resource_types:
+            # Clear and delete cache instances to guarantee no lingering references
+            self.__caches[cls].clear()
+            del self.__caches[cls]
+
+
+def get_cache_index_key(resource):
+    """Return a usable cache lookup key for an already initialized resource
+
+    Args:
+        resource (APIResource|tuple): APIResource instance or 3-length tuple key returned from this function
+
+    Raises:
+        TypeError: If resource is not an APIResource instance or acceptable 3-length tuple cache key
+    """
+    if isinstance(resource, APIResource):
+        attr, attr_value = list(resource.get_cache_index_keys().items())[0]
+        key = (type(resource), attr, attr_value)
+    else:
+        key = tuple(resource)
+
+    if len(key) != 3:
+        raise TypeError('Cache key must be tuple of (class, key, value), got "{!r}" instead'.format(key))
+
+    if not issubclass(key[0], APIResource):
+        raise TypeError('First value of cache key must be a subclass of APIResource, got "{!r}" instead'.format(key[0]))
+
+    return key
+
+
+def check_cache(resource_type):
+    """Decorator for adapter methods to check cache for resource before normally sending requests to retrieve data
+
+    Only works with single kwargs, almost always used with @one_of_keyword_only decorator
+
+    Args:
+        resource_type (type(APIResource)): Subclass of APIResource of cache to be checked when called
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                adapter = args[0]
+                key, val = list(kwargs.items())[0]
+            except IndexError:
+                logger.warning("Couldn't generate full index key, skipping cache")
+            else:
+
+                index_key = (resource_type, key, val)
+                try:
+                    cached_record = adapter._swimlane.resources_cache[index_key]
+                except KeyError:
+                    logger.debug('Cache miss: "{!r}"'.format(index_key))
+                else:
+                    logger.debug('Cache hit: "{!r}"'.format(cached_record))
+                    return cached_record
+
+            # Fallback to default function call
+            return func(*args, **kwargs)
+
+        return wrapper
+    return decorator