QueryableList

Bases: list[M], Generic[M]

A list of Queryable objects

This class is a subclass of the built-in list class that allows for querying the list of objects.

Returned by:

• Plankapy v1
  • Board Interfaces
    • Board
      •  attachments
      •  boardMemberships
      •  cardLabels
      •  cardMemberships
      •  cards
      •  editors
      •  labels
      •  lists
      •  tasks
      •  users
      •  viewers
    • Label  cards
    • List  cards
  • Card Interfaces Card
    •  attachments
    •  comments
    •  labels
    •  members
    •  tasks
  • Models  QueryableList
    •  filter_where
    •  order_by
    •  select_where
    •  take
  • Planka
    •  notifications
    •  project_background_images
    •  projects
    •  users
  • Project Interfaces Project
    •  boardMemberships
    •  boards
    •  managers
    •  projectManagers
    •  users
  • QueryableList
    •  filter_where
    •  order_by
    •  select_where
    •  take
  • User Interfaces User
    •  boards
    •  cards
    •  manager_of
    •  notifications
    •  projects

METHOD	DESCRIPTION
filter_where	Filter the list of objects by keyword arguments
order_by	Order the list by a key
pop_where	Get the first object that matches the filter
select_where	Select objects from the list that match a function
take	Take the first n objects from the list

filter_where

filter_where(**kwargs) -> QueryableList[M] | None

Filter the list of objects by keyword arguments

PARAMETER	DESCRIPTION
**kwargs	See Model for the available attributes DEFAULT: {}

RETURNS	DESCRIPTION
QueryableList[M] | None	QueryableList[M]: The objects that match the filter or None if no objects match

Example:

>>> users = QueryableList(project.users)
>>> users
[User(id=1, name='Bob'), User(id=2, name='Alice'), User(id=3, name='Bob')]

>>> users.filter_where(name='Bob')
[User(id=1, name='Bob'), User(id=3, name='Bob')]

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

def filter_where(self, **kwargs) -> QueryableList[M] | None:
    """Filter the list of objects by keyword arguments

    Args:
        **kwargs: See Model for the available attributes

    Returns:
        QueryableList[M]: The objects that match the filter or None if no objects match

    Example:
    ```python
    >>> users = QueryableList(project.users)
    >>> users
    [User(id=1, name='Bob'), User(id=2, name='Alice'), User(id=3, name='Bob')]

    >>> users.filter_where(name='Bob')
    [User(id=1, name='Bob'), User(id=3, name='Bob')]
    ```
    """
    return QueryableList(item for item in self if all(getattr(item, key) == value for key, value in kwargs.items())) or None

order_by

order_by(key: str, desc: bool = False) -> QueryableList[M]

Order the list by a key

PARAMETER	DESCRIPTION
key	The key to order by TYPE: str
desc	True to order in descending order, False otherwise TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
QueryableList[M]	QueryableList[M]: The list of objects ordered by the key

Example:

>>> users = QueryableList(project.users)
>>> users
[User(name='Bob'), User(name='Alice')]

>>> users = users.order_by('name')
>>> users
[User(name='Alice'), User(name='Bob')]

>>> users = users.order_by('name', desc=True)
>>> users
[User(name='Bob'), User(name='Alice')]

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

def order_by(self, key: str, desc: bool=False) -> QueryableList[M]:
    """Order the list by a key

    Args:
        key (str): The key to order by
        desc (bool): True to order in descending order, False otherwise

    Returns:
        QueryableList[M]: The list of objects ordered by the key

    Example:
    ```python
    >>> users = QueryableList(project.users)
    >>> users
    [User(name='Bob'), User(name='Alice')]

    >>> users = users.order_by('name')
    >>> users
    [User(name='Alice'), User(name='Bob')]

    >>> users = users.order_by('name', desc=True)
    >>> users
    [User(name='Bob'), User(name='Alice')]
    ```
    """
    return QueryableList(sorted(self, key=lambda x: getattr(x, key), reverse=desc))

pop_where

pop_where(**kwargs) -> M | None

Get the first object that matches the filter

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to filter the list by DEFAULT: {}

RETURNS	DESCRIPTION
M	The first object that matches the filter TYPE: M | None

Example:

>>> users = QueryableList(project.users)
>>> users
[User(id=1, name='Bob'), User(id=2, name='Alice'), User(id=3, name='Bob')]

>>> users.pop_where(name='Bob')
User(id=1, name='Bob')

>>> user = users.pop_where(name='Frank')
>>> user
None

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

def pop_where(self, **kwargs) -> M | None:
    """Get the first object that matches the filter

    Args:
        **kwargs: Keyword arguments to filter the list by

    Returns:
        M: The first object that matches the filter

    Example:
    ```python
    >>> users = QueryableList(project.users)
    >>> users
    [User(id=1, name='Bob'), User(id=2, name='Alice'), User(id=3, name='Bob')]

    >>> users.pop_where(name='Bob')
    User(id=1, name='Bob')

    >>> user = users.pop_where(name='Frank')
    >>> user
    None
    ```
    """
    vals = self.filter_where(**kwargs)
    return vals[0] if vals else None

select_where

select_where(predicate: Callable[[M], bool]) -> QueryableList[M]

Select objects from the list that match a function

PARAMETER	DESCRIPTION
predicate	A function that takes an object and returns a boolean TYPE: Callable[[M], bool]

RETURNS	DESCRIPTION
QueryableList[M]	QueryableList[M]: The objects that match the function

Example:

>>> users = QueryableList(project.users)
>>> users
[User(id=1, name='Bob'), User(id=2, name='Alice'), User(id=3, name='Frank')]

>>> users = users.select_where(lambda x: x.name in ('Bob', 'Alice'))
>>> users
[User(id=1, name='Bob'), User(id=2, name='Alice')]

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

def select_where(self, predicate: Callable[[M], bool]) -> QueryableList[M]:
    """Select objects from the list that match a function

    Args:
        predicate: A function that takes an object and returns a boolean

    Returns:
        QueryableList[M]: The objects that match the function

    Example:
    ```python
    >>> users = QueryableList(project.users)
    >>> users
    [User(id=1, name='Bob'), User(id=2, name='Alice'), User(id=3, name='Frank')]

    >>> users = users.select_where(lambda x: x.name in ('Bob', 'Alice'))
    >>> users
    [User(id=1, name='Bob'), User(id=2, name='Alice')]
    ```
    """
    return QueryableList(item for item in self if predicate(item))

take

take(n: int) -> QueryableList[M]

Take the first n objects from the list

PARAMETER	DESCRIPTION
n	The number of objects to take TYPE: int

RETURNS	DESCRIPTION
QueryableList[M]	QueryableList[M]: The first n objects in the list, if n is greater than the length of the list, the list is padded with None

Example:

>>> users = QueryableList(project.users)
>>> users.take(2)
[User(name='Alice'), User(name='Bob')]

>>> users.take(3)
[User(name='Alice'), User(name='Bob'), None]

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

def take(self, n: int) -> QueryableList[M]:
    """Take the first n objects from the list

    Args:
        n (int): The number of objects to take

    Returns:
        QueryableList[M]: The first n objects in the list, if n is greater than the length of the list, the list is padded with `None`

    Example:
    ```python
    >>> users = QueryableList(project.users)
    >>> users.take(2)
    [User(name='Alice'), User(name='Bob')]

    >>> users.take(3)
    [User(name='Alice'), User(name='Bob'), None]
    ```
    """
    if n > len(self):
        return self + [None] * (n - len(self))
    return self[:n]