Board

CLASS	DESCRIPTION
Board	Python interface for Planka Boards

Board

Board(schema: Schema, session: Planka)

Bases: PlankaModel[Board]

Python interface for Planka Boards

Returned by:

• Plankapy v2 models
  • Action  Action  board
  • Board Membership  BoardMembership  board
  • Card  Card  board
  • Custom Field Group  CustomFieldGroup  board
  • Label  Label  board
  • List  List  board
  • Notification  Notification  board
  • Notification Service  NotificationService  board
  • Project  Project
    •  boards
    •  create_board
    •  import_board

Used by:

• Plankapy v2
  • Planka Utilities
    •  board_to_csv
    •  board_to_table
  • models
    • Label  Label  add_to_board
    • User  User
      •  add_to_board
      •  remove_from_board

METHOD	DESCRIPTION
add_editor	Add a Board editor
add_editors	Add Board editors
add_member	Add a User to the Board
add_members	Add a Users to the Board
add_viewer	Add a Board viewer
add_viewers	Add a Board viewer
copy	Create a deepcopy of the model and its associated schema.
create_field_group	Create a new CustomFieldGroup on the Board
create_label	Create a new Label on the Board
create_list	Create a new List on the Board
delete	Delete the Board
diff	Get a schema diff between two model schemas.
filter	Apply a card filter to the board (apply the filter to all lists and agregate the cards)
remove_label	Remove a Label from the Board
remove_list	Remove a List from the Board
remove_user	Remove a User from the Board
remove_users	Remove Users from the Board
sync	Sync the Board with the Planka Server
update	Update the Board

ATTRIBUTE	DESCRIPTION
__formatter__	Formatter func that allows overriding str behavior for models TYPE: ModelFormatter[Self]
active_lists	Get all active Lists for the Board TYPE: list[List]
all_lists	Get all Lists associated with the Board (including archive and trash) TYPE: list[List]
always_display_card_creator	Whether to always display the Card creator TYPE: bool
archive_list	Get the archive List for the Board (archive List is not a normal List!) TYPE: List
archived_cards	Get all Cards in the Board archive list TYPE: list[Card]
attachments	Get all Attachments associated with the Board TYPE: list[Attachment]
board_memberships	Get all BoardMemberships for the Board TYPE: list[BoardMembership]
card_labels	Get all CardLabels associated with the Board TYPE: list[CardLabel]
card_memberships	Get all CardMemberships associated with the Board TYPE: list[CardMembership]
cards	Get all active Cards on the Board (use archived_cards and trashed_cards for archived/trashed Card lists) TYPE: list[Card]
closed_lists	Get all closed Lists for the Board TYPE: list[List]
created_at	When the Board was created TYPE: datetime
custom_field_groups	Get all CustomFieldGroups associated with the Board TYPE: list[CustomFieldGroup]
custom_field_values	Get all CustomFieldValues associated with the Board TYPE: list[CustomFieldValue]
custom_fields	Get all CustomFields associated with the Board TYPE: list[CustomField]
default_card_type	Default Card type for new Cards TYPE: CardType
default_view	Default view for the board TYPE: BoardView
editors	Get all editor Users for the Board TYPE: list[User]
expand_task_lists_by_default	Whether to expand TaskLists by default TYPE: bool
formal_name	Get the formal name of the board in the format {Project}->{Board} TYPE: str
labels	Get all Labels on the Board TYPE: list[Label]
limit_card_types_to_default_one	Whether to limit Card types to default one TYPE: bool
lists	Get all active/closed lists in the board (this is the one you most likely want) TYPE: list[List]
name	Name/title of the Board TYPE: str
position	Position of the Board within the Project TYPE: int
project	TheProject the Board belongs to TYPE: Project
projects	Get all Projects that the Board is associated with (use Board.Project instead, this is always one item) TYPE: list[Project]
subscribed	Whether the current user is subscribed to the Board TYPE: bool
subscribed_cards	Get all Cards on the Board that the current User is subscribed to TYPE: list[Card]
task_lists	Get all TaskLists associated with the Board TYPE: list[TaskList]
tasks	Get all Tasks associated with the Board TYPE: list[Task]
trash_list	Get the trash List for the Board (trash List is not a normal List!) TYPE: List
trashed_cards	Get all Cards in the Board trash list TYPE: list[Card]
updated_at	When the Board was last updated TYPE: datetime
users	Get all Users on the Board TYPE: list[User]
viewers	Get all viewer Users for the Board TYPE: list[User]

Source code in src/plankapy/v2/models/_base.py

def __init__(self, schema: Schema, session: Planka) -> None:
    self._schema = schema
    self.session = session
    self.endpoints = session.endpoints
    self.client = session.client
    self.current_role = session.current_role
    self.current_id = session.current_id

__formatter__ class-attribute instance-attribute

__formatter__: ModelFormatter[Self] = DEFAULT_FORMATTER

Formatter func that allows overriding str behavior for models

active_lists property

active_lists: list[List]

Get all active Lists for the Board

all_lists property

all_lists: list[List]

Get all Lists associated with the Board (including archive and trash)

always_display_card_creator property writable

always_display_card_creator: bool

Whether to always display the Card creator

archive_list property

archive_list: List

Get the archive List for the Board (archive List is not a normal List!)

archived_cards property

archived_cards: list[Card]

Get all Cards in the Board archive list

attachments property

attachments: list[Attachment]

Get all Attachments associated with the Board

board_memberships property

board_memberships: list[BoardMembership]

Get all BoardMemberships for the Board

card_labels property

card_labels: list[CardLabel]

Get all CardLabels associated with the Board

card_memberships property

card_memberships: list[CardMembership]

Get all CardMemberships associated with the Board

cards property

cards: list[Card]

Get all active Cards on the Board (use archived_cards and trashed_cards for archived/trashed Card lists)

closed_lists property

closed_lists: list[List]

Get all closed Lists for the Board

created_at property

created_at: datetime

When the Board was created

custom_field_groups property

custom_field_groups: list[CustomFieldGroup]

Get all CustomFieldGroups associated with the Board

custom_field_values property

custom_field_values: list[CustomFieldValue]

Get all CustomFieldValues associated with the Board

custom_fields property

custom_fields: list[CustomField]

Get all CustomFields associated with the Board

default_card_type property writable

default_card_type: CardType

Default Card type for new Cards

default_view property writable

default_view: BoardView

Default view for the board

editors property

editors: list[User]

Get all editor Users for the Board

expand_task_lists_by_default property writable

expand_task_lists_by_default: bool

Whether to expand TaskLists by default

formal_name property

formal_name: str

Get the formal name of the board in the format {Project}->{Board}

labels property

labels: list[Label]

Get all Labels on the Board

limit_card_types_to_default_one property writable

limit_card_types_to_default_one: bool

Whether to limit Card types to default one

lists property

lists: list[List]

Get all active/closed lists in the board (this is the one you most likely want)

name property writable

name: str

Name/title of the Board

position property writable

position: int

Position of the Board within the Project

project property

project: Project

TheProject the Board belongs to

projects property

projects: list[Project]

Get all Projects that the Board is associated with (use Board.Project instead, this is always one item)

subscribed property

subscribed: bool

Whether the current user is subscribed to the Board

subscribed_cards property

subscribed_cards: list[Card]

Get all Cards on the Board that the current User is subscribed to

task_lists property

task_lists: list[TaskList]

Get all TaskLists associated with the Board

tasks property

tasks: list[Task]

Get all Tasks associated with the Board

trash_list property

trash_list: List

Get the trash List for the Board (trash List is not a normal List!)

trashed_cards property

trashed_cards: list[Card]

Get all Cards in the Board trash list

updated_at property

updated_at: datetime

When the Board was last updated

users property

users: list[User]

Get all Users on the Board

viewers property

viewers: list[User]

Get all viewer Users for the Board

add_editor

add_editor(user: User) -> BoardMembership

Add a Board editor

PARAMETER	DESCRIPTION
user	The User to add as an editor TYPE: User

RETURNS	DESCRIPTION
BoardMembership	BoardMembership

Source code in src/plankapy/v2/models/board.py

def add_editor(self, user: User) -> BoardMembership:
    """Add a Board editor

    Args:
        user (User): The User to add as an editor

    Returns:
        BoardMembership
    """
    return self.add_member(user, role='editor', can_comment=True)

add_editors

add_editors(users: Sequence[User]) -> list[BoardMembership]

Add Board editors

PARAMETER	DESCRIPTION
users	The Users to add as editors TYPE: Sequence[User]

RETURNS	DESCRIPTION
list[BoardMembership]	list[BoardMembership]

Source code in src/plankapy/v2/models/board.py

@model_list
def add_editors(self, users: Sequence[User]) -> list[BoardMembership]:
    """Add Board editors

    Args:
        users (Sequence[User]): The Users to add as editors

    Returns:
        list[BoardMembership]
    """
    return [self.add_editor(user) for user in users]

add_member

add_member(user: User, *, role: BoardRole = 'viewer', can_comment: bool = False) -> BoardMembership

Add a User to the Board

PARAMETER	DESCRIPTION
user	The User to add TYPE: User
role	The Role to assign to the user (default: viewer) TYPE: Literal['viewer', 'editor'] DEFAULT: 'viewer'
can_comment	If role is viewer set commenting status (default: False) TYPE: bool DEFAULT: False

Source code in src/plankapy/v2/models/board.py

def add_member(self, user: User, 
               *,
               role: BoardRole='viewer',
               can_comment: bool=False) -> BoardMembership:
    """Add a User to the Board

    Args:
        user (User): The User to add
        role (Literal['viewer', 'editor']): The Role to assign to the user (default: `viewer`)
        can_comment (bool): If role is `viewer` set commenting status (default: `False`)
    """
    # Create a new membership
    if user not in self.users:
        BoardMembership(
            self.endpoints.createBoardMembership(
                self.id, 
                userId=user.id, 
                role=role, 
                canComment=can_comment)['item'], 
            self.session
        )

    # Get existing membership and update role different
    membership = [bm for bm in self.board_memberships if bm.user == user].pop()
    if membership.role != role:
        membership.role = role
    if membership.can_comment != can_comment:
        membership.can_comment = can_comment
    return membership

add_members

add_members(users: Sequence[User], *, role: BoardRole = 'viewer', can_comment: bool = False) -> list[BoardMembership]

Add a Users to the Board

PARAMETER	DESCRIPTION
users	The Users to add TYPE: Sequence[User]
role	The Role to assign to the user (default: viewer) TYPE: Literal['viewer', 'editor'] DEFAULT: 'viewer'
can_comment	If role is viewer set commenting status (default: False) TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
list[BoardMembership]	list[BoardMembership]

Source code in src/plankapy/v2/models/board.py

@model_list
def add_members(self, users: Sequence[User], 
                *,
                role: BoardRole='viewer',
                can_comment: bool=False) -> list[BoardMembership]:
    """Add a Users to the Board

    Args:
        users (Sequence[User]): The Users to add
        role (Literal['viewer', 'editor']): The Role to assign to the user (default: `viewer`)
        can_comment (bool): If role is `viewer` set commenting status (default: `False`)

    Returns:
        list[BoardMembership]
    """
    return [
        self.add_member(
            user,
            role=role,
            can_comment=can_comment,
        )
        for user in users
    ]

add_viewer

add_viewer(user: User, *, can_comment: bool = False) -> BoardMembership

Add a Board viewer

PARAMETER	DESCRIPTION
user	The User to add as a viewer TYPE: User
can_comment	Whether the viewer User can comment on cards TYPE: bool DEFAULT: False

Source code in src/plankapy/v2/models/board.py

def add_viewer(self, user: User, *, can_comment: bool=False) -> BoardMembership:
    """Add a Board viewer

    Args:
        user (User): The User to add as a viewer
        can_comment (bool): Whether the viewer User can comment on cards
    """
    return self.add_member(user, role='viewer', can_comment=can_comment)

add_viewers

add_viewers(users: Sequence[User], *, can_comment: bool = False) -> list[BoardMembership]

Add a Board viewer

PARAMETER	DESCRIPTION
users	The Users to add as viewers TYPE: Sequence[User]
can_comment	Whether the viewer Users can comment on cards TYPE: bool DEFAULT: False

Source code in src/plankapy/v2/models/board.py

@model_list
def add_viewers(self, users: Sequence[User], *, can_comment: bool=False) -> list[BoardMembership]:
    """Add a Board viewer

    Args:
        users (Sequence[User]): The Users to add as viewers
        can_comment (bool): Whether the viewer Users can comment on cards
    """
    return [self.add_viewer(user, can_comment=can_comment) for user in users]

copy

copy() -> Self

Create a deepcopy of the model and its associated schema.

Note

Since the endpoints for both instances of the Model are the same, any calls to update will restore the state and bring both copies into sync. copies like this are meant more for comparing changes when running a sync or update/assignemnt operation.

Example:

    >>> card_copy = card.copy()
    >>> card.name = 'Updated Name'
    >>> card_copy.name
    'Original Name'
    >>> card.name
    'Updated Name'
    >>> # This update may have had side effects
    >>> print(card_copy.diff(card))
    {'name': ('Original Name', 'Updated Name'), 'updatedAt': ('...2:00pm', '...2:45pm'), ...}

Source code in src/plankapy/v2/models/_base.py

def copy(self) -> Self:
    """Create a deepcopy of the model and its associated schema.

    Note:
        Since the endpoints for both instances of the Model are the same, any 
        calls to update will restore the state and bring both copies into sync. 
        copies like this are meant more for comparing changes when running a sync 
        or update/assignemnt operation.

    Example:
    ```python
        >>> card_copy = card.copy()
        >>> card.name = 'Updated Name'
        >>> card_copy.name
        'Original Name'
        >>> card.name
        'Updated Name'
        >>> # This update may have had side effects
        >>> print(card_copy.diff(card))
        {'name': ('Original Name', 'Updated Name'), 'updatedAt': ('...2:00pm', '...2:45pm'), ...}
    ```
    """
    return copy.deepcopy(self)

create_field_group

create_field_group(name: str | None = None, *, position: Position = 'top', base_group: BaseCustomFieldGroup | None = None) -> CustomFieldGroup

Create a new CustomFieldGroup on the Board

PARAMETER	DESCRIPTION
name	The name of the Custom Field Group TYPE: str | None DEFAULT: None
position	The position of the field group within the board TYPE: Position DEFAULT: 'top'
base_group	An optional BaseCustomFieldGroup to use as a template TYPE: BaseCustomFieldGroup | None DEFAULT: None

Source code in src/plankapy/v2/models/board.py

def create_field_group(self, 
                       name: str|None=None, 
                       *, 
                       position: Position= 'top', 
                       base_group: BaseCustomFieldGroup|None=None) -> CustomFieldGroup:
    """Create a new CustomFieldGroup on the Board

    Args:
        name: The name of the Custom Field Group
        position: The position of the field group within the board
        base_group: An optional BaseCustomFieldGroup to use as a template
    """
    args: paths.Request_createBoardCustomFieldGroup = {
        'name': name,
        'position': get_position(self.custom_field_groups, position)
    }
    if base_group:
        args['baseCustomFieldGroupId'] = base_group.id
        args['name'] = args['name'] or base_group.name
    return CustomFieldGroup(
        self.endpoints.createBoardCustomFieldGroup(self.id, **args)['item'],
        self.session
    )

create_label

create_label(*, name: str, position: Position = 'top', color: LabelColor | Literal['random'] = 'random') -> Label

Create a new Label on the Board

PARAMETER	DESCRIPTION
name	The name of the Label TYPE: str
positon	The position of the label in the label list
color	An optional color for the label (a random unused color by default) TYPE: LabelColor | Literal['random'] DEFAULT: 'random'

Source code in src/plankapy/v2/models/board.py

def create_label(self, 
                 *,
                 name: str,
                 position: Position='top',
                 color: LabelColor|Literal['random']='random') -> Label:
    """Create a new Label on the Board

    Args:
        name: The name of the Label
        positon: The position of the label in the label list
        color: An optional color for the label (a random unused color by default)
    """
    l = Label(
        self.endpoints.createLabel(
            self.id, 
            name=name,
            position=get_position(self.labels, position),
            color=color if color != 'random' else choice(LabelColors))['item'], 
            self.session
        )
    return l

create_list

create_list(*, name: str, type: Literal['active', 'closed'] = 'active', position: Position = 'top', color: ListColor | Literal['random'] | None = None) -> List

Create a new List on the Board

PARAMETER	DESCRIPTION
name	Name/title of the List TYPE: str
type	Type/status of the List TYPE: Literal['active', 'closed'] DEFAULT: 'active'
position	Position of the List within the Board TYPE: Position DEFAULT: 'top'
color	An optional color to set the list to (random to randomize) TYPE: ListColor | Literal['random'] | None DEFAULT: None

Source code in src/plankapy/v2/models/board.py

def create_list(self, 
                *, 
                name: str,
                type: Literal['active', 'closed']='active',
                position: Position = 'top',
                color: ListColor|Literal['random']|None=None) -> List:
    """Create a new List on the Board

    Args:
        name: Name/title of the List
        type: Type/status of the List
        position: Position of the List within the Board
        color: An optional color to set the list to (`random` to randomize)
    """
    l = List(
        self.endpoints.createList(
            self.id, 
            name=name,
            type=type,
            position=get_position(self.active_lists + self.closed_lists, position))['item'], 
        self.session
    )
    if color:
        l.color = color
    return l

delete

delete()

Delete the Board

Source code in src/plankapy/v2/models/board.py

def delete(self):
    """Delete the Board"""
    return self.endpoints.deleteBoard(self.id)

diff

diff(other: PlankaModel[Schema]) -> Diff

Get a schema diff between two model schemas.

Note

Only matching keys are diffed. Any schema keys that are not in the source schema will not be checked in the target schema

Source code in src/plankapy/v2/models/_base.py

def diff(self, other: PlankaModel[Schema]) -> Diff:
    """Get a schema diff between two model schemas.

    Note:
        Only matching keys are diffed. Any schema keys that are not in the source schema 
        will not be checked in the target schema
    """
    return {
        k: (source, delta) 
        for k, source in self.schema
        if k in other.schema
        and (delta := other.schema[k]) 
        and delta != source
    }

filter

filter(*, search: str | None = None, users: User | Sequence[User] | None = None, labels: Label | Sequence[Label] | None = None, card_before: Card | None = None, changed_before: datetime | None = None) -> list[Card]

Apply a card filter to the board (apply the filter to all lists and agregate the cards)

PARAMETER	DESCRIPTION
search	A search term to apply to the cards TYPE: str | None DEFAULT: None
users	A list of Users to filter the cards by TYPE: User | Sequence[User] | None DEFAULT: None
labels	A list of Labels to filter the cards by TYPE: Label | Sequence[Label] | None DEFAULT: None
card_before	Limit filter to only cards before this card TYPE: Card | None DEFAULT: None
changed_before	A time filter that filters on list_changed_at TYPE: datetime | None DEFAULT: None

Source code in src/plankapy/v2/models/board.py

@model_list
def filter(self, 
           *,
           search: str|None=None,
           users: User|Sequence[User]|None=None,
           labels: Label|Sequence[Label]|None=None,
           card_before: Card|None=None,
           changed_before: datetime|None=None) -> list[Card]:
    """Apply a card filter to the board (apply the filter to all lists and agregate the cards)

    Args:
        search: A search term to apply to the cards
        users: A list of Users to filter the cards by
        labels: A list of Labels to filter the cards by
        card_before: Limit filter to only cards before this card
        changed_before: A time filter that filters on `list_changed_at`
    """
    return [
        card
        for l in self.lists
        for card in l.filter(
            search=search, 
            users=users, 
            labels=labels, 
            card_before=card_before, 
            changed_before=changed_before
        ) 
    ]

remove_label

remove_label(label: Label) -> None

Remove a Label from the Board

PARAMETER	DESCRIPTION
label	The Label to remove (must be associated with the board) TYPE: Label

Source code in src/plankapy/v2/models/board.py

def remove_label(self, label: Label) -> None:
    """Remove a Label from the Board

    Args:
        label (Label): The Label to remove (must be associated with the board)
    """
    if label in self.labels:
        label.delete()

remove_list

remove_list(list: List) -> None

Remove a List from the Board

PARAMETER	DESCRIPTION
list	The list to remove (must be associated with the Board and not trash or archive) TYPE: List

Source code in src/plankapy/v2/models/board.py

def remove_list(self, list: List) -> None:
    """Remove a List from the Board

    Args:
        list (List): The list to remove (must be associated with the Board and not `trash` or `archive`)
    """
    if list in self.active_lists:
        list.delete()

remove_user

remove_user(user: User) -> User | None

Remove a User from the Board

Note

If the User is not a member, no change will be made and None will be returned

Source code in src/plankapy/v2/models/board.py

def remove_user(self, user: User) -> User | None:
    """Remove a User from the Board

    Note:
        If the User is not a member, no change will be made and None will be returned
    """
    if (membership := self.board_memberships[{'userId': user.id}].dpop()):
        membership.delete()
        return user

remove_users

remove_users(users: Sequence[User]) -> list[User]

Remove Users from the Board

Note

If a User is not a member, no change will be made and they will be excluded from the returned user list

Source code in src/plankapy/v2/models/board.py

@model_list
def remove_users(self, users: Sequence[User]) -> list[User]:
    """Remove Users from the Board

    Note:
        If a User is not a member, no change will be made and they will 
        be excluded from the returned user list
    """
    return [removed for u in users if (removed := self.remove_user(u))]

sync

sync() -> None

Sync the Board with the Planka Server

Source code in src/plankapy/v2/models/board.py

def sync(self) -> None:
    """Sync the Board with the Planka Server"""
    self.schema = self.endpoints.getBoard(self.id)['item']

update

update(**board: Unpack[Request_updateBoard]) -> None

Update the Board

Source code in src/plankapy/v2/models/board.py

def update(self, **board: Unpack[paths.Request_updateBoard]) -> None:
    """Update the Board"""
    self.schema = self.endpoints.updateBoard(self.id, **board)['item']