Skip to content

Label

CLASS DESCRIPTION
Label

Python interface for Planka Labels

Label 

Label(schema: Schema, session: Planka)

Bases: PlankaModel[Label]

Python interface for Planka Labels

Returned by: Used by:
METHOD DESCRIPTION
add_to_board

Add the Label to a Board or return a matching Label from the Board.
copy

Create a deepcopy of the model and its associated schema.
delete

Delete the Label
diff

Get a schema diff between two model schemas.
get_cards

All Cards that have this Label in the Board
sync

Sync the Label with the Planka server
update

Update the Label
ATTRIBUTE DESCRIPTION
__formatter__

Formatter func that allows overriding str behavior for models

TYPE: ModelFormatter[Self]

board

The Board the Label belongs to

TYPE: Board

color

Color of the label

TYPE: LabelColor

created_at

When the label was created

TYPE: datetime

name

Name/title of the Label

TYPE: str

position

Position of the Label within the Board

TYPE: int

updated_at

When the label was last updated

TYPE: datetime

Source code in src/plankapy/v2/models/_base.py 
30
31
32
33
34
35
36
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

board property 

board: Board

The Board the Label belongs to

color property writable 

color: LabelColor

Color of the label

created_at property 

created_at: datetime

When the label was created

name property writable 

name: str

Name/title of the Label

position property writable 

position: int

Position of the Label within the Board

updated_at property 

updated_at: datetime

When the label was last updated

add_to_board 

add_to_board(board: Board, *, position: Position = 'top', color: LabelColor | None = None) -> Label

Add the Label to a Board or return a matching Label from the Board.

PARAMETER DESCRIPTION

board

The Board to add the Label to

TYPE: Board

position

The position of the Label within the Board (default: top)

TYPE: Position DEFAULT: 'top'

color

Optionally change the LabelColor in the new Board

TYPE: LabelColor | None DEFAULT: None

RETURNS DESCRIPTION
Label

The new Label or the matching Label (same color and name)

TYPE: Label

Note

Matching is determines by name and color, if a Label matches on the board, but a color override is set, a new label will be created. If the label is already on the board, the input label is returned

Source code in src/plankapy/v2/models/label.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def add_to_board(self, board: Board, 
                 *, 
                 position: Position='top',
                 color: LabelColor|None=None) -> Label:
    """Add the Label to a Board or return a matching Label from the Board.

    Args:
        board (Board): The Board to add the Label to
        position (Position): The position of the Label within the Board (default: `top`)
        color (LabelColor | None): Optionally change the LabelColor in the new Board

    Returns:
        Label: The new Label or the matching Label (same color and name)

    Note:
        Matching is determines by name and color, if a Label matches on the board, but a color 
        override is set, a new label will be created. If the label is already on the board, the 
        input label is returned
    """
    # Don't re-add label to same board
    if board == self.board:
        return self

    # Don't add the Label if one with matching name and color exists
    # If a color override is set, allow the creation of a new label
    for lbl in board.labels:
        if (lbl.name, lbl.color) == (self.name, self.color) and color == self.color:
            return lbl

    _schema = self.schema.copy()
    _schema['boardId'] = board.id
    _schema['position'] = get_position(board.labels, position)

    # Update color
    if color is not None:
        _schema['color'] = color
    return Label(self.endpoints.createLabel(**_schema)['item'], self.session)

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 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
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)

delete 

delete()

Delete the Label

Source code in src/plankapy/v2/models/label.py 
79
80
81
def delete(self):
    """Delete the Label"""
    return self.endpoints.deleteLabel(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 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
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
    }

get_cards 

get_cards() -> list[Card]

All Cards that have this Label in the Board

Source code in src/plankapy/v2/models/label.py 
121
122
123
124
125
126
127
128
129
@model_list
def get_cards(self) -> list[Card]:
    """All Cards that have this Label in the Board"""
    return [
        cl.card
        for cl in self.board.card_labels
        # Avoid initializing another Label
        if cl.schema['labelId'] == self.schema['id']
    ]

sync 

sync()

Sync the Label with the Planka server

Source code in src/plankapy/v2/models/label.py 
69
70
71
72
73
def sync(self):
    """Sync the Label with the Planka server"""
    _lbls = [l for l in self.board.labels if l == self]
    if _lbls:
        self.schema = _lbls.pop().schema

update 

update(**kwargs: Unpack[Request_updateLabel])

Update the Label

Source code in src/plankapy/v2/models/label.py 
75
76
77
def update(self, **kwargs: Unpack[paths.Request_updateLabel]):
    """Update the Label"""
    self.schema = self.endpoints.updateLabel(self.id, **kwargs)['item']