Skip to content

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.

Source code in src/plankapy/models.py 
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
class QueryableList(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.

    """

    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

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

    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

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

    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]

filter_where(**kwargs)

Filter the list of objects by keyword arguments

Parameters:

Name Type Description Default
**kwargs

See Model for the available attributes

 {}

Returns:

Type 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/models.py 
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
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(key, desc=False)

Order the list by a key

Parameters:

Name Type Description Default
key str

The key to order by

 required
desc bool

True to order in descending order, False otherwise

 False

Returns:

Type 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/models.py 
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
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(**kwargs)

Get the first object that matches the filter

Parameters:

Name Type Description Default
**kwargs

Keyword arguments to filter the list by

 {}

Returns:

Name Type Description
M M | None

The first object that matches the filter

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/models.py 
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
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(predicate)

Select objects from the list that match a function

Parameters:

Name Type Description Default
predicate Callable[[M], bool]

A function that takes an object and returns a boolean

 required

Returns:

Type 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/models.py 
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
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(n)

Take the first n objects from the list

Parameters:

Name Type Description Default
n int

The number of objects to take

 required

Returns:

Type 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/models.py 
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
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]