Planka

Root object for interacting with the Planka API

ATTRIBUTE	DESCRIPTION
auth	Authentication method TYPE: Type[BaseAuth]
url	Base url for the Planka instance TYPE: str
handler	JSONHandler instance for making requests TYPE: JSONHandler

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'

METHOD	DESCRIPTION
create_project	Creates a new project
create_user	Create a new user

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

def __init__(self, url: str, auth: Type[BaseAuth]):        
    self._url = url
    self._auth = auth
    self._create_session()

auth property writable

auth: Type[BaseAuth]

Current authentication instance

RETURNS	DESCRIPTION
Type[BaseAuth]	Authentication method

config property

config: JSONResponse

Planka Configuration

RETURNS	DESCRIPTION
JSONResponse	Configuration data

me property

me: User

Current Logged in User

RETURNS	DESCRIPTION
User	Current user

notifications property

notifications: QueryableList[Notification]

Queryable List of all notifications for the current user

RETURNS	DESCRIPTION
QueryableList[Notification]	Queryable List of all notifications

project_background_images property

project_background_images: QueryableList[BackgroundImage]

Get Project Background Images

RETURNS	DESCRIPTION
QueryableList[BackgroundImage]	Queryable List of all project background images

projects property

projects: QueryableList[Project]

Queryable List of all projects on the Planka instance

RETURNS	DESCRIPTION
QueryableList[Project]	Queryable List of all projects

url property writable

url: str

The current planka url

RETURNS	DESCRIPTION
str	Planka url

user_avatars property

user_avatars: list[str]

Get User Avatars

RETURNS	DESCRIPTION
list[str]	Queryable List of all user avatar links

users property

users: QueryableList[User]

Queryable List of all users on the Planka instance

RETURNS	DESCRIPTION
QueryableList[User]	Queryable List of all users

create_project

create_project(project: Project) -> Project

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

create_project(*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

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

ALTERNATE	DESCRIPTION
project	Project instance to create TYPE: Project

RETURNS	DESCRIPTION
Project	New project instance TYPE: Project

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/v1/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

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

PARAMETER	DESCRIPTION
username	Username of the user (required) TYPE: str
email	Email address of the user (required) TYPE: str
password	Password for the user (required) TYPE: str
name	Full name of the user (default: username) TYPE: str DEFAULT: None

RAISES	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/v1/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