Project

Bases: Project_

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

Attributes:

Name	Type	Description
gradients	list[Gradient]	All available gradients
gradient_to_css	dict[Gradient, str]	Mapping of gradient names to CSS values

Source code in src/plankapy/interfaces.py

class Project(Project_):
    """Interface for interacting with planka Projects and their included sub-objects

    Attributes:
        gradients (list[Gradient]): All available gradients
        gradient_to_css (dict[Gradient, str]): Mapping of gradient names to CSS values
    """

    gradients = Gradient.__args__
    gradient_to_css = GradientCSSMap

    @property
    def _included(self) -> JSONHandler.JSONResponse:
        """Included data for the project

        Warning:
            This property is meant to be used internally for building objects in the other properties
            It can be directly accessed, but it will only return JSON data and not objects

        Returns:
            Included data for the project
        """
        route = self.routes.get_project(id=self.id)
        return route()['included']

    @property
    def users(self) -> QueryableList[User]:
        """All users in the project

        Returns:
            Queryable List of all users
        """
        return QueryableList([
            User(**user).bind(self.routes)
            for user in self._included['users']
        ])

    @property
    def projectManagers(self) -> 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:
            Queryable List of all project manager relations
        """
        return QueryableList([
            ProjectManager(**projectManager).bind(self.routes)
            for projectManager in self._included['projectManagers']
        ])

    @property
    def managers(self) -> QueryableList[User]:
        """All project managers (Users)

        Returns:
            Queryable List of all project managers
        """
        return QueryableList([
            user
            for user in self.users
            for projectManager in self.projectManagers
            if projectManager.userId == user.id
        ])


    @property
    def boardMemberships(self) -> 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:
            Queryable List of all board membership relations in the project    
        """
        return QueryableList([
            BoardMembership(**boardMembership).bind(self.routes)
            for boardMembership in self._included['boardMemberships']
        ])

    @property
    def boards(self) -> QueryableList[Board]:
        """All boards in the project

        Returns:
            Queryable List of all boards
        """
        return QueryableList([
            Board(**board).bind(self.routes)
            for board in self._included['boards']
        ])

    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


    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]

    @overload
    def create_board(self, board: Board) -> Board: ...

    @overload
    def create_board(self, name: str, position: int=0) -> Board: ...

    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)

    @overload
    def add_project_manager(self, user: User) -> ProjectManager: ...

    @overload
    def add_project_manager(self, userId: int) -> ProjectManager: ...

    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)

    @overload
    def remove_project_manager(project_manager: User) -> ProjectManager | None: ...

    @overload
    def remove_project_manager(userId: int) -> ProjectManager | None: ...

    def remove_project_manager(self, *args, **kwargs) -> ProjectManager | None:
        overload = parse_overload(args, kwargs,
                                  model='user',
                                  options=('userId',),
                                  required=('userId',)
        )

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

        for manager in self.projectManagers:
            if manager.userId == overload['userId']:
                return manager.delete()

    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

    @overload
    def update(self, project: Project) -> Project: ...

    @overload
    def update(self, name: str=None) -> Project: ...

    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

    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

    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'])

    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'}

    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'])

boardMemberships property

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:

Type	Description
QueryableList[BoardMembership]	Queryable List of all board membership relations in the project

boards property

All boards in the project

Returns:

Type	Description
QueryableList[Board]	Queryable List of all boards

managers property

All project managers (Users)

Returns:

Type	Description
QueryableList[User]	Queryable List of all project managers

projectManagers property

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:

Type	Description
QueryableList[ProjectManager]	Queryable List of all project manager relations

users property

All users in the project

Returns:

Type	Description
QueryableList[User]	Queryable List of all users

add_project_manager(*args, **kwargs)

add_project_manager(user: User) -> ProjectManager

add_project_manager(userId: int) -> 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

Parameters:

Name	Type	Description	Default
userId	int	id of the user to make project manager (required)	required

Alternate

Name	Type	Description	Default
user	User	User instance to create (required)	required

Returns:

Name	Type	Description
ProjectManager	ProjectManager	New project manager instance

Example

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

Source code in src/plankapy/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)

create_board(*args, **kwargs)

create_board(board: Board) -> Board

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

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

Parameters:

Name	Type	Description	Default
name	str	Name of the board	required
position	int	Position of the board (default: 0)	required

Alternate

Name	Type	Description	Default
board	Board	Board instance to create	required

Returns:

Name	Type	Description
Board	Board	New board instance

Source code in src/plankapy/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()

Deletes the project

Danger

This action is irreversible and cannot be undone

Returns:

Name	Type	Description
Project	Project	Deleted project instance

Source code in src/plankapy/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(path)

Download a background image from the project

Parameters:

Name	Type	Description	Default
path	Path	Path to save the image file	required

Returns:

Name	Type	Description
Path	Path | None	Path to the downloaded image file or None if no background image is set

Example

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

Source code in src/plankapy/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

gradient_css()

Get the CSS value for the project gradient

Note

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

Returns:

Type	Description
str | None	CSS value for the gradient

Source code in src/plankapy/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]

refresh()

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/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 the background image from the project

Source code in src/plankapy/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(gradient)

Set a background gradient for the project

Parameters:

Name	Type	Description	Default
gradient	Gradient	Background gradient to set	required

Returns:

Name	Type	Description
Project	Project	Updated project instance

Raises:

Type	Description
ValueError	If the gradient name is not in the available gradients

Example

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

Source code in src/plankapy/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(image)

Add a background image to the project

Parameters:

Name	Type	Description	Default
image	Path	Path to the image file	required

Returns:

Name	Type	Description
BackgroundImage	BackgroundImage	New background image

Source code in src/plankapy/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(*args, **kwargs)

update(project: Project) -> Project

update(name: str = None) -> 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

Parameters:

Name	Type	Description	Default
name	str	Name of the project (required)	required

Alternate

Name	Type	Description	Default
project	Project	Project instance to update (required)	required

Returns:

Name	Type	Description
Project	Project	Updated project instance

Example

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

Source code in src/plankapy/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