List

CLASS	DESCRIPTION
List	Python interface for Planka Lists

List

List(schema: Schema, session: Planka)

Bases: PlankaModel[List]

Python interface for Planka Lists

Returned by:

• Plankapy v2 models
  • Board  Board
    •  active_lists
    •  all_lists
    •  archive_list
    •  closed_lists
    •  lists
    •  trash_list
    •  create_list
  • Card  Card
    •  list
    •  prev_list

Used by:

• Plankapy v2 models
  • Board  Board  remove_list
  • Card  Card  move
  • List  List  move_cards

METHOD	DESCRIPTION
archive_cards	Move all cards in the List to the Board archive
copy	Create a deepcopy of the model and its associated schema.
create_card	Create a new card in the List
delete	Delete the List
delete_cards	Delete all Cards in the List (must be a trash list)
diff	Get a schema diff between two model schemas.
filter	Apply a filter to the list
move_cards	Move all Cards in this List to another List
shuffle	Shuffle the cards in the List (randomize position)
sort	Sort the list using a sort function
sort_cards	Sort all cards in the List and return the sorted Cards
sync	Sync the List with the Planka server
update	Update the List

ATTRIBUTE	DESCRIPTION
__formatter__	Formatter func that allows overriding str behavior for models TYPE: ModelFormatter[Self]
attachments	Attachments associated with the List TYPE: list[Attachment]
board	The Board the List belongs to TYPE: Board
card_labels	CardLabels associated with the List TYPE: list[CardLabel]
card_memberships	CardMemberships associated with the List TYPE: list[CardMembership]
cards	Cards associated with the List TYPE: list[Card]
color	Color for the List TYPE: ListColor
created_at	When the List was created TYPE: datetime
custom_field_groups	CustomFieldGroups associated with the List TYPE: list[CustomFieldGroup]
custom_field_values	CustomFieldValues associated with the List TYPE: list[CustomFieldValue]
custom_fields	CustomFields associated with the List TYPE: list[CustomField]
name	Name/title of the List TYPE: str
position	Position of the List within the Board TYPE: int
task_lists	TaskLists associated with the List TYPE: list[TaskList]
tasks	Tasks associated with the List TYPE: list[Task]
type	Type/status of the list
updated_at	When the List was last updated TYPE: datetime
users	Users associated with the List 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

attachments property

attachments: list[Attachment]

Attachments associated with the List

board property

board: Board

The Board the List belongs to

card_labels property

card_labels: list[CardLabel]

CardLabels associated with the List

card_memberships property

card_memberships: list[CardMembership]

CardMemberships associated with the List

cards property

cards: list[Card]

Cards associated with the List

color property writable

color: ListColor

Color for the List

created_at property

created_at: datetime

When the List was created

custom_field_groups property

custom_field_groups: list[CustomFieldGroup]

CustomFieldGroups associated with the List

custom_field_values property

custom_field_values: list[CustomFieldValue]

CustomFieldValues associated with the List

custom_fields property

custom_fields: list[CustomField]

CustomFields associated with the List

name property

name: str

Name/title of the List

position property

position: int

Position of the List within the Board

task_lists property

task_lists: list[TaskList]

TaskLists associated with the List

tasks property

tasks: list[Task]

Tasks associated with the List

type property writable

type

Type/status of the list

updated_at property

updated_at: datetime

When the List was last updated

users property

users: list[User]

Users associated with the List

archive_cards

archive_cards() -> list[Card]

Move all cards in the List to the Board archive

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

@model_list
def archive_cards(self) -> list[Card]:
    """Move all cards in the List to the Board archive"""
    return [
        Card(c, self.session)
        for c in self.endpoints.moveListCards(
            self.id, 
            listId=self.board.archive_list.id
            )['included']['cards']
    ]

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_card

create_card(*, name: str, position: Position = 'bottom', type: CardType = 'project', description: str | None = None, due_date: datetime | None = None, due_date_completed: bool = False, stopwatch_duration: timedelta | None = None, stopwatch_started: datetime | Literal['now'] | None = None) -> Card

Create a new card in the List

PARAMETER	DESCRIPTION
name	The name of the Card TYPE: str
position	The position of the card within the List TYPE: Position DEFAULT: 'bottom'
type	The type of the card TYPE: CardType DEFAULT: 'project'
description	An optional description to include TYPE: str | None DEFAULT: None
due_date	A due date for the card TYPE: datetime | None DEFAULT: None
due_date_completed	If the card has been completed TYPE: bool DEFAULT: False
stopwatch_duration	The duration to include with the stopwatch TYPE: timedelta | None DEFAULT: None
stopwatch_started	The start time for the runnung stopwatch (None is paused) TYPE: datetime | Literal['now'] | None DEFAULT: None

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

def create_card(self, 
                *,
                name: str,
                position: Position='bottom',
                type: CardType='project',
                description: str|None=None,
                due_date: datetime|None=None,
                due_date_completed: bool=False,
                stopwatch_duration: timedelta|None=None,
                stopwatch_started: datetime|Literal['now']|None=None) -> Card:
    """Create a new card in the List

    Args:
        name: The name of the Card
        position: The position of the card within the List
        type: The type of the card
        description: An optional description to include
        due_date: A due date for the card
        due_date_completed: If the card has been completed
        stopwatch_duration: The duration to include with the stopwatch
        stopwatch_started: The start time for the runnung stopwatch (None is paused)

    """
    args: paths.Request_createCard = {
        'name': name,
        'position': get_position(self.cards, position),
        'type': type
    }
    # Apply optionals
    if description:
        args['description'] = description
    if due_date:
        args['dueDate'] = dttoiso(due_date, default_timezone=self.session.timezone)
    if due_date_completed:
        args['isDueCompleted'] = True

    if stopwatch_duration or stopwatch_started:
        args['stopwatch'] = {}
        if stopwatch_duration:
            args['stopwatch']['total'] = int(stopwatch_duration.total_seconds())
        if stopwatch_started:
            if stopwatch_started == 'now':
                t = datetime.now(self.session.timezone).isoformat()
            else:
                t = dttoiso(stopwatch_started, default_timezone=self.session.timezone)
            args['stopwatch']['startedAt'] = t

    return Card(
        self.endpoints.createCard(\
            self.id, 
            **args)['item'], 
            self.session
        )

delete

delete()

Delete the List

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

def delete(self):
    """Delete the List"""
    return self.endpoints.deleteList(self.id)

delete_cards

delete_cards() -> None

Delete all Cards in the List (must be a trash list)

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

def delete_cards(self) -> None:
    """Delete all Cards in the List (must be a trash list)"""
    self.endpoints.clearList(self.id)['item']

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 filter to the list

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/list_.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 filter to the list

    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`
    """

    kwargs: dict[str, Any] = {}
    if search:
        kwargs['search'] = search
    if users:
        if isinstance(users, User):
            users = [users]
        kwargs['userIds'] = ','.join(u.id for u in users)
    if labels:
        if isinstance(labels, Label):
            labels = [labels]
        kwargs['labelIds '] = ','.join(l.id for l in labels)
    if card_before or changed_before:
        kwargs['before'] = {}
    if card_before:
        kwargs['before']['id'] = card_before.id
    if changed_before:
        kwargs['before']['listChangedAt'] = dttoiso(changed_before, default_timezone=self.session.timezone)

    return [
        Card(c, self.session) 
        for c in self.endpoints.getCards(
            self.id, 
            **kwargs,
        )['items']
    ]

move_cards

move_cards(list: List, position: Position = 'top') -> list[Card]

Move all Cards in this List to another List

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

@model_list
def move_cards(self, list: List, position: Position='top') -> list[Card]:
    """Move all Cards in this List to another List"""
    cards = self.cards
    for c in self.cards:
        c.move(list, position)
    return cards

shuffle

shuffle() -> list[Card]

Shuffle the cards in the List (randomize position)

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

@model_list
def shuffle(self) -> list[Card]:
    """Shuffle the cards in the List (randomize position)"""
    cards = self.cards
    shuffle(cards)
    for pos, card in enumerate(cards, start=1):
        card.position = pos*POSITION_GAP
    return cards

sort

sort(key: Callable[[Card], Any] | None = None, reverse: bool = False) -> list[Card]

Sort the list using a sort function

PARAMETER	DESCRIPTION
key	The sorting function to use (default is card.name) TYPE: Callable[[Card], Any] | None DEFAULT: None
reverse	Reverse the sort order TYPE: bool DEFAULT: False

Note

If sorting on fields that may have comparison errors (e.g. due_date) make sure your sort key properly accounts for that:

>>> lst.sort(lambda c: c.due_date)
Exception ... # Can't compare NoneType and datetime
>>> lst.sort(lambda c: c.due_date or c.created_at+timedelta(days=10000))
[
    Card(dueDate='2026-01-20...'),
    Card(dueDate='2026-01-26...'),
    ...
]

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

@model_list
def sort(self, key: Callable[[Card], Any]|None=None, reverse: bool=False) -> list[Card]:
    """Sort the list using a sort function

    Args:
        key: The sorting function to use (default is `card.name`)
        reverse: Reverse the sort order

    Note:
        If sorting on fields that may have comparison errors (e.g. `due_date`) 
        make sure your sort key properly accounts for that: 
        ```python
        >>> lst.sort(lambda c: c.due_date)
        Exception ... # Can't compare NoneType and datetime
        >>> lst.sort(lambda c: c.due_date or c.created_at+timedelta(days=10000))
        [
            Card(dueDate='2026-01-20...'),
            Card(dueDate='2026-01-26...'),
            ...
        ]
        ```
    """
    if key is None:
        key = lambda c: c.name
    cards = self.cards
    cards.sort(key=key, reverse=reverse)
    for pos, card in enumerate(cards, start=1):
        card.position = pos*POSITION_GAP
    return cards

sort_cards

sort_cards(**kwargs: Unpack[Request_sortList]) -> list[Card]

Sort all cards in the List and return the sorted Cards

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

@model_list
def sort_cards(self, **kwargs: Unpack[paths.Request_sortList]) -> list[Card]:
    """Sort all cards in the List and return the sorted Cards"""
    return [Card(c, self.session) for c in self.endpoints.sortList(self.id, **kwargs)['included']['cards']]

sync

sync()

Sync the List with the Planka server

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

def sync(self):
    """Sync the List with the Planka server"""
    self.schema = self.endpoints.getList(self.id)['item']

update

update(**list: Unpack[Request_updateList])

Update the List

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

def update(self, **list: Unpack[paths.Request_updateList]):
    """Update the List"""
    self.endpoints.updateList(self.id, **list)