Board

Bases: Board_

Interface for interacting with planka Boards and their included sub-objects

Note

All implemented public properties return API responses with accessed. This means that the values are not cached and will be updated on every access. If you wish to cache values, you are responsible for doing so. By default, property access will always provide the most up to date information.

METHOD	DESCRIPTION
__eq__	Check if two model instances are equal
__getitem__	Get the value of an attribute
__hash__	Generate a hash for the model instance so it can be used in mappings (dict, set)
__iter__	Iterate over public, assigned model attribute names
add_user	Adds a user to the board
bind	Bind routes to the model
create_label	Creates a new label in the board
create_list	Creates a new list in the board
delete	Deletes the board
editor	Context manager for editing the model
json	Dump the model properties to a JSON string
pickle	Pickle the model, preserving as much of its state as possible
refresh	Refreshes the board data
remove_user	Remove a user from a board
update	Updates the board with new values

ATTRIBUTE	DESCRIPTION
attachments	All attachments in the board TYPE: QueryableList[Attachment]
boardMemberships	All board memberships TYPE: QueryableList[BoardMembership]
cardLabels	All card -> label relationships in the board TYPE: QueryableList[CardLabel]
cardMemberships	All card -> user relationships in the board TYPE: QueryableList[CardMembership]
cards	All cards in the board TYPE: QueryableList[Card]
created_at	Get the creation date of the model instance TYPE: datetime | None
deleted_at	Get the deletion date of the model instance TYPE: datetime | None
editors	All users that can edit the board TYPE: QueryableList[User]
labels	All labels in the board TYPE: QueryableList[Label]
link	Get the link to the model instance TYPE: str | None
lists	All lists in the board TYPE: QueryableList[List]
project	Project the board belongs to TYPE: Project
routes	Get the routes for the model instance TYPE: Routes
tasks	All tasks in the board TYPE: QueryableList[Task]
unique_name	Generate a unique name for the model instance using the last 5 characters of the id TYPE: str
updated_at	Get the last update date of the model instance TYPE: datetime | None
users	All users in the board TYPE: QueryableList[User]
viewers	All users that can view the board TYPE: QueryableList[User]

attachments property

attachments: QueryableList[Attachment]

All attachments in the board

Note

This property is used by the Card class to determine its attachments

RETURNS	DESCRIPTION
QueryableList[Attachment]	A list of all card attachments in the board

boardMemberships property

boardMemberships: QueryableList[BoardMembership]

All board memberships

Note

This property is primarily here for internal use, '.editor' and '.viewer' properties are derived from the board memberships

RETURNS	DESCRIPTION
QueryableList[BoardMembership]	Queryable List of all membership types (editor, viewer)

cardLabels property

cardLabels: QueryableList[CardLabel]

All card -> label relationships in the board

Note

This property is used by the Card class to determine its labels

RETURNS	DESCRIPTION
QueryableList[CardLabel]	A list of all card labels in the board

cardMemberships property

cardMemberships: QueryableList[CardMembership]

All card -> user relationships in the board

Note

This property is used by the Card class to determine its users

RETURNS	DESCRIPTION
QueryableList[CardMembership]	A list of all card memberships in the board

cards property

cards: QueryableList[Card]

All cards in the board

RETURNS	DESCRIPTION
QueryableList[Card]	A list of all cards in the board

created_at property

created_at: datetime | None

Get the creation date of the model instance

RETURNS	DESCRIPTION
datetime | None	Optional[datetime]: The creation date of the model instance

deleted_at property

deleted_at: datetime | None

Get the deletion date of the model instance

RETURNS	DESCRIPTION
datetime | None	Optional[datetime]: The deletion date of the model instance

editors property

editors: QueryableList[User]

All users that can edit the board

RETURNS	DESCRIPTION
QueryableList[User]	Queryable List of all editors

labels property

labels: QueryableList[Label]

All labels in the board

RETURNS	DESCRIPTION
QueryableList[Label]	Queryable List of all labels in the board

link property

link: str | None

Get the link to the model instance

Note

Only Project, Board, and Card models have links.

All other models return None

RETURNS	DESCRIPTION
str	The link to the model instance TYPE: str | None

lists property

lists: QueryableList[List]

All lists in the board

RETURNS	DESCRIPTION
QueryableList[List]	Queryable List of all lists in the board

project property

project: Project

Project the board belongs to

Note

All objects include a reference to their parent object and parent objects include a reference to their children This means that you can traverse the entire API structure from any object

RETURNS	DESCRIPTION
Project	Project instance TYPE: Project

routes property writable

routes: Routes

Get the routes for the model instance

RETURNS	DESCRIPTION
Routes	The routes bound to the model instance TYPE: Routes

tasks property

tasks: QueryableList[Task]

All tasks in the board

Note

This property is used by the Card class to determine its tasks

RETURNS	DESCRIPTION
QueryableList[Task]	A list of all card tasks in the board

unique_name property

unique_name: str

Generate a unique name for the model instance using the last 5 characters of the id and the name attribute

RETURNS	DESCRIPTION
str	The unique name for the model instance in the format {name}_{id[:-5]} TYPE: str

updated_at property

updated_at: datetime | None

Get the last update date of the model instance

RETURNS	DESCRIPTION
datetime | None	Optional[datetime]: The last update date of the model instance

users property

users: QueryableList[User]

All users in the board

RETURNS	DESCRIPTION
QueryableList[User]	Queryable List of all users

viewers property

viewers: QueryableList[User]

All users that can view the board

RETURNS	DESCRIPTION
QueryableList[User]	Queryable List of all viewers

__eq__

__eq__(other: Model) -> bool

Check if two model instances are equal

Note

Compares the hash and class of the model instances

Warning

Does not compare the attributes of the model instances, out of sync models with different attributes can still be equal, it's best to refresh the models before comparing.

PARAMETER	DESCRIPTION
other	The other model instance to compare TYPE: Model

RETURNS	DESCRIPTION
bool	True if the model instances are equal, False otherwise TYPE: bool

Source code in src/plankapy/v1/models.py

def __eq__(self, other: Model) -> bool:
    """Check if two model instances are equal

    Note:
        Compares the hash and class of the model instances

    Warning:
        Does not compare the attributes of the model instances, out of sync models
        with different attributes can still be equal, it's best to refresh the models
        before comparing.

    Args:
        other (Model): The other model instance to compare

    Returns:
        bool: True if the model instances are equal, False otherwise
    """
    return isinstance(other, self.__class__) and hash(self) == hash(other)

__getitem__

__getitem__(key) -> Any

Get the value of an attribute

Warning

This is an implementation detail that allows for the unpacking operations in the rest of the codebase, all model attributes are still directly accessible through __getattribute___

Note

Returns None if the attribute is Unset or starts with an underscore

Example

print(model['name'])
>>> "Model Name"

model.name = Unset
print(model['name'])
>>> None

Source code in src/plankapy/v1/models.py

def __getitem__(self, key) -> Any:
    """Get the value of an attribute

    Warning:
        This is an implementation detail that allows for the unpacking operations
        in the rest of the codebase, all model attributes are still directly accessible
        through `__getattribute___`

    Note:
        Returns None if the attribute is `Unset` or starts with an underscore

    Example:
        ```python
        print(model['name'])
        >>> "Model Name"

        model.name = Unset
        print(model['name'])
        >>> None
        ```
    """
    val = self.__dict__[key]
    return val if val is not Unset else None

__hash__

__hash__() -> int

Generate a hash for the model instance so it can be used in mappings (dict, set)

Note

All Models are still mutable, but their ID value is unique

RETURNS	DESCRIPTION
int	The hash value of the model instance TYPE: int

Example

board_map = {
    Board(name="Board 1"): board.,
    Board(name="Board 2"): "Board 2"
}
>>> 1

Source code in src/plankapy/v1/models.py

def __hash__(self) -> int:
    """Generate a hash for the model instance so it can be used in mappings (`dict`, `set`)

    Note:
        All Models are still mutable, but their ID value is unique

    Returns:
        int: The hash value of the model instance

    Example:
        ```python
        board_map = {
            Board(name="Board 1"): board.,
            Board(name="Board 2"): "Board 2"
        }
        >>> 1
        ```
    """
    if hasattr(self, 'id'):
        return int(self.id)

    # Default hash if no id (string of name and attributes)
    return hash(f"{self.__class__.__name__}{self.__dict__}")

__iter__

__iter__()

Iterate over public, assigned model attribute names

Warning

This is used in conjunction with __getitem__ to unpack assigned values. This allows model state to be passed as keyword arguments to functions

Example:

model = Model(name="Model Name", position=1, other=Unset)

def func(name=None, position=None):
    return {"name": name, "position": position}

print(func(**model))
>>> {'name': 'Model Name', 'position': 1}

Notice how only the assigned values are returned after unpacking and any Unset or private attributes are skipped, This allows None values to be assigned during a PATCH request to delete data

Note

Skips attributes that are Unset or start with an underscore

RETURNS	DESCRIPTION
Iterator	The iterator of the model attributes

Example

# Skip Private attributes
print(list(model.__dict__))
>>> ['_privateattribute', 'name', 'position', 'id']

print(list(model))
>>> ['name', 'position', 'id'] # Skips _privateattribute

# Skip Unset attributes
print(model.___dict___)
>>> {'_privateattribute': 'Private', 'name': 'Model Name', 'position': Unset, 'id': 1}

items = dict(model.items())
print(items)
>>> {'name': 'Model Name', 'id': 1} # Skips position because it's Unset

Source code in src/plankapy/v1/models.py

def __iter__(self):
    """Iterate over public, assigned model attribute names

    Warning:
        This is used in conjunction with `__getitem__` to unpack assigned values. 
        This allows model state to be passed as keyword arguments to functions

        Example:
            ```python
            model = Model(name="Model Name", position=1, other=Unset)

            def func(name=None, position=None):
                return {"name": name, "position": position}

            print(func(**model))
            >>> {'name': 'Model Name', 'position': 1}
            ```
        Notice how only the assigned values are returned after unpacking and any Unset or 
        private attributes are skipped, This allows `None` values to be assigned during
        a `PATCH` request to delete data 

    Note:
        Skips attributes that are `Unset` or start with an underscore

    Returns:
        Iterator: The iterator of the model attributes

    Example:
        ```python

        # Skip Private attributes
        print(list(model.__dict__))
        >>> ['_privateattribute', 'name', 'position', 'id']

        print(list(model))
        >>> ['name', 'position', 'id'] # Skips _privateattribute

        # Skip Unset attributes
        print(model.___dict___)
        >>> {'_privateattribute': 'Private', 'name': 'Model Name', 'position': Unset, 'id': 1}

        items = dict(model.items())
        print(items)
        >>> {'name': 'Model Name', 'id': 1} # Skips position because it's Unset
        ```
    """
    return iter(
        k for k, v in self.__dict__.items() 
        if v is not Unset 
        and not k.startswith("_")
    )

add_user

add_user(user: User, role: BoardRole = 'viewer', canComment: bool = False) -> BoardMembership

Adds a user to the board

PARAMETER	DESCRIPTION
user	User instance to add TYPE: User
canComment	Whether the user can comment on the board (default: False) TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
BoardMembership	New board membership TYPE: BoardMembership

RAISES	DESCRIPTION
ValueError	If the role is invalid (must be 'viewer' or 'editor')

Source code in src/plankapy/v1/interfaces.py

def add_user(self, user: User, role: BoardRole='viewer', canComment: bool=False) -> BoardMembership:
    """Adds a user to the board

    Args:
        user (User): User instance to add
        canComment (bool): Whether the user can comment on the board (default: False)

    Returns:
        BoardMembership: New board membership

    Raises:
        ValueError: If the role is invalid (must be 'viewer' or 'editor')
    """
    if role not in self.roles:
        raise ValueError(f'Invalid role: {role}')

    if role == 'editor':
        canComment = True
    route = self.routes.post_board_membership(boardId=self.id)
    return BoardMembership(**route(userId=user.id, boardId=self.id, canComment=canComment, role=role)['item']).bind(self.routes)

bind

bind(routes: Routes) -> Self

Bind routes to the model Args: routes (Routes): The routes to bind to the model instance

RETURNS	DESCRIPTION
Self	Self for chain operations

Example

model = Model(**kwargs).bind(routes)

Source code in src/plankapy/v1/models.py

def bind(self, routes: Routes) -> Self:
    """Bind routes to the model
    Args:
        routes (Routes): The routes to bind to the model instance

    Returns:
        Self for chain operations

    Example:
        ```python
        model = Model(**kwargs).bind(routes)
        ```
    """
    self.routes = routes
    return self

create_label

create_label(label: Label) -> Label

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

create_label(*args, **kwargs) -> Label

Creates a new label in the board

PARAMETER	DESCRIPTION
name	Name of the label (required) TYPE: str
position	Position of the label (default: 0) TYPE: int
color	Color of the label (default: "berry-red") TYPE: LabelColor

ALTERNATE	DESCRIPTION
label	Label instance to create TYPE: Label

RETURNS	DESCRIPTION
Label	New label instance TYPE: Label

Example

>>> new_label = board.create_label('My Label')
>>> label = Label(name='My Label', position=0, color='wet-moss')
>>> new_label2 = board.create_label(label)

Source code in src/plankapy/v1/interfaces.py

def create_label(self, *args, **kwargs) -> Label:
    """Creates a new label in the board

    Args:
        name (str): Name of the label (required)
        position (int): Position of the label (default: 0)
        color (LabelColor): Color of the label (default: "berry-red")

    Args: Alternate
        label (Label): Label instance to create

    Returns:
        Label: New label instance

    Example:
        ```python
        >>> new_label = board.create_label('My Label')
        >>> label = Label(name='My Label', position=0, color='wet-moss')
        >>> new_label2 = board.create_label(label)
        ```
    """
    overload = parse_overload(args, kwargs, model='label', 
                              options=('name', 'position', 'color'), 
                              required=('name',)) # Only name requires user provided value

    # Required arguments with defaults must be manually assigned
    overload['position'] = overload.get('position', 0)
    overload['color'] = overload.get('color', choice(LabelColor.__args__))
    overload['boardId'] = self.id

    route = self.routes.post_label(boardId=self.id)
    return Label(**route(**overload)['item']).bind(self.routes)

create_list

create_list(_list: List) -> List

create_list(name: str, position: int) -> List

create_list(*args, **kwargs) -> List

Creates a new list in the board

PARAMETER	DESCRIPTION
name	Name of the list (required) TYPE: str
position	Position of the list (default: 0) TYPE: int

ALTERNATE	DESCRIPTION
list	List instance to create TYPE: List

RETURNS	DESCRIPTION
List	New list instance TYPE: List

Example

>>> new_list = board.create_list('My List')

>>> l = List(name='My List', position=0)
>>> new_list2 = board.create_list(l)

Source code in src/plankapy/v1/interfaces.py

def create_list(self, *args, **kwargs) -> List:
    """Creates a new list in the board

    Args:
        name (str): Name of the list (required)
        position (int): Position of the list (default: 0)

    Args: Alternate
        list (List): List instance to create

    Returns:
        List: New list instance

    Example:
        ```python
        >>> new_list = board.create_list('My List')

        >>> l = List(name='My List', position=0)
        >>> new_list2 = board.create_list(l)
        ```
    """
    overload = parse_overload(args, kwargs, model='list', 
                              options=('name', 'position'), 
                              required=('name',))

    overload['position'] = overload.get('position', 0)
    overload['boardId'] = self.id

    route = self.routes.post_list(boardId=self.id)
    return List(**route(**overload)['item']).bind(self.routes)

delete

delete() -> Board

Deletes the board

Danger

This action is irreversible and cannot be undone

RETURNS	DESCRIPTION
Board	Deleted board instance TYPE: Board

Source code in src/plankapy/v1/interfaces.py

def delete(self) -> Board:
    """Deletes the board

    Danger:
        This action is irreversible and cannot be undone

    Returns:
        Board: Deleted board instance
    """
    self.refresh()
    route = self.routes.delete_board(id=self.id)
    route()
    return self

editor

editor() -> Generator[Self, None, None]

Context manager for editing the model

Example

print(model.name)
>>> "Old Name"
with model.editor() as m:
    m.name = "New Name"
    m.position = 1

print(model.name)
>>> "New Name"

Source code in src/plankapy/v1/models.py

@contextmanager
def editor(self) -> Generator[Self, None, None]:
    """Context manager for editing the model

    Example:
        ```python
        print(model.name)
        >>> "Old Name"
        with model.editor() as m:
            m.name = "New Name"
            m.position = 1

        print(model.name)
        >>> "New Name"
        ```

    """
    try:
        self.refresh()
        _self = self.__dict__.copy() # Backup the model state
        yield self
    except Exception as e:
        self.__dict__ = _self # Restore the model state
        raise e
    finally:
        self.update()

json

json() -> str

Dump the model properties to a JSON string

Note

Only properties defined in the {Model}_ dataclass are dumped. All relationships and included items (e.g. board.cards) are lost. If you wish to preserve these relationships, use the .pickle method

RETURNS	DESCRIPTION
str	(str) : A JSON string with the Model attributes

Source code in src/plankapy/v1/models.py

def json(self) -> str:
    """Dump the model properties to a JSON string

    Note:
        Only properties defined in the `{Model}_` dataclass are dumped. 
        All relationships and included items (e.g. `board.cards`) are lost.
        If you wish to preserve these relationships, use the `.pickle` method

    Returns:
        (str) : A JSON string with the Model attributes
    """
    return json.dumps({k: self[k] for k in self})

pickle

pickle() -> bytes

Pickle the model, preserving as much of its state as possible

Warning

This method currently works, and since the object data is updated by routes You can use this to store a reference to a specific object. The data will be maintained until operations that trigger a .refresh() call are made, e.g. using the .editor() context.

RETURNS	DESCRIPTION
bytes	(bytes) : Raw bytes generated by pickle.dump

Source code in src/plankapy/v1/models.py

def pickle(self) -> bytes:
    """Pickle the model, preserving as much of its state as possible

    Warning:
        This method currently works, and since the object data is updated by routes
        You can use this to store a reference to a specific object. The data will be
        maintained until operations that trigger a `.refresh()` call are made, e.g. 
        using the `.editor()` context.

    Returns:
        (bytes) : Raw bytes generated by `pickle.dump`
    """
    out = io.BufferedWriter(raw=io.BytesIO())
    pickle.dump(self, out)
    return out.raw.read()

refresh

refresh() -> None

Refreshes the board data

Source code in src/plankapy/v1/interfaces.py

def refresh(self) -> None:
    """Refreshes the board data"""
    route = self.routes.get_board(id=self.id)
    self.__init__(**route()['item'])

remove_user

remove_user(user: User) -> User

remove_user(userId: int) -> User

remove_user(*args, **kwargs) -> User

Remove a user from a board

Source code in src/plankapy/v1/interfaces.py

def remove_user(self, *args, **kwargs) -> User:
    """Remove a user from a board
    """
    overload = parse_overload(args, kwargs,
                              model='user',
                              options=('userId',),
                              required=('userId',))

    if 'userId' not in overload: # Case if passed User
        overload['userId'] = overload['id']

    for member in self.boardMemberships:
        if member.userId == overload['userId']:
            member.delete()

update

update() -> Board

update(board: Board) -> Board

update(name: str = None, position: int = None) -> Board

update(*args, **kwargs) -> Board

Updates the board with new values

PARAMETER	DESCRIPTION
name	Name of the board (optional) TYPE: str
position	Position of the board (optional) TYPE: int

ALTERNATE	DESCRIPTION
board	Board instance to update (required) TYPE: Board

Note

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

RETURNS	DESCRIPTION
Board	Updated board instance TYPE: Board

Source code in src/plankapy/v1/interfaces.py

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

    Args:
        name (str): Name of the board (optional)
        position (int): Position of the board (optional)

    Args: Alternate
        board (Board): Board instance to update (required)

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

    Returns:
        Board: Updated board instance
    """
    overload = parse_overload(
        args, kwargs, 
        model='board', 
        options=('name', 'position'),
        noarg=self)

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