Custom Field Group¶

CLASS	DESCRIPTION
`CustomFieldGroup`	Python interface for Planka CustomFieldGroups

CustomFieldGroup ¶

CustomFieldGroup(schema: Schema, session: Planka)

Bases: PlankaModel[CustomFieldGroup]

Python interface for Planka CustomFieldGroups

Returned by:

Plankapy v2
- Planka Utilities PlankaSnapshot custom_field_groups
- models

METHOD	DESCRIPTION
`add_field`	Add a Field to the CustomFieldGroup
`add_fields`	Add fields to the CustomFieldGroup
`add_to_card`	Add the CustomFieldGroup to a Card
`copy`	Create a deepcopy of the model and its associated schema.
`delete`	Delete the CustomFieldGroup
`diff`	Get a schema diff between two model schemas.
`make_base_group`	Convert a CustomFieldGroup into a BaseCustomFieldGroup for a Project or Board
`remove_field`	Remove the field from the CustomFieldGroup
`sync`	Sync the CustomFieldGroup with the Planka server
`update`	Update the CustomFieldGroup

ATTRIBUTE	DESCRIPTION
`__formatter__`	Formatter func that allows overriding str behavior for models TYPE: `ModelFormatter[Self]`
`base_custom_field_group`	The BaseCustomFieldGroup used as a template TYPE: `BaseCustomFieldGroup`
`board`	The Board the CustomFieldGroup belongs to TYPE: `Board`
`card`	The Card the CustomFieldGroup belongs to TYPE: `Card`
`created_at`	When the CustomFieldGroup was created TYPE: `datetime`
`name`	Name/title of the CustomFieldGroup TYPE: `str`
`position`	Position of the CustomFieldGroup within the Board/Card TYPE: `int`
`updated_at`	When the CustomFieldGroup was last updated TYPE: `datetime`

Source code in src/plankapy/v2/models/_base.py

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

base_custom_field_group `property` ¶

base_custom_field_group: BaseCustomFieldGroup

The BaseCustomFieldGroup used as a template

board `property` ¶

board: Board

The Board the CustomFieldGroup belongs to

card `property` ¶

card: Card

The Card the CustomFieldGroup belongs to

created_at `property` ¶

created_at: datetime

When the CustomFieldGroup was created

name `property` `writable` ¶

name: str

Name/title of the CustomFieldGroup

position `property` `writable` ¶

position: int

Position of the CustomFieldGroup within the Board/Card

updated_at `property` ¶

updated_at: datetime

When the CustomFieldGroup was last updated

add_field ¶

add_field(name: str, *, position: Position = 'top', show_on_card: bool = False) -> CustomField

Add a Field to the CustomFieldGroup

PARAMETER	DESCRIPTION
`name` ¶	The name of the Field to add TYPE: `str`
`position` ¶	The position of the field within the group (default: `top`) TYPE: `Position` DEFAULT: `'top'`
`show_on_card` ¶	Show the field on the Card front (default: `False`) TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`CustomField`	If the Field aleady exists, that Field is returned TYPE: `CustomField`

Source code in src/plankapy/v2/models/custom_field_group.py

def add_field(self, name: str,
              *,
              position: Position='top',
              show_on_card: bool=False) -> CustomField:
    """Add a Field to the CustomFieldGroup

    Args:
        name (str): The name of the Field to add
        position (Position): The position of the field within the group (default: `top`)
        show_on_card (bool): Show the field on the Card front (default: `False`)

    Returns:
        CustomField: If the Field aleady exists, that Field is returned
    """
    # Return existing field
    _existing_field = [cf for cf in self.custom_fields if cf.name == name]
    if _existing_field:
        return _existing_field.pop()

    return CustomField(
        self.endpoints.createCustomFieldInGroup(
            self.id,
            name=name,
            position=get_position(self.custom_fields, position),
            showOnFrontOfCard=show_on_card, 
        )['item'], self.session
    )

add_fields ¶

add_fields(*names: str, position: Position = 'top', show_on_card: bool = False) -> list[CustomField]

Add fields to the CustomFieldGroup

PARAMETER	DESCRIPTION
`*names` ¶	Varargs of the names to add TYPE: `str` DEFAULT: `()`
`position` ¶	The position of the field within the group (default: `top`) TYPE: `Position` DEFAULT: `'top'`
`show_on_card` ¶	Show the field on the Card front (default: `False`) TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[CustomField]`	list[CustomField] : The fields added

Note

Field positions will be calculated in the order passed

Source code in src/plankapy/v2/models/custom_field_group.py

def add_fields(self,
               *names: str,
               position: Position='top',
               show_on_card: bool=False) -> list[CustomField]:
    """Add fields to the CustomFieldGroup

    Args:
        *names (str): Varargs of the names to add
        position (Position): The position of the field within the group (default: `top`)
        show_on_card (bool): Show the field on the Card front (default: `False`)

    Returns:
        list[CustomField] : The fields added

    Note:
        Field positions will be calculated in the order passed
    """
    return [
        self.add_field(name=name, position=position, show_on_card=show_on_card)
        for name in names
    ]

add_to_card ¶

add_to_card(card: Card) -> CustomFieldGroup

Add the CustomFieldGroup to a Card

PARAMETER	DESCRIPTION
`card` ¶	The Card to add the CustomFieldGroup to TYPE: `Card`

Source code in src/plankapy/v2/models/custom_field_group.py

def add_to_card(self, card: Card) -> CustomFieldGroup:
    """Add the CustomFieldGroup to a Card

    Args:
        card (Card): The Card to add the CustomFieldGroup to
    """
    # Replace the Current cardId with the ID of the Card we are adding to
    _schema = self.schema.copy()
    _schema['cardId'] = card.id
    return CustomFieldGroup(self.endpoints.createCardCustomFieldGroup(**_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

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 CustomFieldGroup

Source code in src/plankapy/v2/models/custom_field_group.py

def delete(self):
    """Delete the CustomFieldGroup"""
    return self.endpoints.deleteCustomFieldGroup(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

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
    }

make_base_group ¶

make_base_group(project: Project) -> BaseCustomFieldGroup

Convert a CustomFieldGroup into a BaseCustomFieldGroup for a Project or Board

PARAMETER	DESCRIPTION
`project` ¶	The project to add the BaseCustomFieldGroup to TYPE: `Project`

RETURNS	DESCRIPTION
`BaseCustomFieldGroup`	The new BaseCustomFieldGroup TYPE: `BaseCustomFieldGroup`

Source code in src/plankapy/v2/models/custom_field_group.py

def make_base_group(self, project: Project) -> BaseCustomFieldGroup:
    """Convert a CustomFieldGroup into a BaseCustomFieldGroup for a Project or Board

    Args:
        project (Project): The project to add the BaseCustomFieldGroup to

    Returns:
        BaseCustomFieldGroup: The new BaseCustomFieldGroup
    """
    return BaseCustomFieldGroup(self.endpoints.createBaseCustomFieldGroup(project.id, name=self.name)['item'], self.session)

remove_field ¶

remove_field(field: CustomField) -> None

Remove the field from the CustomFieldGroup

PARAMETER	DESCRIPTION
`field` ¶	The CustomField to remove (must be in this Group) TYPE: `CustomField`

Source code in src/plankapy/v2/models/custom_field_group.py

def remove_field(self, field: CustomField) -> None:
    """Remove the field from the CustomFieldGroup

    Args:
        field (CustomField): The CustomField to remove (must be in this Group)
    """
    if field in self.custom_fields:
        field.delete()

sync ¶

sync()

Sync the CustomFieldGroup with the Planka server

Source code in src/plankapy/v2/models/custom_field_group.py

def sync(self):
    """Sync the CustomFieldGroup with the Planka server"""
    self.schema = self.endpoints.getCustomFieldGroup(self.id)['item']

update ¶

update(**kwargs: Unpack[Request_updateCustomFieldGroup])

Update the CustomFieldGroup

Source code in src/plankapy/v2/models/custom_field_group.py

def update(self, **kwargs: Unpack[paths.Request_updateCustomFieldGroup]):
    """Update the CustomFieldGroup"""
    self.schema = self.endpoints.updateCustomFieldGroup(self.id, **kwargs)['item']

Custom Field Group¶