trello

Platypush documentation

trello#

Description#

Trello integration.

You’ll need a Trello API key. You can get it here.

You’ll also need an auth token if you want to view/change private resources. You can generate a permanent token linked to your account on https://trello.com/1/connect?key=<KEY>&name=platypush&response_type=token&expiration=never&scope=read,write.

Also, polling of events requires you to follow a separate procedure to retrieve the Websocket tokens, since Trello uses a different (and undocumented) authorization mechanism:

  1. Open https://trello.com in your browser.

  2. Open the developer tools (F12).

  3. Go to the Cookies tab.

  4. Copy the value of the cloud.session.token cookie.

Configuration#

trello:
  # [Required]
  # Trello API key. You can get it `here
  # <https://trello.com/app-key>`_.
  api_key:   # type=str

  # [Optional]
  # Trello API secret. You can get it `here
  # <https://trello.com/app-key>`_.
  # api_secret:   # type=Optional[str]

  # [Optional]
  # Trello token. It is required if you want to access or
  # modify private resources. You can get a permanent token on
  # ``https://trello.com/1/connect?key=<KEY>&name=platypush&response_type=token&expiration=never&scope=read,write``.
  # token:   # type=Optional[str]

  # [Optional]
  # Cloud session token. It is required
  # if you want to monitor your boards for changes. See
  # `TrelloPlugin <https://docs.platypush.tech/platypush/plugins/trello.html#platypush.plugins.trello.TrelloPlugin>`_ for the procedure to
  # retrieve it.
  # cloud_session_token:   # type=Optional[str]

  # [Optional]
  # List of boards to subscribe, by ID or name. If
  # specified, then the plugin will listen for changes only on these boards.
  # boards:   # type=Optional[List[str]]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install py-trello

Triggered events#

Actions#

Module reference#

class platypush.plugins.trello.TrelloPlugin(api_key: str, api_secret: str | None = None, token: str | None = None, cloud_session_token: str | None = None, boards: List[str] | None = None, **kwargs)[source]#

Bases: RunnablePlugin

Trello integration.

You’ll need a Trello API key. You can get it here.

You’ll also need an auth token if you want to view/change private resources. You can generate a permanent token linked to your account on https://trello.com/1/connect?key=<KEY>&name=platypush&response_type=token&expiration=never&scope=read,write.

Also, polling of events requires you to follow a separate procedure to retrieve the Websocket tokens, since Trello uses a different (and undocumented) authorization mechanism:

  1. Open https://trello.com in your browser.

  2. Open the developer tools (F12).

  3. Go to the Cookies tab.

  4. Copy the value of the cloud.session.token cookie.

__init__(api_key: str, api_secret: str | None = None, token: str | None = None, cloud_session_token: str | None = None, boards: List[str] | None = None, **kwargs)[source]#
Parameters:

  • api_key –

    Trello API key. You can get it here.

  • api_secret –

    Trello API secret. You can get it here.

  • token – Trello token. It is required if you want to access or modify private resources. You can get a permanent token on https://trello.com/1/connect?key=<KEY>&name=platypush&response_type=token&expiration=never&scope=read,write.

  • cloud_session_token – Cloud session token. It is required if you want to monitor your boards for changes. See platypush.plugins.trello.TrelloPlugin for the procedure to retrieve it.

  • boards – List of boards to subscribe, by ID or name. If specified, then the plugin will listen for changes only on these boards.

add_card(board: str, list: str, name: str, description: str | None = None, position: int | None = None, labels: List[str] | None = None, due: datetime | str | None = None, source: str | None = None, assign: List[str] | None = None)[source]#

Add a card to a list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

  • name – Card name

  • description – Card description

  • position – Card position index

  • labels – List of labels

  • due – Due date (datetime.datetime object or ISO-format string)

  • source – Card ID to clone from

  • assign – List of assignee member IDs

Returns:

{
  "attachments": [
    {
      "date": "2019-08-25T15:32:13.000Z",
      "edge_color": "#000000",
      "id": "5d62808da5d6a95a3a3e4f2f",
      "is_upload": true,
      "member_id": "5d62808da5d6a95a3a3e4f2f",
      "mime_type": "text/plain",
      "name": "My Attachment.txt",
      "previews": [
        {
          "height": 100,
          "id": "5d62808da5d6a95a3a3e4f2f",
          "scaled": true,
          "size": 10000,
          "url": "https://trello.com/c/5d62808da5d6a95a3a3e4f2f/my-attachment-txt.jpg",
          "width": 100
        }
      ],
      "size": 1024,
      "url": "https://trello.com/c/5d62808da5d6a95a3a3e4f2f/my-attachment.txt"
    }
  ],
  "board": {
    "closed": "Whether the board is closed.",
    "date_last_activity": "2019-08-25T15:52:45.000Z",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "lists": "The board's lists.",
    "name": "My Board",
    "url": "https://trello.com/b/5d62808da5d6a95a3a3e4f2f/my-board"
  },
  "checklists": [
    {
      "id": "5d62808da5d6a95a3a3e4f2f",
      "items": [
        {
          "checked": true,
          "id": "5d62808da5d6a95a3a3e4f2f",
          "name": "My Checklist Item"
        }
      ],
      "name": "My Checklist"
    }
  ],
  "closed": "Whether the card is closed.",
  "comments": [
    {
      "creator": {
        "avatar_url": "https://trello-avatars.s3.amazonaws.com/5d62808da5d6a95a3a3e4f2f/50.png",
        "fullname": "My Full Name",
        "id": "5d62808da5d6a95a3a3e4f2f",
        "initials": "MFN",
        "username": "myusername"
      },
      "date": "2019-08-25T15:32:13.000Z",
      "id": "5d62808da5d6a95a3a3e4f2f",
      "text": "My comment's text.",
      "type": "commentCard"
    }
  ],
  "date_last_activity": "2019-08-25T15:52:45.000Z",
  "description": "My card's description.",
  "due_date": "2019-08-25T15:52:45.000Z",
  "id": "5d62808da5d6a95a3a3e4f2f",
  "is_due_complete": "Whether the card is due complete.",
  "labels": [
    {
      "color": "green",
      "id": "5d62808da5d6a95a3a3e4f2f",
      "name": "My Label"
    }
  ],
  "latest_card_move_date": "2019-08-25T15:52:45.000Z",
  "list": {
    "closed": "Whether the list is closed.",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "name": "My List",
    "subscribed": "Whether the list is subscribed."
  },
  "name": "My Card",
  "url": "https://trello.com/c/5d62808da5d6a95a3a3e4f2f/my-card"
}

add_card_member(card_id: str, member_id: str)[source]#

Add a member to a card.

Parameters:

  • card_id – Card ID

  • member_id – Member ID

add_checklist(card_id: str, title: str, items: List[str], states: List[bool] | None = None)[source]#

Add a checklist to a card.

Parameters:

  • card_id – Card ID

  • title – Checklist title

  • items – List of items in the checklist

  • states – State of each item, True for checked, False for unchecked

add_label(card_id: str, label: str)[source]#

Add a label to a card.

Parameters:

  • card_id – Card ID

  • label – Label name

add_list(board: str, name: str, pos: int | None = None)[source]#

Add a list to a board.

Parameters:

  • board – Board ID or name

  • name – List name

  • pos – Optional position (default: last)

add_member(board: str, member_id: str, member_type: str = 'normal')[source]#

Add a member to a board.

Parameters:

  • board – Board ID or name.

  • member_id – Member ID to add.

  • member_type – Member type - can be ‘normal’ or ‘admin’ (default: ‘normal’).

archive_all_cards(board: str, list: str)[source]#

Archive all the cards on a list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

assign_card(card_id: str, member_id: str)[source]#

Assign a card.

Parameters:

  • card_id – Card ID

  • member_id – Member ID

attach_card(card_id: str, name: str | None = None, mime_type: str | None = None, file: str | None = None, url: str | None = None)[source]#

Add an attachment to a card. It can be either a local file or a remote URL.

Parameters:

  • card_id – Card ID

  • name – File name

  • mime_type – MIME type

  • file – Path to the file

  • url – URL to the file

card_subscribe(card_id: str)[source]#

Subscribe to a card. :param card_id: Card ID

change_card_board(card_id: str, board: str, list: str | None = None)[source]#

Move a card to a new board.

Parameters:

  • card_id – Card ID

  • board – New board ID or name

  • list – Optional target list ID or name

change_card_list(card_id: str, list: str)[source]#

Move a card to a new list.

Parameters:

  • card_id – Card ID

  • list – List ID or name

change_card_pos(card_id: str, position: int)[source]#

Move a card to a new position.

Parameters:

  • card_id – Card ID

  • position – New position index

close_board(board: str)[source]#

Close/archive a board.

Parameters:

board – Board ID or name

close_card(card_id: str)[source]#

Close/archive a card.

Parameters:

card_id – Card ID

close_list(board: str, list: str)[source]#

Close/archive a list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

comment_card(card_id: str, text: str)[source]#

Add a comment to a card.

Parameters:

  • card_id – Card ID

  • text – Comment text

create_label(board: str, name: str, color: str | None = None)[source]#

Add a label to a board.

Parameters:

  • board – Board ID or name

  • name – Label name

  • color – Optional HTML color

delete_card(card_id: str)[source]#

Permanently delete a card.

Parameters:

card_id – Card ID

delete_comment(card_id: str, comment_id: str)[source]#

Delete a comment.

Parameters:

  • card_id – Card ID

  • comment_id – Comment ID

delete_label(board: str, label: str)[source]#

Delete a label from a board.

Parameters:

  • board – Board ID or name

  • label – Label ID or name

get_admin_members(board: str)[source]#

Get the list of the admin members of a board.

Parameters:

board – Board ID or name.

Returns:

[
  {
    "bio": "My bio.",
    "fullname": "My Full Name",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "initials": "MFN",
    "member_type": "admin",
    "username": "myusername"
  }
]

get_board(board: str)[source]#

Get the info about a board.

Parameters:

board – Board ID or name

Returns:

{
  "closed": "Whether the board is closed.",
  "date_last_activity": "2019-08-25T15:52:45.000Z",
  "id": "5d62808da5d6a95a3a3e4f2f",
  "lists": "The board's lists.",
  "name": "My Board",
  "url": "https://trello.com/b/5d62808da5d6a95a3a3e4f2f/my-board"
}

get_boards(all: bool = False)[source]#

Get the list of boards.

Parameters:

all – If True, return all the boards included those that have been closed/archived/deleted. Otherwise, only return open/active boards (default: False).

Returns:

[
  {
    "closed": "Whether the board is closed.",
    "date_last_activity": "2019-08-25T15:52:45.000Z",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "lists": "The board's lists.",
    "name": "My Board",
    "url": "https://trello.com/b/5d62808da5d6a95a3a3e4f2f/my-board"
  }
]

get_cards(board: str, list: str | None = None, all: bool = False)[source]#

Get the list of cards on a board.

Parameters:

  • board – Board ID or name

  • list – List ID or name. If set then the method will only return the cards found on that list (default: None)

  • all – If True, return all the cards included those that have been closed/archived/deleted. Otherwise, only return open/active cards (default: False).

Returns:

[
  {
    "attachments": [
      {
        "date": "2019-08-25T15:32:13.000Z",
        "edge_color": "#000000",
        "id": "5d62808da5d6a95a3a3e4f2f",
        "is_upload": true,
        "member_id": "5d62808da5d6a95a3a3e4f2f",
        "mime_type": "text/plain",
        "name": "My Attachment.txt",
        "previews": [
          {
            "height": 100,
            "id": "5d62808da5d6a95a3a3e4f2f",
            "scaled": true,
            "size": 10000,
            "url": "https://trello.com/c/5d62808da5d6a95a3a3e4f2f/my-attachment-txt.jpg",
            "width": 100
          }
        ],
        "size": 1024,
        "url": "https://trello.com/c/5d62808da5d6a95a3a3e4f2f/my-attachment.txt"
      }
    ],
    "board": {
      "closed": "Whether the board is closed.",
      "date_last_activity": "2019-08-25T15:52:45.000Z",
      "id": "5d62808da5d6a95a3a3e4f2f",
      "lists": "The board's lists.",
      "name": "My Board",
      "url": "https://trello.com/b/5d62808da5d6a95a3a3e4f2f/my-board"
    },
    "checklists": [
      {
        "id": "5d62808da5d6a95a3a3e4f2f",
        "items": [
          {
            "checked": true,
            "id": "5d62808da5d6a95a3a3e4f2f",
            "name": "My Checklist Item"
          }
        ],
        "name": "My Checklist"
      }
    ],
    "closed": "Whether the card is closed.",
    "comments": [
      {
        "creator": {
          "avatar_url": "https://trello-avatars.s3.amazonaws.com/5d62808da5d6a95a3a3e4f2f/50.png",
          "fullname": "My Full Name",
          "id": "5d62808da5d6a95a3a3e4f2f",
          "initials": "MFN",
          "username": "myusername"
        },
        "date": "2019-08-25T15:32:13.000Z",
        "id": "5d62808da5d6a95a3a3e4f2f",
        "text": "My comment's text.",
        "type": "commentCard"
      }
    ],
    "date_last_activity": "2019-08-25T15:52:45.000Z",
    "description": "My card's description.",
    "due_date": "2019-08-25T15:52:45.000Z",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "is_due_complete": "Whether the card is due complete.",
    "labels": [
      {
        "color": "green",
        "id": "5d62808da5d6a95a3a3e4f2f",
        "name": "My Label"
      }
    ],
    "latest_card_move_date": "2019-08-25T15:52:45.000Z",
    "list": {
      "closed": "Whether the list is closed.",
      "id": "5d62808da5d6a95a3a3e4f2f",
      "name": "My List",
      "subscribed": "Whether the list is subscribed."
    },
    "name": "My Card",
    "url": "https://trello.com/c/5d62808da5d6a95a3a3e4f2f/my-card"
  }
]

get_lists(board: str, all: bool = False)[source]#

Get the list of lists on a board.

Parameters:

  • board – Board ID or name

  • all – If True, return all the lists, included those that have been closed/archived/deleted. Otherwise, only return open/active lists (default: False).

Returns:

[
  {
    "closed": "Whether the list is closed.",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "name": "My List",
    "subscribed": "Whether the list is subscribed."
  }
]

get_members(board: str)[source]#

Get the list of all the members of a board.

Parameters:

board – Board ID or name.

Returns:

[
  {
    "bio": "My bio.",
    "fullname": "My Full Name",
    "id": "5d62808da5d6a95a3a3e4f2f",
    "initials": "MFN",
    "member_type": "admin",
    "username": "myusername"
  }
]

list_subscribe(board: str, list: str)[source]#

Subscribe to a list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

list_unsubscribe(board: str, list: str)[source]#

Unsubscribe from a list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

main()[source]#

Implementation of the main loop of the plugin.

move_all_cards(board: str, src: str, dest: str)[source]#

Move all the cards from a list to another.

Parameters:

  • board – Board ID or name

  • src – Source list

  • dest – Target list

move_list(board: str, list: str, position: int)[source]#

Move a list to another position.

Parameters:

  • board – Board ID or name

  • list – List ID or name

  • position – New position index

open_board(board: str)[source]#

Re-open/un-archive a board.

Parameters:

board – Board ID or name

open_card(card_id: str)[source]#

Open/un-archive a card.

Parameters:

card_id – Card ID

open_list(board: str, list: str)[source]#

Open/un-archive a list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

remove_attachment(card_id: str, attachment_id: str)[source]#

Remove an attachment from a card.

Parameters:

  • card_id – Card ID

  • attachment_id – Attachment ID

remove_card_due(card_id: str)[source]#

Remove the due date from a card.

Parameters:

card_id – Card ID

remove_card_due_complete(card_id: str)[source]#

Remove the due complete flag from a card.

Parameters:

card_id – Card ID

remove_card_member(card_id: str, member_id: str)[source]#

Remove a member from a card.

Parameters:

  • card_id – Card ID

  • member_id – Member ID

remove_label(card_id: str, label: str)[source]#

Remove a label from a card.

Parameters:

  • card_id – Card ID

  • label – Label name

remove_member(board: str, member_id: str)[source]#

Remove a member from a board.

Parameters:

  • board – Board ID or name.

  • member_id – Member ID to remove.

set_board_description(board: str, description: str)[source]#

Change the description of a board.

Parameters:

  • board – Board ID or name.

  • description – New description.

set_board_name(board: str, name: str)[source]#

Change the name of a board.

Parameters:

  • board – Board ID or name.

  • name – New name.

set_card_description(card_id: str, description: str)[source]#

Change the description of a card.

Parameters:

  • card_id – Card ID

  • description – New description

set_card_due(card_id: str, due: str | datetime)[source]#

Set the due date for a card.

Parameters:

  • card_id – Card ID

  • due – Due date, as a datetime.datetime object or an ISO string

set_card_due_complete(card_id: str)[source]#

Set the due date of a card as completed.

Parameters:

card_id – Card ID

set_card_name(card_id: str, name: str)[source]#

Change the name of a card.

Parameters:

  • card_id – Card ID

  • name – New name

set_list_name(board: str, list: str, name: str)[source]#

Change the name of a board list.

Parameters:

  • board – Board ID or name

  • list – List ID or name

  • name – New name

start()#

Start the plugin.

stop()[source]#

Stop the plugin.

unassign_card(card_id: str, member_id: str)[source]#

Un-assign a card.

Parameters:

  • card_id – Card ID

  • member_id – Member ID

update_comment(card_id: str, comment_id: str, text: str)[source]#

Update the content of a comment.

Parameters:

  • card_id – Card ID

  • comment_id – Comment ID

  • text – New comment text

wait_stop(timeout=None)#

Wait until a stop event is received.

Platypush documentation