Planka

Root object for interacting with the Planka API

Attributes:

Name	Type	Description
auth	Type[BaseAuth]	Authentication method
url	str	Base url for the Planka instance
handler	JSONHandler	JSONHandler instance for making requests

Note

All objects that return a list of objects will return a QueryableList object. This object is a subclass of list see the QueryableList docs for more information

Note

All implemented public properties return API responses with accessed. This means that the values are not cached and will be updated on every access. If you wish to cache values, you are responsible for doing so. By default, property access will always provide the most up to date information.

Example:

>>> len(project.cards)
5
>>> project.create_card('My Card')
>>> len(project.cards)
6

Example

>>> from plankapy import Planka, PasswordAuth

>>> auth = PasswordAuth('username', 'password')
>>> planka = Planka('https://planka.example.com', auth)

>>> planka.me
User(id=...9234, name='username', ...)

Tip

If you want to store a property chain to update later, but dont want to call it by full name, you can use a lambda

Example:

>>> card = lambda: planka.project[0].boards[0].lists[0].cards[0]
>>> comments = lambda: card().comments
>>> len(comments())
2

>>> card().add_comment('My Comment')
>>> len(comments())
3

Tip

All objects inherit the editor context manager from the Model class except Planka. This means if you want to make changes to something, you can do it directly to attributes in an editor context instead of calling the model's update method

Example:

>>> with card.editor():
...    card.name = 'My New Card'
...    card.description = 'My New Description'

>>> card.name
'My New Card'

Source code in src/plankapy/interfaces.py

class Planka:
    """Root object for interacting with the Planka API

    Attributes:
        auth (Type[BaseAuth]): Authentication method
        url (str): Base url for the Planka instance
        handler (JSONHandler): JSONHandler instance for making requests

    Note:
        All objects that return a list of objects will return a `QueryableList` object. This object is a subclass of `list`
        see the `QueryableList` docs for more information

    Note:
        All implemented public properties return API responses with accessed. This means that the values are not cached 
        and will be updated on every access. If you wish to cache values, you are responsible for doing so. By default, 
        property access will always provide the most up to date information.

        Example:
            ```python
            >>> len(project.cards)
            5
            >>> project.create_card('My Card')
            >>> len(project.cards)
            6
            ```

    Example:
        ```python
        >>> from plankapy import Planka, PasswordAuth

        >>> auth = PasswordAuth('username', 'password')
        >>> planka = Planka('https://planka.example.com', auth)

        >>> planka.me
        User(id=...9234, name='username', ...)
        ```

    Tip:
        If you want to store a property chain to update later, but dont want to call it by full name, you can use a lambda

        Example:
            ```python
            >>> card = lambda: planka.project[0].boards[0].lists[0].cards[0]
            >>> comments = lambda: card().comments
            >>> len(comments())
            2

            >>> card().add_comment('My Comment')
            >>> len(comments())
            3
            ```

    Tip:
        All objects inherit the `editor` context manager from the `Model` class except `Planka`.
        This means if you want to make changes to something, you can do it directly to attributes
        in an editor context instead of calling the model's `update` method

        Example:
            ```python
            >>> with card.editor():
            ...    card.name = 'My New Card'
            ...    card.description = 'My New Description'

            >>> card.name
            'My New Card'
            ```
    """
    def __init__(self, url: str, auth: Type[BaseAuth]):        
        self._url = url
        self._auth = auth
        self._create_session()

    def _create_session(self) -> None:
        """INTERNAL: Creates a new session with the current authentication method and url"""
        self.handler = JSONHandler(self.url)
        self.handler.headers.update(self.auth.authenticate(self.url))
        self.routes = Routes(self.handler)

    @property
    def auth(self) -> Type[BaseAuth]:
        """Current authentication instance

        Returns:
            Authentication method
        """
        return self._auth

    @auth.setter
    def auth(self, auth: Type[BaseAuth]):
        """Changes the authentication method and creates a new session

        Args:
            auth (Type[BaseAuth]): New authentication method

        Warning:
            Changing the authentication method will create a new session with the current url, 
            If you need to change both the url and the authentication method, create a new Planka instance

        Example:
            ```python
            >>> planka.auth = TokenAuth('<new_token>')
            ```
        """
        self._auth = auth
        self._create_session(auth)

    @property
    def url(self) -> str:
        """The current planka url

        Returns:
            Planka url
        """
        return self._url

    @url.setter
    def url(self, url: str):
        """Changes the base url and creates a new session

        Args:
            url: New base url

        Warning:
            Changing the url will create a new session with the current authentication method, 
            If you need to change both the url and the authentication method, create a new Planka instance

        Example:
            ```python
            >>> planka.url = 'https://planka.example.com'
            ```
        """
        self._url = url
        self._create_session(self.auth)

    @property
    def projects(self) -> QueryableList[Project]:
        """Queryable List of all projects on the Planka instance

        Returns:
            Queryable List of all projects
        """
        route = self.routes.get_project_index()
        return QueryableList([
            Project(**project).bind(self.routes)
            for project in route()['items']
        ])

    @property
    def users(self) -> QueryableList[User]:
        """Queryable List of all users on the Planka instance

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

    @property
    def notifications(self) -> QueryableList[Notification]:
        """Queryable List of all notifications for the current user

        Returns:
            Queryable List of all notifications
        """
        route = self.routes.get_notification_index()
        return QueryableList([
            Notification(**notification).bind(self.routes)
            for notification in route()['items']
        ])

    @property
    def project_background_images(self) -> QueryableList[BackgroundImage]:
        """Get Project Background Images

        Returns:
            Queryable List of all project background images
        """
        return QueryableList(
            BackgroundImage(**project.backgroundImage)
            for project in self.projects
            if project.backgroundImage
        )

    @property
    def user_avatars(self) -> list[str]:
        """Get User Avatars

        Returns:
            Queryable List of all user avatar links
        """
        return [
            user.avatarUrl
            for user in self.users
            if user.avatarUrl
        ]
    @property
    def me(self) -> User:
        """Current Logged in User

        Returns:
            Current user
        """
        route = self.routes.get_me()
        return User(**route()['item']).bind(self.routes)

    @property
    def config(self) -> JSONHandler.JSONResponse:
        """Planka Configuration

        Returns:
            Configuration data
        """
        route = self.routes.get_config()
        return route()['item']

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

    @overload
    def create_project(self, name: str, position: int=None, 
                       background: Gradient=None) -> Project: ...

    def create_project(self, *args, **kwargs) -> Project:
        """Creates a new project

        Note:
            If no background is provided, a random gradient will be assigned

            If no position is provided, the project will be created at position 0

        Args:
            name (str): Name of the project (required)
            position (int): Position of the project (default: 0)
            background (Gradient): Background gradient of the project (default: None)

        Args: Alternate
            project (Project): Project instance to create

        Returns:
            Project: New project instance

        Example:
            ```python
            >>> new_project = planka.create_project('My Project')
            >>> new_project.set_background_gradient('blue-xchange') # Set background gradient
            >>> new_project.add_project_manager(planka.me) # Add current user as project manager
            ```
        """
        overload = parse_overload(args, kwargs, model='project', 
                                  options=('name', 'position', 'background'), 
                                  required=('name',))

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

        style = overload.get('background', None)
        route = self.routes.post_project()
        project = Project(**route(**overload)['item']).bind(self.routes)

        with project.editor(): # Project POST does not accept background, so we set it after creation
            project.set_background_gradient(style or choice(Project.gradients))

        return project


    def create_user(self, username: str, email: str, password: str, name: str=None) -> User:
        """Create a new user

        Note:
            Planka will reject insecure passwords! If creating a user with a specific password fails, 
            try a more secure password

        Note:
            If the username is not lowercase, it will be converted to lowercase

        Args:
            username (str): Username of the user (required)
            email (str): Email address of the user (required)
            password (str): Password for the user (required)
            name (str): Full name of the user (default: `username`)

        Raises:
            ValueError: If the username or email already exists
            ValueError: If password is insecure or a 400 code is returned
        """

        username = username.strip()
        if not username.islower():
            print('Warning: Usernames are converted to lowercase')
            username = username.lower()

        for user in self.users:
            if user.username == username:
                raise ValueError(f'Username {username} already exists. '
                                 'Please use a different username')
            if user.email == email:
                raise ValueError(f'Email {email} already exists. '
                                 'Please use a different email address')

        route = self.routes.post_user()
        try:
            return User(**route(username=username, name=name or username, password=password, email=email)['item']).bind(self.routes)
        except HTTPError as e:
            if e.code == 400: # Invalid password, email, or username
                raise ValueError(
                    f'Failed to create user {username}:\n'
                    '\tTry: \n'
                    '\t\tA more secure password\n'
                    '\t\tValidating the user\'s email address\n'
                    '\t\tChecking that the username has no whitespace') from e
            else: # Unknown error
                raise e

auth property writable

Current authentication instance

Returns:

Type	Description
Type[BaseAuth]	Authentication method

config property

Planka Configuration

Returns:

Type	Description
JSONResponse	Configuration data

me property

Current Logged in User

Returns:

Type	Description
User	Current user

notifications property

Queryable List of all notifications for the current user

Returns:

Type	Description
QueryableList[Notification]	Queryable List of all notifications

project_background_images property

Get Project Background Images

Returns:

Type	Description
QueryableList[BackgroundImage]	Queryable List of all project background images

projects property

Queryable List of all projects on the Planka instance

Returns:

Type	Description
QueryableList[Project]	Queryable List of all projects

url property writable

The current planka url

Returns:

Type	Description
str	Planka url

user_avatars property

Get User Avatars

Returns:

Type	Description
list[str]	Queryable List of all user avatar links

users property

Queryable List of all users on the Planka instance

Returns:

Type	Description
QueryableList[User]	Queryable List of all users

create_project(*args, **kwargs)

create_project(project: Project) -> Project

create_project(name: str, position: int = None, background: Gradient = None) -> Project

Creates a new project

Note

If no background is provided, a random gradient will be assigned

If no position is provided, the project will be created at position 0

Parameters:

Name	Type	Description	Default
name	str	Name of the project (required)	required
position	int	Position of the project (default: 0)	required
background	Gradient	Background gradient of the project (default: None)	required

Alternate

Name	Type	Description	Default
project	Project	Project instance to create	required

Returns:

Name	Type	Description
Project	Project	New project instance

Example

>>> new_project = planka.create_project('My Project')
>>> new_project.set_background_gradient('blue-xchange') # Set background gradient
>>> new_project.add_project_manager(planka.me) # Add current user as project manager

Source code in src/plankapy/interfaces.py

def create_project(self, *args, **kwargs) -> Project:
    """Creates a new project

    Note:
        If no background is provided, a random gradient will be assigned

        If no position is provided, the project will be created at position 0

    Args:
        name (str): Name of the project (required)
        position (int): Position of the project (default: 0)
        background (Gradient): Background gradient of the project (default: None)

    Args: Alternate
        project (Project): Project instance to create

    Returns:
        Project: New project instance

    Example:
        ```python
        >>> new_project = planka.create_project('My Project')
        >>> new_project.set_background_gradient('blue-xchange') # Set background gradient
        >>> new_project.add_project_manager(planka.me) # Add current user as project manager
        ```
    """
    overload = parse_overload(args, kwargs, model='project', 
                              options=('name', 'position', 'background'), 
                              required=('name',))

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

    style = overload.get('background', None)
    route = self.routes.post_project()
    project = Project(**route(**overload)['item']).bind(self.routes)

    with project.editor(): # Project POST does not accept background, so we set it after creation
        project.set_background_gradient(style or choice(Project.gradients))

    return project

create_user(username, email, password, name=None)

Create a new user

Note

Planka will reject insecure passwords! If creating a user with a specific password fails, try a more secure password

Note

If the username is not lowercase, it will be converted to lowercase

Parameters:

Name	Type	Description	Default
username	str	Username of the user (required)	required
email	str	Email address of the user (required)	required
password	str	Password for the user (required)	required
name	str	Full name of the user (default: username)	None

Raises:

Type	Description
ValueError	If the username or email already exists
ValueError	If password is insecure or a 400 code is returned

Source code in src/plankapy/interfaces.py

def create_user(self, username: str, email: str, password: str, name: str=None) -> User:
    """Create a new user

    Note:
        Planka will reject insecure passwords! If creating a user with a specific password fails, 
        try a more secure password

    Note:
        If the username is not lowercase, it will be converted to lowercase

    Args:
        username (str): Username of the user (required)
        email (str): Email address of the user (required)
        password (str): Password for the user (required)
        name (str): Full name of the user (default: `username`)

    Raises:
        ValueError: If the username or email already exists
        ValueError: If password is insecure or a 400 code is returned
    """

    username = username.strip()
    if not username.islower():
        print('Warning: Usernames are converted to lowercase')
        username = username.lower()

    for user in self.users:
        if user.username == username:
            raise ValueError(f'Username {username} already exists. '
                             'Please use a different username')
        if user.email == email:
            raise ValueError(f'Email {email} already exists. '
                             'Please use a different email address')

    route = self.routes.post_user()
    try:
        return User(**route(username=username, name=name or username, password=password, email=email)['item']).bind(self.routes)
    except HTTPError as e:
        if e.code == 400: # Invalid password, email, or username
            raise ValueError(
                f'Failed to create user {username}:\n'
                '\tTry: \n'
                '\t\tA more secure password\n'
                '\t\tValidating the user\'s email address\n'
                '\t\tChecking that the username has no whitespace') from e
        else: # Unknown error
            raise e