Base Custom Field Group¶

CLASS	DESCRIPTION
`BaseCustomFieldGroup`	Python interface for Planka BaseCustomFieldGroups

BaseCustomFieldGroup ¶

BaseCustomFieldGroup(schema: Schema, session: Planka)

Bases: PlankaModel[BaseCustomFieldGroup]

Python interface for Planka BaseCustomFieldGroups

Returned by:

Plankapy v2 models

Used by:

Plankapy v2 models Board Board create_field_group

METHOD	DESCRIPTION
`add_field`	Add an existing CustomField to the BaseGroup
`add_fields`	Add a multiple CustomFields to the field group. Useful for copying from one
`copy`	Create a deepcopy of the model and its associated schema.
`create_field`	Create a new CustomField in the BaseCustomFieldGroup
`create_fields`	Create multiple fields in the group (position will be arg order)
`delete`	Delete the BaseCustomFieldGroup
`delete_field`	Delete a CustomField from the Group
`delete_fields`	Delete s sequence of fields from the Group
`diff`	Get a schema diff between two model schemas.
`sync`	Sync the BaseCustomFieldGroup with the Planka server
`update`	Update the BaseCustomFieldGroup

ATTRIBUTE	DESCRIPTION
`__formatter__`	Formatter func that allows overriding str behavior for models TYPE: `ModelFormatter[Self]`
`created_at`	When the base custom field group was created TYPE: `datetime`
`custom_fields`	The CustomFields associated with the BaseCustomFieldGroup TYPE: `list[CustomField]`
`name`	Name/title of the base custom field group TYPE: `str`
`project`	The Project that the BaseCustomFieldGroup is associated with TYPE: `Project`
`updated_at`	When the base custom field group 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

created_at `property` ¶

created_at: datetime

When the base custom field group was created

custom_fields `property` ¶

custom_fields: list[CustomField]

The CustomFields associated with the BaseCustomFieldGroup

name `property` `writable` ¶

name: str

Name/title of the base custom field group

project `property` ¶

project: Project

The Project that the BaseCustomFieldGroup is associated with

updated_at `property` ¶

updated_at: datetime

When the base custom field group was last updated

add_field ¶

add_field(field: CustomField, *, position: Position = 'top', show_on_card: bool | None = None) -> CustomField

Add an existing CustomField to the BaseGroup

PARAMETER	DESCRIPTION
`field` ¶	The existing CustomField to add TYPE: `CustomField`
`position` ¶	The position of the new Field TYPE: `Position` DEFAULT: `'top'`
`show_on_card` ¶	Override the input Field's show state TYPE: `bool \| None` DEFAULT: `None`

Note

If a CustomField with a matching name already exists in the base group, it will be returned

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

def add_field(self, field: CustomField, 
              *, 
              position: Position='top',
              show_on_card: bool|None=None) -> CustomField:
    """Add an existing CustomField to the BaseGroup

    Args:
        field: The existing CustomField to add
        position: The position of the new Field
        show_on_card: Override the input Field's show state

    Note:
        If a CustomField with a matching name already exists in the base group, it 
        will be returned
    """

    if (cf := self.custom_fields[field].dpop()):
        flds = ('name', 'position', 'showOnFrontOfCard')
        cf.update(**{k: field[k] for k in flds if cf[k] != field[k]})
        return cf

    return self.create_field(
        field.name, 
        position=position, 
        show_on_card=show_on_card or field.show_on_front_of_card
    )

add_fields ¶

add_fields(fields: Sequence[CustomField], *, position: Position = 'top', show_on_card: bool | None = None) -> list[CustomField]

Add a multiple CustomFields to the field group. Useful for copying from one Project to another

PARAMETER	DESCRIPTION
`fields` ¶	A sequence of fields to add TYPE: `Sequence[CustomField]`
`position` ¶	Position override for the fields (Will be applied sequence in order) TYPE: `Position` DEFAULT: `'top'`
`show_on_card` ¶	Card display override for fields TYPE: `bool \| None` DEFAULT: `None`

Example

>>> p1_bcfg.add_fields(p2_bcfg.custom_fields)

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

@model_list
def add_fields(self, fields: Sequence[CustomField],
               *,
               position: Position='top',
               show_on_card: bool|None=None) -> list[CustomField]:
    """Add a multiple CustomFields to the field group. Useful for copying from one 
    Project to another

    Args:
        fields: A sequence of fields to add
        position: Position override for the fields (Will be applied sequence in order)
        show_on_card: Card display override for fields

    Example:
        ```python
        >>> p1_bcfg.add_fields(p2_bcfg.custom_fields)
        ```
    """
    return [
        self.add_field(
            field, 
            position=position or field.position, 
            show_on_card=show_on_card
        ) 
        for field in fields
    ]

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)

create_field ¶

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

Create a new CustomField in the BaseCustomFieldGroup

PARAMETER	DESCRIPTION
`name` ¶	Name/title of the custom field TYPE: `str`
`position` ¶	Position of the custom field within the group TYPE: `Position` DEFAULT: `'top'`
`show_on_card` ¶	Whether to show the field on the front of cards TYPE: `bool` DEFAULT: `False`

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

def create_field(self, 
                 name: str, 
                 *,
                 position: Position='top', 
                 show_on_card: bool=False) -> CustomField:
    """Create a new CustomField in the BaseCustomFieldGroup

    Args:
        name: Name/title of the custom field
        position: Position of the custom field within the group
        show_on_card: Whether to show the field on the front of cards 
    """
    return CustomField(
        self.endpoints.createCustomFieldInBaseGroup(
            self.id, 
            name=name,
            position=get_position(self.custom_fields, position),
            showOnFrontOfCard=show_on_card,
            )['item'], 
        self.session
    )

create_fields ¶

create_fields(*names: str, show_on_card: bool = False) -> list[CustomField]

Create multiple fields in the group (position will be arg order)

PARAMETER	DESCRIPTION
`names` ¶	Varargs of the new field names TYPE: `str` DEFAULT: `()`
`show_on_card` ¶	Show the new fields on the front of Cards TYPE: `bool` DEFAULT: `False`

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

@model_list
def create_fields(self, *names: str, show_on_card: bool = False) -> list[CustomField]:
    """Create multiple fields in the group (position will be arg order)

    Args:
        names: Varargs of the new field names
        show_on_card: Show the new fields on the front of Cards
    """
    return [
        self.create_field(name, position='bottom', show_on_card=show_on_card)
        for name in names
    ]

delete ¶

delete()

Delete the BaseCustomFieldGroup

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

def delete(self):
    """Delete the BaseCustomFieldGroup"""
    return self.endpoints.deleteBaseCustomFieldGroup(self.id)

delete_field ¶

delete_field(field: CustomField) -> CustomField | None

Delete a CustomField from the Group

PARAMETER	DESCRIPTION
`field` ¶	The field to delete TYPE: `CustomField`

Note

If the field is not a member of the group, None will be returned

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

def delete_field(self, field: CustomField) -> CustomField | None:
    """Delete a CustomField from the Group

    Args:
        field: The field to delete

    Note:
        If the field is not a member of the group, None will be returned 
    """
    if (f := self.custom_fields[field].dpop()):
        f.delete()
        return f

delete_fields ¶

delete_fields(fields: Sequence[CustomField]) -> list[CustomField]

Delete s sequence of fields from the Group

PARAMETER	DESCRIPTION
`fields` ¶	The fields to delete TYPE: `Sequence[CustomField]`

Note

If the field is not a member of the group, it will not be included in the returned list

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

@model_list
def delete_fields(self, fields: Sequence[CustomField]) -> list[CustomField]:
    """Delete s sequence of fields from the Group

    Args:
        fields: The fields to delete

    Note:
        If the field is not a member of the group, it will not be included in 
        the returned list
    """
    return [removed for field in fields if (removed := self.delete_field(field))]

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
    }

sync ¶

sync()

Sync the BaseCustomFieldGroup with the Planka server

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

def sync(self):
    """Sync the BaseCustomFieldGroup with the Planka server"""
    for bcfg in self.project.base_custom_field_groups:
        if bcfg == self:
            self.schema = bcfg.schema

update ¶

update(**base_custom_field_group: Unpack[Request_updateBaseCustomFieldGroup])

Update the BaseCustomFieldGroup

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

def update(self, **base_custom_field_group: Unpack[paths.Request_updateBaseCustomFieldGroup]):
    """Update the BaseCustomFieldGroup"""
    self.endpoints.updateBaseCustomFieldGroup(self.id, **base_custom_field_group)

Base Custom Field Group¶