# -*- coding: utf-8 -*- from __future__ import with_statement, print_function, absolute_import import datetime from operator import itemgetter import pytz from dateutil import parser as dateparser from trello import TrelloBase from trello.attachments import Attachments from trello.checklist import Checklist from trello.compat import force_str from trello.label import Label from trello.organization import Organization from trello.customfield import CustomField, CustomFieldText, CustomFieldCheckbox, CustomFieldNumber, CustomFieldDate, CustomFieldList class Card(TrelloBase): """ Class representing a Trello card. Card attributes are stored on the object https://developers.trello.com/advanced-reference/card """ @property def short_url(self): return self.shortUrl @property def member_id(self): return self.idMembers @property def short_id(self): return self.idShort @property def list_id(self): return self.idList @property def board_id(self): return self.idBoard @property def description(self): return self.desc @property def date_last_activity(self): return self.dateLastActivity @property def labels(self): return self._labels if self._labels else [] @property def custom_fields(self): """ Lazily loads and returns the custom fields """ if self.customFields is None: self.customFields = self.fetch_custom_fields() return self.customFields @property def comments(self): """ Lazily loads and returns the comments """ if self._comments is None: self._comments = self.fetch_comments() return self._comments @property def checklists(self): """ Lazily loads and returns the checklists """ if self._checklists is None: self._checklists = self.fetch_checklists() return self._checklists @property def plugin_data(self): """ Lazily loads and returns the plugin data """ if self._plugin_data is None: self._plugin_data = self.fetch_plugin_data() return self._plugin_data @property def attachments(self): """ Lazily loads and returns the attachments """ if self._attachments is None: self._attachments = self.fetch_attachments() return self._attachments def __init__(self, parent, card_id, name=''): """ :parent: reference to the parent trello list :card_id: ID for this card """ super(Card, self).__init__() if isinstance(parent, List): self.trello_list = parent self.board = parent.board else: self.board = parent self.client = parent.client self.id = card_id self.name = name self.customFields = None self._checklists = None self._comments = None self._plugin_data = None self._attachments = None self._labels = None self._json_obj = None @classmethod def from_json(cls, parent, json_obj): """ Deserialize the card json object to a Card object :parent: the list object that the card belongs to :json_obj: json object :rtype: Card """ if 'id' not in json_obj: raise Exception("key 'id' is not in json_obj") card = cls(parent, json_obj['id'], name=json_obj['name']) card._json_obj = json_obj card.desc = json_obj.get('desc', '') card.due = json_obj.get('due', '') card.is_due_complete = json_obj['dueComplete'] card.closed = json_obj['closed'] card.url = json_obj['url'] card.pos = json_obj['pos'] card.shortUrl = json_obj['shortUrl'] card.idMembers = json_obj['idMembers'] card.member_ids = json_obj['idMembers'] card.idLabels = json_obj['idLabels'] card.idBoard = json_obj['idBoard'] card.idList = json_obj['idList'] card.idShort = json_obj['idShort'] card.badges = json_obj['badges'] card.customFields = card.fetch_custom_fields(json_obj=json_obj) card.countCheckItems = json_obj['badges']['checkItems'] card.countCheckLists = len(json_obj['idChecklists']) card._labels = Label.from_json_list(card.board, json_obj['labels']) card.dateLastActivity = dateparser.parse(json_obj['dateLastActivity']) if "attachments" in json_obj: card._attachments = [] for attachment_json in json_obj["attachments"]: card._attachments.append(attachment_json) if 'actions' in json_obj: card.actions = json_obj['actions'] return card def __repr__(self): return force_str(u'' % self.name) def fetch(self, eager=True): """ Fetch all attributes for this card :param eager: If eager, comments, checklists and attachments will be fetched immediately, otherwise on demand """ json_obj = self.client.fetch_json( '/cards/' + self.id, query_params={'badges': False, 'customFieldItems': 'true'}) self.id = json_obj['id'] self.name = json_obj['name'] self.desc = json_obj.get('desc', '') self.closed = json_obj['closed'] self.url = json_obj['url'] self.shortUrl = json_obj['shortUrl'] self.idMembers = json_obj['idMembers'] self.idShort = json_obj['idShort'] self.idList = json_obj['idList'] self.idBoard = json_obj['idBoard'] self.idLabels = json_obj['idLabels'] self._labels = Label.from_json_list(self.board, json_obj['labels']) self.badges = json_obj['badges'] self.pos = json_obj['pos'] if json_obj.get('due', ''): self.due = json_obj.get('due', '') else: self.due = '' self.checked = json_obj['checkItemStates'] self.dateLastActivity = dateparser.parse(json_obj['dateLastActivity']) self._customFields = self.fetch_custom_fields(json_obj=json_obj) self._plugin_data = self.fetch_plugin_data() if eager else None self._checklists = self.fetch_checklists() if eager else None self._comments = self.fetch_comments() if eager else None self._attachments = self.fetch_attachments() if eager else None def fetch_custom_fields(self, json_obj=None): """ Fetch current set of custom fields from card or json_obj. """ if json_obj is None: json_obj = self.client.fetch_json( '/cards/' + self.id, query_params={'badges': False, 'customFieldItems': 'true'}) return CustomField.from_json_list( self, json_obj.get('customFieldItems', {})) def fetch_comments(self, force=False, limit=None): comments = [] if (force is True) or (self.badges['comments'] > 0): query_params = {'filter': 'commentCard,copyCommentCard'} if limit is not None: query_params['limit'] = limit comments = self.client.fetch_json( '/cards/' + self.id + '/actions', query_params=query_params) return sorted(comments, key=lambda comment: comment['date']) return comments def get_list(self): obj = self.client.fetch_json('/lists/' + self.idList) return List.from_json(board=self, json_obj=obj) def get_comments(self): """Alias for fetch_comments for backward compatibility. Always contact server """ return self.fetch_comments(force=True) def fetch_checklists(self): if self.countCheckLists == 0: return [] if not hasattr(self, "checked") or self.checked is None: self.fetch(eager=False) checklists = [] json_obj = self.client.fetch_json( '/cards/' + self.id + '/checklists', ) # Thanks https://github.com/HuffAndPuff for noticing checklist # were not sorted json_obj = sorted(json_obj, key=lambda checklist: checklist['pos']) for cl in json_obj: checklists.append(Checklist(self.client, self.checked, cl, trello_card=self.id)) return checklists def fetch_plugin_data(self): items = self.client.fetch_json( '/cards/' + self.id + '/pluginData') return items def fetch_attachments(self, force=False): if (force is True) or (self.badges['attachments'] > 0): items = self.client.fetch_json( '/cards/' + self.id + '/attachments', query_params={'filter':'false'}) return items return [] def get_attachments(self): return [Attachments.from_json(attachments_json) for attachments_json in self.fetch_attachments(force=True)] def fetch_actions(self, action_filter='createCard', since=None, before=None, action_limit=50): """ Fetch actions for this card can give more argv to action_filter, split for ',' json_obj is list """ query_params={'filter': action_filter, 'limit': action_limit} if since: query_params["since"] = since if before: query_params["before"] = before json_obj = self.client.fetch_json( '/cards/' + self.id + '/actions', query_params=query_params) self.actions = json_obj return self.actions def attriExp(self, multiple): """ Provides the option to explore what comes from trello :multiple is one of the attributes of GET /1/cards/[card id or shortlink]/actions """ self.fetch_actions(multiple) return self.actions @staticmethod def _movement_as_triplet(source_list, destination_list, movement_datetime): return [source_list["name"], destination_list["name"], movement_datetime] @staticmethod def _movement_as_dict(source_list, destination_list, movement_datetime): _movement = { "source": source_list, "destination": destination_list, "datetime": movement_datetime, } return _movement def _list_movements(self, movement_function, filter_by_date_interval=None): """ Returns the list of movements of this card. The list of movements is in descending date and time order. First movement is the closest one to now. Its structure is a list of dicts where the lists are "source" and "destination" and both are also dicts. Date and time of the movement is in key "datetime" as a datetime object. :param movement_function: function that returns a representation of the movement. :param filter_by_date_interval: Date interval used to filter card movements to return. Optional :return: list with the movements. """ action_since = None if not filter_by_date_interval else filter_by_date_interval[0] action_before = None if not filter_by_date_interval else filter_by_date_interval[1] if not hasattr(self, "actions") or self.actions is None: self.fetch_actions('updateCard:idList,', action_since, action_before) movements = [] for idx in self.actions: date_str = idx['date'] movement_datetime = dateparser.parse(date_str) source_list = idx['data']['listBefore'] destination_list = idx['data']['listAfter'] movement = movement_function(source_list, destination_list, movement_datetime) movements.append(movement) return movements def listCardMove_date(self): """Will return the history of transitions of a card from one list to another. The lower the index the more recent the historical item. It returns a list of lists. The sublists are triplets of starting list, ending list and when the transition occurred. """ return self._list_movements(movement_function=Card._movement_as_triplet) def list_movements(self, list_cmp=None, filter_by_date_interval=None): """Will return the history of transitions of a card from one list to another. The lower the index the more recent the historical item. It returns a list of dicts in date and time descending order (the first movement is the most recent). Dicts are of the form source: destination: datetime: :param: list_cmp Comparison function between lists. For list_cmp(a, b) returns -1 if list a is greater that list b. Returns 1 otherwise. :param: filter_by_date_interval: pair of two dates (two strings in YYYY-MM-DD format) to filter card movements by date. """ movement_as_dict_function = Card._movement_as_dict if list_cmp: def movement_as_dict_function(_source_list, _destination_list, _movement_datetime): _movement = Card._movement_as_dict(_source_list, _destination_list, _movement_datetime) _source_list_id = _source_list["id"] _destination_list_id = _destination_list["id"] _movement["moving_forward"] = list_cmp(_source_list_id, _destination_list_id) > 0 return _movement return self._list_movements(movement_function=movement_as_dict_function, filter_by_date_interval=filter_by_date_interval) def get_stats_by_list(self, lists, list_cmp=None, done_list=None, time_unit="seconds", card_movements_filter=None): """Gets several stats about the card by each list of the board: - time: The time that the card has been in each column in seconds (minutes or hours). - forward_moves: How many times this card has been the source of a forward movement. - backward_moves: How many times this card has been the source of a backward movement. Returns a dict where the key is list id and value is a dict with keys time, forward_moves and backward_moves. :param lists: list of board lists. :param list_cmp: function that compares two lists a,b given id_a, id_b. If b is in a forward position returns 1 else -1. :param time_unit: default to seconds. Allow specifying time in "minutes" or "hours". :param done_list: Column that implies that the task is done. If present, time measurement will be stopped if is current task list. :param card_movements_filter: Pair of two dates (two strings in YYYY-MM-DD format) that will filter the movements of the card. Optional. :return: dict of the form {list_id: {time: