Project

Bases: Project_

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

ATTRIBUTE	DESCRIPTION
gradients	All available gradients TYPE: list[Gradient]
gradient_to_css	Mapping of gradient names to CSS values TYPE: dict[Gradient, str]

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_project_manager	Creates a new project manager in the project
bind	Bind routes to the model
create_board	Creates a new board in the project from a name and position or a Board instance
delete	Deletes the project
download_background_image	Download a background image from the project
editor	Context manager for editing the model
gradient_css	Get the CSS value for the project gradient
json	Dump the model properties to a JSON string
pickle	Pickle the model, preserving as much of its state as possible
refresh	Refreshes the project data
remove_background_image	Remove the background image from the project
set_background_gradient	Set a background gradient for the project
set_background_image	Add a background image to the project
update	Updates the project with new values

boardMemberships property

boardMemberships: QueryableList[BoardMembership]

All board memberships and roles in the project

Note

This property is not a list of users, but a list of BoardMembership objects that define the user's role in the project boards. This is used to remove memberships in associated project boards and will likely never be used directly

RETURNS	DESCRIPTION
QueryableList[BoardMembership]	Queryable List of all board membership relations in the project

boards property

boards: QueryableList[Board]

All boards in the project

RETURNS	DESCRIPTION
QueryableList[Board]	Queryable List of all boards

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

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

managers property

managers: QueryableList[User]

All project managers (Users)

RETURNS	DESCRIPTION
QueryableList[User]	Queryable List of all project managers

projectManagers property

projectManagers: QueryableList[ProjectManager]

All project managers (ProjectManager Relations)

Note

This property is not a list of users, but a list of ProjectManager objects that define the user's role in the project. This is used to remove managers in associated project boards and will likely never be used directly

RETURNS	DESCRIPTION
QueryableList[ProjectManager]	Queryable List of all project manager relations

routes property writable

routes: Routes

Get the routes for the model instance

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

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 project

RETURNS	DESCRIPTION
QueryableList[User]	Queryable List of all users

__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_project_manager

add_project_manager(user: User) -> ProjectManager

add_project_manager(userId: int) -> ProjectManager

add_project_manager(*args, **kwargs) -> ProjectManager

Creates a new project manager in the project

Note

This method has overloaded arguments, You can pass a User instance or provide a required userId argument

PARAMETER	DESCRIPTION
userId	id of the user to make project manager (required) TYPE: int

ALTERNATE	DESCRIPTION
user	User instance to create (required) TYPE: User

RETURNS	DESCRIPTION
ProjectManager	New project manager instance TYPE: ProjectManager

Example

>>> new_manager = project.create_project_manager(planka.me)
>>> other_manager = project.create_project_manager(userId='...1234')

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

def add_project_manager(self, *args, **kwargs) -> ProjectManager:
    """Creates a new project manager in the project

    Note:
        This method has overloaded arguments,
        You can pass a `User` instance or provide a required `userId` argument

    Args:
        userId (int): id of the user to make project manager (required)

    Args: Alternate    
        user (User): User instance to create (required)

    Returns:
        ProjectManager: New project manager instance

    Example:
        ```python
        >>> new_manager = project.create_project_manager(planka.me)
        >>> other_manager = project.create_project_manager(userId='...1234')
        ```

    """
    overload = parse_overload(
        args, kwargs, 
        model='user', 
        options=('userId',), 
        required=('userId',))

    userId = overload.get('userId', None)

    if not userId: # Get id from passed User
        userId = overload.get('id')

    # Don't assign a manager twice (raises HTTP 409 - Conflict)
    if userId in [manager.id for manager in self.managers]:
        return

    route = self.routes.post_project_manager(projectId=self.id)
    return ProjectManager(**route(userId=userId, projectId=self.id)['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_board

create_board(board: Board) -> Board

create_board(name: str, position: int = 0) -> Board

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

Creates a new board in the project from a name and position or a Board instance

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

ALTERNATE	DESCRIPTION
board	Board instance to create TYPE: Board

RETURNS	DESCRIPTION
Board	New board instance TYPE: Board

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

def create_board(self, *args, **kwargs) -> Board:
    """Creates a new board in the project from a name and position or a Board instance

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

    Args: Alternate
        board (Board): Board instance to create

    Returns:
        Board: New board instance
    """
    overload = parse_overload(
        args, kwargs, 
        model='board', 
        options=('name', 'position'), 
        required=('name',))

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

    route = self.routes.post_board(projectId=self.id)
    return Board(**route(**overload)['item']).bind(self.routes)

delete

delete() -> Project

Deletes the project

Danger

This action is irreversible and cannot be undone

RETURNS	DESCRIPTION
Project	Deleted project instance TYPE: Project

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

def delete(self) -> Project:
    """Deletes the project

    Danger:
        This action is irreversible and cannot be undone

    Returns:
        Project: Deleted project instance
    """
    self.refresh()
    route = self.routes.delete_project(id=self.id)
    route()
    return self

download_background_image

download_background_image(path: Path) -> Path | None

Download a background image from the project

PARAMETER	DESCRIPTION
path	Path to save the image file TYPE: Path

RETURNS	DESCRIPTION
Path	Path to the downloaded image file or None if no background image is set TYPE: Path | None

Example

>>> project.download_background_image('/home/user/downloads/background.jpg')

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

def download_background_image(self, path: Path) -> Path | None:
    """Download a background image from the project

    Args:
        path (Path): Path to save the image file

    Returns:
        Path: Path to the downloaded image file or None if no background image is set

    Example:
        ```python
        >>> project.download_background_image('/home/user/downloads/background.jpg')
        ```
    """
    if not self.backgroundImage:
        return None

    path = Path(path)
    path.write_bytes(self.routes.handler._get_file(self.backgroundImage['url']))
    return path

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()

gradient_css

gradient_css() -> str | None

Get the CSS value for the project gradient

Note

If the project has no gradient set, this will return None

RETURNS	DESCRIPTION
str | None	CSS value for the gradient

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

def gradient_css(self) -> str | None:
    """Get the CSS value for the project gradient

    Note:
        If the project has no gradient set, this will return `None`

    Returns:
        CSS value for the gradient
    """
    gradient = self.background
    if gradient.type != 'gradient':
        return None
    return self.gradient_to_css[gradient.name]

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 project data

Note

All objects accessed by properties are always up to date, but the root object that contains those properties keeps a cache of its own data. This method refreshes the root object data.

FUTURE: This method might be removed or disabled in the future if I can get a getattr implementation to work without causing infinite recursion updating the root object when properties are accessed

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

def refresh(self) -> None:
    """Refreshes the project data

    Note:
        All objects accessed by properties are always up to date, but the root object that contains those
        properties keeps a cache of its own data. This method refreshes the root object data.

        FUTURE: This method might be removed or disabled in the future if I can get a __getattr__ implementation
        to work without causing infinite recursion updating the root object when properties are accessed

    """
    route = self.routes.get_project(id=self.id)
    self.__init__(**route()['item'])

remove_background_image

remove_background_image() -> None

Remove the background image from the project

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

def remove_background_image(self) -> None:
    """Remove the background image from the project"""
    with self.editor():
        if self.backgroundImage:
            self.backgroundImage = None
            self.background = {'name': f'{choice(self.gradients)}', 'type': 'gradient'}

set_background_gradient

set_background_gradient(gradient: Gradient) -> Project

Set a background gradient for the project

PARAMETER	DESCRIPTION
gradient	Background gradient to set TYPE: Gradient

RETURNS	DESCRIPTION
Project	Updated project instance TYPE: Project

RAISES	DESCRIPTION
ValueError	If the gradient name is not in the available gradients

Example

>>> project.set_background_gradient('blue-xchange')

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

def set_background_gradient(self, gradient: Gradient) -> Project:
    """Set a background gradient for the project

    Args:
        gradient (Gradient): Background gradient to set

    Returns:
        Project: Updated project instance

    Raises:
        ValueError: If the gradient name is not in the available gradients

    Example:
        ```python
        >>> project.set_background_gradient('blue-xchange')
        ```
    """
    if gradient not in self.gradients:
        raise ValueError(
            f'Invalid gradient: {gradient}'
            f'Available gradients: {self.gradients}')

    with self.editor():
        self.backgroundImage = None            
        self.background = {'name': gradient, 'type': 'gradient'}

    return self

set_background_image

set_background_image(image: Path) -> BackgroundImage

Add a background image to the project

PARAMETER	DESCRIPTION
image	Path to the image file TYPE: Path

RETURNS	DESCRIPTION
BackgroundImage	New background image TYPE: BackgroundImage

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

def set_background_image(self, image: Path) -> BackgroundImage:
    """Add a background image to the project

    Args:
        image (Path): Path to the image file

    Returns:
        BackgroundImage: New background image
    """
    route = self.routes.post_project_background_image(id=self.id)
    return BackgroundImage(**route(_file=image)['item']['backgroundImage'])

update

update(project: Project) -> Project

update(name: str = None) -> Project

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

Updates the project with new values

Note

To set background image, use the set_background_image method To set a background gradient, use the set_background_gradient method

PARAMETER	DESCRIPTION
name	Name of the project (required) TYPE: str

ALTERNATE	DESCRIPTION
project	Project instance to update (required) TYPE: Project

RETURNS	DESCRIPTION
Project	Updated project instance TYPE: Project

Example

>>> project.update(name='My New Project', background='blue-xchange'))

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

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

    Note:
        To set background image, use the `set_background_image` method
        To set a background gradient, use the `set_background_gradient` method

    Args:
        name (str): Name of the project (required)

    Args: Alternate
        project (Project): Project instance to update (required)

    Returns:
        Project: Updated project instance

    Example:
        ```python
        >>> project.update(name='My New Project', background='blue-xchange'))
        ```
    """
    overload = parse_overload(
        args, kwargs, model='project', 
        options=('name',),
        noarg=self)

    # Keep it backwards compatible
    # Allow setting gradient directly by name
    if 'background' in overload and isinstance(overload['background'], str):
        bg = overload.pop('background') # Remove background from overload
        if bg in self.gradients:
            self.set_background_gradient(bg) # Set the gradient if it's valid

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