Label

Bases: Label_

Interface for interacting with planka Labels

Note

Label Colors are defined in the LabelColor Literal currently:

Source code in src/plankapy/interfaces.py

class Label(Label_):
    """Interface for interacting with planka Labels

    Note:
        Label Colors are defined in the `LabelColor` Literal
        currently:

    """
    colors = LabelColor.__args__
    colors_to_hex = LabelColorHexMap

    @property
    def board(self) -> Board:
        """Board the label belongs to

        Returns:
            Board: Board instance
        """
        board_route = self.routes.get_board(id=self.boardId)
        return Board(**board_route()['item']).bind(self.routes)

    @property
    def cards(self) -> QueryableList[Card]:
        """All cards with the label in the board

        Returns:
            Queryable List of all cards with the label in the board
        """
        return QueryableList([
            cardLabel.card
            for cardLabel in self.board.cardLabels
            if cardLabel.labelId == self.id
        ])

    @overload
    def update(self) -> Label: ...

    @overload
    def update(self, label: Label) -> Label: ...

    @overload
    def update(self, name: str=None, color: LabelColor=None, position: int=None) -> Label: ...

    def update(self, *args, **kwargs) -> Label:
        """Updates the label with new values

        Tip:
            Use `.editor()` context manager to update the label with the user as an editor

            Example:
            ```python
            >>> with label.editor():
            ...    label.name = 'My New Label'
            ...    label.color = 'lagoon-blue'

            >>> label
            Label(name='My New Label', color='lagoon-blue', position=0, ...)
            ``

        Args:
            name (str): Name of the label (optional)
            color (LabelColor): Color of the label (optional)
            position (int): Position of the label (optional)

        Args: Alternate
            label (Label): Label instance to update with

        Returns:
            Label: Updated label instance

        Raises:
            ValueError: If the color is not in the available colors
        """
        overload = parse_overload(
            args, kwargs, 
            model='label', 
            options=('name', 'color', 'position'),
            noarg=self)

        if 'color' in overload and overload['color'] not in self.colors:
            raise ValueError(
                f"Invalid color: {overload['color']}\n"
                f"Valid colors: {self.colors}")

        route = self.routes.patch_label(id=self.id)
        self.__init__(**route(**overload)['item'])
        return self

    def hex_color(self) -> str:
        """Returns the hex color of the label

        Returns:
            str: Hex color of the label
        """
        return self.colors_to_hex[self.color]

    def delete(self) -> Label:
        """Deletes the label

        Danger:
            This action is irreversible and cannot be undone

        Returns:
            Label: Deleted label instance
        """
        self.refresh()
        route = self.routes.delete_label(id=self.id)
        route()
        return self

    def refresh(self) -> None:
        """Refreshes the label data"""
        for label in self.board.labels:
            if label.id == self.id:
                self.__init__(**label)

board property

Board the label belongs to

Returns:

Name	Type	Description
Board	Board	Board instance

cards property

All cards with the label in the board

Returns:

Type	Description
QueryableList[Card]	Queryable List of all cards with the label in the board

delete()

Deletes the label

Danger

This action is irreversible and cannot be undone

Returns:

Name	Type	Description
Label	Label	Deleted label instance

Source code in src/plankapy/interfaces.py

def delete(self) -> Label:
    """Deletes the label

    Danger:
        This action is irreversible and cannot be undone

    Returns:
        Label: Deleted label instance
    """
    self.refresh()
    route = self.routes.delete_label(id=self.id)
    route()
    return self

hex_color()

Returns the hex color of the label

Returns:

Name	Type	Description
str	str	Hex color of the label

Source code in src/plankapy/interfaces.py

def hex_color(self) -> str:
    """Returns the hex color of the label

    Returns:
        str: Hex color of the label
    """
    return self.colors_to_hex[self.color]

refresh()

Refreshes the label data

Source code in src/plankapy/interfaces.py

def refresh(self) -> None:
    """Refreshes the label data"""
    for label in self.board.labels:
        if label.id == self.id:
            self.__init__(**label)

update(*args, **kwargs)

update() -> Label

update(label: Label) -> Label

update(name: str = None, color: LabelColor = None, position: int = None) -> Label

Updates the label with new values

Tip

Use .editor() context manager to update the label with the user as an editor

Example: ```python

with label.editor(): ... label.name = 'My New Label' ... label.color = 'lagoon-blue'

label Label(name='My New Label', color='lagoon-blue', position=0, ...) ``

Parameters:

Name	Type	Description	Default
name	str	Name of the label (optional)	required
color	LabelColor	Color of the label (optional)	required
position	int	Position of the label (optional)	required

Alternate

Name	Type	Description	Default
label	Label	Label instance to update with	required

Returns:

Name	Type	Description
Label	Label	Updated label instance

Raises:

Type	Description
ValueError	If the color is not in the available colors

Source code in src/plankapy/interfaces.py

def update(self, *args, **kwargs) -> Label:
    """Updates the label with new values

    Tip:
        Use `.editor()` context manager to update the label with the user as an editor

        Example:
        ```python
        >>> with label.editor():
        ...    label.name = 'My New Label'
        ...    label.color = 'lagoon-blue'

        >>> label
        Label(name='My New Label', color='lagoon-blue', position=0, ...)
        ``

    Args:
        name (str): Name of the label (optional)
        color (LabelColor): Color of the label (optional)
        position (int): Position of the label (optional)

    Args: Alternate
        label (Label): Label instance to update with

    Returns:
        Label: Updated label instance

    Raises:
        ValueError: If the color is not in the available colors
    """
    overload = parse_overload(
        args, kwargs, 
        model='label', 
        options=('name', 'color', 'position'),
        noarg=self)

    if 'color' in overload and overload['color'] not in self.colors:
        raise ValueError(
            f"Invalid color: {overload['color']}\n"
            f"Valid colors: {self.colors}")

    route = self.routes.patch_label(id=self.id)
    self.__init__(**route(**overload)['item'])
    return self