BoardMembership

Bases: BoardMembership_

Interface for interacting with planka Board Memberships

Note

Only memberships that the current user has manager access to can be seen

Source code in src/plankapy/interfaces.py

class BoardMembership(BoardMembership_):
    """Interface for interacting with planka Board Memberships

    Note:
        Only memberships that the current user has manager access to can be seen
    """
    @property
    def user(self) -> User:
        """User that the membership is associated with

        Returns:
            User: User instance
        """
        user_route = self.routes.get_user(id=self.userId)
        return User(**user_route()['item']).bind(self.routes)

    @property
    def board(self) -> Board:
        """Board that the membership is associated with

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

    @overload
    def update(self): ...

    @overload
    def update(self, boardMembership: BoardMembership): ...

    @overload
    def update(self, role: BoardRole=None, canComment: bool=None): ...

    def update(self, *args, **kwargs) -> BoardMembership:
        """Updates the board membership with new values

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

            Example:
            ```python
            >>> with boardMembership.editor():
            ...    boardMembership.role = 'editor'

            >>> boardMembership
            BoardMembership(userId='...', boardId='...', role='editor', canComment=True)
            ```

        Warning:
            canComment will always be set to True if the role is 'editor', if a context is used as a user is 
            switched to a viewer, they will maintain their ability to comment unless explicitly set to False

            Example:
            ```python
            >>> boardMembership.role
            'editor'

            >>> with boardMembership.editor():
            ...    boardMembership.role = 'viewer'

            >>> boardMembership.canComment
            True

            >>> # Using .update() will not automatically set canComment to False
            >>> # on role change unless specified
            >>> boardMembership.update(role='viewer')
            >>> boardMembership.canComment
            False
            ```

        Args:
            role (BoardRole): Role of the user in the board (default: None)
            canComment (bool): Whether the user can comment on the board (default: None)

        Args: Alternate
            boardMembership (BoardMembership): Board membership instance to update with

        Returns:
            BoardMembership: Updated board membership instance

        Raises:
            ValueError: If the role is invalid (must be 'viewer' or 'editor')

        Note:
            If no arguments are provided, the board membership will update itself with the current values stored in its attributes
        """
        overload = parse_overload(
            args, kwargs, 
            model='boardMembership', 
            options=('role', 'canComment'),
            noarg=self)

        if 'role' in overload:
            if overload['role'] not in self.roles:
                raise ValueError(
                    f'Invalid role: {overload["role"]}'
                    f'Available roles: {self.roles}')

            if overload['role'] == 'editor': # Editors can always comment
                overload['canComment'] = True

            if overload['role'] == 'viewer': # Viewers can only comment if explicitly set
                overload['canComment'] = overload.get('canComment', False)

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

    def delete(self) -> tuple[User, Board]:
        """Deletes the board membership relation

        Danger:
            This action is irreversible and cannot be undone

        Returns:
            User: The user that was removed from the board
        """
        self.refresh()
        route = self.routes.delete_board_membership(id=self.id)
        route()
        return (self.user, self.board)

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

board property

Board that the membership is associated with

Returns:

Name	Type	Description
Board	Board	Board instance

user property

User that the membership is associated with

Returns:

Name	Type	Description
User	User	User instance

delete()

Deletes the board membership relation

Danger

This action is irreversible and cannot be undone

Returns:

Name	Type	Description
User	tuple[User, Board]	The user that was removed from the board

Source code in src/plankapy/interfaces.py

def delete(self) -> tuple[User, Board]:
    """Deletes the board membership relation

    Danger:
        This action is irreversible and cannot be undone

    Returns:
        User: The user that was removed from the board
    """
    self.refresh()
    route = self.routes.delete_board_membership(id=self.id)
    route()
    return (self.user, self.board)

refresh()

Refreshes the board membership data

Source code in src/plankapy/interfaces.py

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

update(*args, **kwargs)

update()

update(boardMembership: BoardMembership)

update(role: BoardRole = None, canComment: bool = None)

Updates the board membership with new values

Tip

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

Example:

>>> with boardMembership.editor():
...    boardMembership.role = 'editor'

>>> boardMembership
BoardMembership(userId='...', boardId='...', role='editor', canComment=True)

Warning

canComment will always be set to True if the role is 'editor', if a context is used as a user is switched to a viewer, they will maintain their ability to comment unless explicitly set to False

Example:

>>> boardMembership.role
'editor'

>>> with boardMembership.editor():
...    boardMembership.role = 'viewer'

>>> boardMembership.canComment
True

>>> # Using .update() will not automatically set canComment to False
>>> # on role change unless specified
>>> boardMembership.update(role='viewer')
>>> boardMembership.canComment
False

Parameters:

Name	Type	Description	Default
role	BoardRole	Role of the user in the board (default: None)	required
canComment	bool	Whether the user can comment on the board (default: None)	required

Alternate

Name	Type	Description	Default
boardMembership	BoardMembership	Board membership instance to update with	required

Returns:

Name	Type	Description
BoardMembership	BoardMembership	Updated board membership instance

Raises:

Type	Description
ValueError	If the role is invalid (must be 'viewer' or 'editor')

Note

If no arguments are provided, the board membership will update itself with the current values stored in its attributes

Source code in src/plankapy/interfaces.py

def update(self, *args, **kwargs) -> BoardMembership:
    """Updates the board membership with new values

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

        Example:
        ```python
        >>> with boardMembership.editor():
        ...    boardMembership.role = 'editor'

        >>> boardMembership
        BoardMembership(userId='...', boardId='...', role='editor', canComment=True)
        ```

    Warning:
        canComment will always be set to True if the role is 'editor', if a context is used as a user is 
        switched to a viewer, they will maintain their ability to comment unless explicitly set to False

        Example:
        ```python
        >>> boardMembership.role
        'editor'

        >>> with boardMembership.editor():
        ...    boardMembership.role = 'viewer'

        >>> boardMembership.canComment
        True

        >>> # Using .update() will not automatically set canComment to False
        >>> # on role change unless specified
        >>> boardMembership.update(role='viewer')
        >>> boardMembership.canComment
        False
        ```

    Args:
        role (BoardRole): Role of the user in the board (default: None)
        canComment (bool): Whether the user can comment on the board (default: None)

    Args: Alternate
        boardMembership (BoardMembership): Board membership instance to update with

    Returns:
        BoardMembership: Updated board membership instance

    Raises:
        ValueError: If the role is invalid (must be 'viewer' or 'editor')

    Note:
        If no arguments are provided, the board membership will update itself with the current values stored in its attributes
    """
    overload = parse_overload(
        args, kwargs, 
        model='boardMembership', 
        options=('role', 'canComment'),
        noarg=self)

    if 'role' in overload:
        if overload['role'] not in self.roles:
            raise ValueError(
                f'Invalid role: {overload["role"]}'
                f'Available roles: {self.roles}')

        if overload['role'] == 'editor': # Editors can always comment
            overload['canComment'] = True

        if overload['role'] == 'viewer': # Viewers can only comment if explicitly set
            overload['canComment'] = overload.get('canComment', False)

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