Planka Utilities

Utility functions for dealing with Planka objects

CLASS	DESCRIPTION
PlankaSnapshot

FUNCTION	DESCRIPTION
due_in	Decorated function for use with a ModelList
board_to_csv	Write the current board state out to a csv file
board_to_table	Get a nested list/table for the board.
snapshot	Create a dictionary snapshot of a Planka object. (MUST BE ADMIN)

PlankaSnapshot

Bases: TypedDict

Returned by:

• Plankapy v2 Planka Utilities  snapshot

ATTRIBUTE	DESCRIPTION
projects	Project Schemas TYPE: list[Project]
boards	Board Schemas TYPE: list[Board]
lists	List Schemas TYPE: list[List]
cards	Card Schemas TYPE: list[Card]
card_labels	Card Label Schemas TYPE: list[CardLabel]
card_memberships	Card Membership Schemas TYPE: list[CardMembership]
task_lists	Task List Schemas TYPE: list[TaskList]
tasks	Task Schemas TYPE: list[Task]
base_custom_field_groups	Base Custom Field Group schemas TYPE: list[BaseCustomFieldGroup]
custom_field_groups	Custom Field Group Schemas TYPE: list[CustomFieldGroup]
custom_fields	Custom Field Schemas TYPE: list[CustomField]
custom_field_values	Custom Field Value Schemas TYPE: list[CustomFieldValue]
comments	Comment Schemas TYPE: list[Comment]
webhooks	Webhook Schemas TYPE: list[Webhook]
users	User Schemas TYPE: list[User]
board_memberships	Board Membership Schemas TYPE: list[BoardMembership]
project_managers	Project Manager Schemas TYPE: list[ProjectManager]
labels	Label Schemas TYPE: list[Label]
notification_services	Notificaiton Service Schemas TYPE: list[NotificationService]
actions	Action Schemas TYPE: list[Action]
config	Config Schema TYPE: Config

projects instance-attribute

projects: list[Project]

Project Schemas

boards instance-attribute

boards: list[Board]

Board Schemas

lists instance-attribute

lists: list[List]

List Schemas

cards instance-attribute

cards: list[Card]

Card Schemas

card_labels instance-attribute

card_labels: list[CardLabel]

Card Label Schemas

card_memberships instance-attribute

card_memberships: list[CardMembership]

Card Membership Schemas

task_lists instance-attribute

task_lists: list[TaskList]

Task List Schemas

tasks instance-attribute

tasks: list[Task]

Task Schemas

base_custom_field_groups instance-attribute

base_custom_field_groups: list[BaseCustomFieldGroup]

Base Custom Field Group schemas

custom_field_groups instance-attribute

custom_field_groups: list[CustomFieldGroup]

Custom Field Group Schemas

custom_fields instance-attribute

custom_fields: list[CustomField]

Custom Field Schemas

custom_field_values instance-attribute

custom_field_values: list[CustomFieldValue]

Custom Field Value Schemas

comments instance-attribute

comments: list[Comment]

Comment Schemas

webhooks instance-attribute

webhooks: list[Webhook]

Webhook Schemas

users instance-attribute

users: list[User]

User Schemas

board_memberships instance-attribute

board_memberships: list[BoardMembership]

Board Membership Schemas

project_managers instance-attribute

project_managers: list[ProjectManager]

Project Manager Schemas

labels instance-attribute

labels: list[Label]

Label Schemas

notification_services instance-attribute

notification_services: list[NotificationService]

Notificaiton Service Schemas

actions instance-attribute

actions: list[Action]

Action Schemas

config instance-attribute

config: Config

Config Schema

due_in

due_in(hours: float = 0, days: float = 0, weeks: float = 0)

Decorated function for use with a ModelList That allows filtering by date

Source code in src/plankapy/v2/utils.py

def due_in(hours: float=0, days: float=0, weeks: float=0):
    """Decorated function for use with a [ModelList](plankapy.v2.models._helpers.ModelList)
    That allows filtering by date
    """
    def _inner(m: HasDueDate):
        if not m.due_date:
            return False
        by = timedelta(days=days, hours=hours, weeks=weeks)
        return (m.due_date - by) <= datetime.now(tz=timezone.utc)
    return _inner

board_to_csv

board_to_csv(board: Board, outdir: str | Path = '.', name: str | None = None)

Write the current board state out to a csv file

Writes out a csv of the board state using list.name and card.name as the headers and values respectively. Will match visual state of the board.

PARAMETER	DESCRIPTION
board	The board to export TYPE: Board
outdir	A string or Path to the outpud directory (default: cwd) TYPE: str | Path DEFAULT: '.'
name	An optional overrde for the filename (default: board.name) TYPE: str | None DEFAULT: None

Source code in src/plankapy/v2/utils.py

def board_to_csv(board: Board, outdir: str|Path='.', name: str|None=None):
    """Write the current board state out to a csv file

    Writes out a csv of the board state using `list.name` and `card.name` as 
    the headers and values respectively. Will match visual state of the board.

    Args:
        board: The board to export
        outdir: A string or Path to the outpud directory (default: `cwd`)
        name: An optional overrde for the filename (default: `board.name`)
    """
    outfile = Path(outdir) / f'{name or board.name}.csv'
    rows = board_to_table(board)
    with outfile.open('wt') as csv:
        csv.writelines(','.join(row)+'\n' for row in rows)

board_to_table

board_to_table(board: Board) -> list[list[str]]

Get a nested list/table for the board. Uses name attributes of cards and lists

PARAMETER	DESCRIPTION
board	The board object to tablify TYPE: Board

RETURNS	DESCRIPTION
list[list[str]]	A matrix of string lists with the first element being list names
list[list[str]]	and the remaining elements being card names from left to right
list[list[str]]	```
list[list[str]]	[ ['list1', 'list2'], ['l1 c1', 'l2 c1'], ['l1 c2', 'l2 c2'], ...
list[list[str]]	]
list[list[str]]	```

Source code in src/plankapy/v2/utils.py

def board_to_table(board: Board) -> list[list[str]]:
    """Get a nested list/table for the board. 
    Uses `name` attributes of cards and lists

    Args:
        board: The board object to tablify

    Returns:
        A matrix of string lists with the first element being list names 
        and the remaining elements being card names from left to right    
        ```
        [
            ['list1', 'list2'],
            ['l1 c1', 'l2 c1'],
            ['l1 c2', 'l2 c2'],
            ...
        ]
        ```
    """
    headers: list[str] = board.lists.extract('name')
    list_cards: list[list[str]] = [
        lst.cards.extract('name')
        for lst in board.lists
    ]
    rows = zip_longest(*list_cards, fillvalue='')
    return [headers]+[list(row) for row in rows]

snapshot

snapshot(planka: Planka) -> PlankaSnapshot

Create a dictionary snapshot of a Planka object. (MUST BE ADMIN) All associated schemas are dumped into a single dictionary.

Note

Since this required traversing all objecs in the system, it can be a very long process. This is best run at a time when not a lot of users are interacting with the board since a 5 minute snapshot could end up with sync errors if state changes over that time.

RETURNS	DESCRIPTION
PlankaSnapshot	A dictonary with all object schemas. Each top level key is a

RAISES	DESCRIPTION
PermissionError	If the logged in user is not an admin

Source code in src/plankapy/v2/utils.py

def snapshot(planka: Planka) -> PlankaSnapshot:
    """Create a dictionary snapshot of a Planka object. (MUST BE ADMIN)
    All associated schemas are dumped into a single dictionary. 

    Note:
        Since this required traversing all objecs in the system, it can be a very long process. 
        This is best run at a time when not a lot of users are interacting with the board since 
        a 5 minute snapshot could end up with sync errors if state changes over that time.

    Returns:
        A dictonary with all object schemas. Each top level key is a 

    Raises:
        PermissionError: If the logged in user is not an admin
    """
    if not planka.me.role == 'admin':
        raise PermissionError('Planka Snapshots can only be done by Admin users!')
    projects = planka.projects
    boards = [b for p in projects for b in p.boards]
    cards = [c for b in boards for c in b.cards]
    lists = [l for b in boards for l in b.lists]
    card_labels = [cl for b in boards for cl in b.card_labels]
    card_memberships = [cm for b in boards for cm in b.card_memberships]
    task_lists = [tl for b in boards for tl in b.task_lists]
    tasks = [t for b in boards for t in b.tasks]
    base_custom_field_groups = [bcfg for p in projects for bcfg in p.base_custom_field_groups]
    custom_field_groups = [cfg for b in boards for cfg in b.custom_field_groups]
    custom_fields = [cf for b in boards for cf in b.custom_fields]
    custom_field_values = [cfv for b in boards for cfv in b.custom_field_values]
    comments = [cm for c in cards for cm in c.comments]
    webhooks = planka.webhooks
    users = planka.users
    board_memberships = [bm for b in boards for bm in b.board_memberships]
    project_managers = [pm for p in projects for pm in p.project_managers]
    labels = [l for b in boards for l in b.labels]
    notification_services = [ns for p in projects for ns in p.notification_services]
    actions = [a for c in cards for a in c.actions]
    config = planka.config

    snap: PlankaSnapshot = {
        'projects': _get_schema(projects),
        'boards': _get_schema(boards),
        'lists': _get_schema(lists),
        'cards': _get_schema(cards),
        'card_labels': _get_schema(card_labels),
        'card_memberships': _get_schema(card_memberships),
        'task_lists': _get_schema(task_lists),
        'tasks': _get_schema(tasks),
        'base_custom_field_groups': _get_schema(base_custom_field_groups),
        'custom_field_groups': _get_schema(custom_field_groups),
        'custom_fields': _get_schema(custom_fields),
        'custom_field_values': _get_schema(custom_field_values),
        'comments': _get_schema(comments),
        'webhooks': _get_schema(webhooks),
        'users': _get_schema(users),
        'board_memberships': _get_schema(board_memberships),
        'project_managers': _get_schema(project_managers),
        'labels': _get_schema(labels),
        'notification_services': _get_schema(notification_services),
        'actions': _get_schema(actions),
        'config': config.schema
    }
    return snap