List querying - libvcs._internal.query_list

QueryList is the backbone of the Manager/Cmd pattern. Every ls() method in libvcs returns a QueryList, enabling chainable filtering on the results.

How It’s Used

All Manager classes return QueryList from their ls() methods — git.branches.ls() yields QueryList[GitBranchCmd], git.tags.ls() yields QueryList[GitTagCmd], and so on:

>>> from libvcs.cmd.git import Git
>>> from libvcs._internal.query_list import QueryList
>>> git = Git(path=example_git_repo.path)
>>> isinstance(git.branches.ls(), QueryList)
True
>>> isinstance(git.tags.ls(), QueryList)
True
>>> isinstance(git.remotes.ls(), QueryList)
True

Filtering

QueryList extends Python’s built-in list with Django-style lookups. Filter on any attribute of the contained objects — exact by default, or with a lookup suffix:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.branches.create(branch='feature-a')
''
>>> git.branches.ls().filter(branch_name='master')
[<GitBranchCmd ... branch_name=master>]
>>> git.branches.ls().filter(branch_name__icontains='FEATURE')
[<GitBranchCmd ... branch_name=feature-a>]

Lookups traverse nested structures with __ as well:

>>> from libvcs._internal.query_list import QueryList
>>> cities = QueryList([
...     {'city': 'Tampa', 'weather': {'sky': 'sunny'}},
...     {'city': 'Chicago', 'weather': {'sky': 'windy'}},
... ])
>>> cities.filter(weather__sky='sunny')
[{'city': 'Tampa', 'weather': {'sky': 'sunny'}}]

Available Lookups

Lookup	Description
exact	Exact match (default)
iexact	Case-insensitive exact match
contains	Substring match
icontains	Case-insensitive substring
startswith	Prefix match
istartswith	Case-insensitive prefix
endswith	Suffix match
iendswith	Case-insensitive suffix
in	Value in list
nin	Value not in list
regex	Regular expression match
iregex	Case-insensitive regex

Chaining

Filters can be chained and combined — multiple conditions in one call AND together, and get() retrieves exactly one match:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.branches.create(branch='feature-login')
''
>>> git.branches.create(branch='feature-signup')
''
>>> git.branches.ls().filter(
...     branch_name__startswith='feature',
...     branch_name__endswith='login',
... )
[<GitBranchCmd ... branch_name=feature-login>]
>>> git.branches.ls().filter(
...     branch_name__contains='feature'
... ).filter(branch_name__contains='signup')
[<GitBranchCmd ... branch_name=feature-signup>]
>>> branch = git.branches.get(branch_name='master')
>>> branch.branch_name
'master'

API Reference

Utilities for filtering or searching list of objects / list data.

Note

This is an internal API not covered by versioning policy.

exception libvcs._internal.query_list.MultipleObjectsReturned

exception

exception

exception libvcs._internal.query_list.MultipleObjectsReturned

Bases: Exception

The query returned multiple objects when only one was expected.

exception libvcs._internal.query_list.ObjectDoesNotExist

exception

exception

exception libvcs._internal.query_list.ObjectDoesNotExist

Bases: Exception

The requested object does not exist.

libvcs._internal.query_list.keygetter(obj, path)

function

function

libvcs._internal.query_list.keygetter(obj, path)

Fetch values in objects and keys, supported nested data.

With dictionaries:

>>> keygetter({ "food": { "breakfast": "cereal" } }, "food")
{'breakfast': 'cereal'}

>>> keygetter({ "food": { "breakfast": "cereal" } }, "food__breakfast")
'cereal'

With objects:

>>> from typing import Optional
>>> from dataclasses import dataclass, field

>>> @dataclass()
... class Food:
...     fruit: list[str] = field(default_factory=list)
...     breakfast: Optional[str] = None

>>> @dataclass()
... class Restaurant:
...     place: str
...     city: str
...     state: str
...     food: Food = field(default_factory=Food)

>>> restaurant = Restaurant(
...     place="Largo",
...     city="Tampa",
...     state="Florida",
...     food=Food(
...         fruit=["banana", "orange"], breakfast="cereal"
...     )
... )

>>> restaurant
Restaurant(place='Largo',
    city='Tampa',
    state='Florida',
    food=Food(fruit=['banana', 'orange'], breakfast='cereal'))

>>> keygetter(restaurant, "food")
Food(fruit=['banana', 'orange'], breakfast='cereal')

>>> keygetter(restaurant, "food__breakfast")
'cereal'

Parameters:

• obj (Mapping[str, Any])

• path (str)

Return type:

None | Any | str | list[str] | Mapping[str, str]

libvcs._internal.query_list.parse_lookup(obj, path, lookup)

function

function

libvcs._internal.query_list.parse_lookup(obj, path, lookup)

Check if field lookup key, e.g. “my__path__contains” has comparator, return val.

If comparator not used or value not found, return None.

>>> parse_lookup({ "food": "red apple" }, "food__istartswith", "__istartswith")
'red apple'

It can also look up objects:

>>> from dataclasses import dataclass

>>> @dataclass()
... class Inventory:
...     food: str

>>> item = Inventory(food="red apple")

>>> item
Inventory(food='red apple')

>>> parse_lookup(item, "food__istartswith", "__istartswith")
'red apple'

Parameters:

• obj (Mapping[str, Any])

• path (str)

• lookup (str)

Return type:

Any | None

class libvcs._internal.query_list.LookupProtocol

class

class

class libvcs._internal.query_list.LookupProtocol

Bases: Protocol

Protocol for QueryList filtering operators.

__init__(*args, **kwargs)

method

method

__init__(*args, **kwargs)

_abc_impl = <_abc._abc_data object>

attribute

attribute

_abc_impl = <_abc._abc_data object>

_is_protocol = True

attribute

attribute

_is_protocol = True

libvcs._internal.query_list.lookup_exact(data, rhs)

function

function

libvcs._internal.query_list.lookup_exact(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_iexact(data, rhs)

function

function

libvcs._internal.query_list.lookup_iexact(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_contains(data, rhs)

function

function

libvcs._internal.query_list.lookup_contains(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_icontains(data, rhs)

function

function

libvcs._internal.query_list.lookup_icontains(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_startswith(data, rhs)

function

function

libvcs._internal.query_list.lookup_startswith(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_istartswith(data, rhs)

function

function

libvcs._internal.query_list.lookup_istartswith(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_endswith(data, rhs)

function

function

libvcs._internal.query_list.lookup_endswith(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_iendswith(data, rhs)

function

function

libvcs._internal.query_list.lookup_iendswith(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_in(data, rhs)

function

function

libvcs._internal.query_list.lookup_in(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_nin(data, rhs)

function

function

libvcs._internal.query_list.lookup_nin(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_regex(data, rhs)

function

function

libvcs._internal.query_list.lookup_regex(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

libvcs._internal.query_list.lookup_iregex(data, rhs)

function

function

libvcs._internal.query_list.lookup_iregex(data, rhs)

Parameters:

• data (str | list[str] | Mapping[str, str])

• rhs (str | list[str] | Mapping[str, str] | Pattern[str])

Return type:

bool

exception libvcs._internal.query_list.PKRequiredException

exception

exception

exception libvcs._internal.query_list.PKRequiredException

Bases: Exception

__init__(*args)

method

method

__init__(*args)

Parameters:

args (object)

Return type:

None

exception libvcs._internal.query_list.OpNotFound

exception

exception

exception libvcs._internal.query_list.OpNotFound

Bases: ValueError

__init__(op, *args)

method

method

__init__(op, *args)

Parameters:

• op (str)

• args (object)

Return type:

None

class libvcs._internal.query_list.QueryList

class

class

class libvcs._internal.query_list.QueryList

Bases: list[T], Generic[T]

Filter list of object/dictionaries. For small, local datasets.

Experimental, unstable.

With dictionaries:

>>> query = QueryList(
...     [
...         {
...             "place": "Largo",
...             "city": "Tampa",
...             "state": "Florida",
...             "foods": {"fruit": ["banana", "orange"], "breakfast": "cereal"},
...         },
...         {
...             "place": "Chicago suburbs",
...             "city": "Elmhurst",
...             "state": "Illinois",
...             "foods": {"fruit": ["apple", "cantelope"], "breakfast": "waffles"},
...         },
...     ]
... )

>>> query.filter(place="Chicago suburbs")[0]['city']
'Elmhurst'
>>> query.filter(place__icontains="chicago")[0]['city']
'Elmhurst'
>>> query.filter(foods__breakfast="waffles")[0]['city']
'Elmhurst'
>>> query.filter(foods__fruit__in="cantelope")[0]['city']
'Elmhurst'
>>> query.filter(foods__fruit__in="orange")[0]['city']
'Tampa'

>>> query.filter(foods__fruit__in="apple")
[{'place': 'Chicago suburbs',
    'city': 'Elmhurst',
    'state': 'Illinois',
    'foods':
        {'fruit': ['apple', 'cantelope'], 'breakfast': 'waffles'}}]

>>> query.filter(foods__fruit__in="non_existent")
[]

With objects:

>>> from typing import Any
>>> from dataclasses import dataclass, field

>>> @dataclass()
... class Restaurant:
...     place: str
...     city: str
...     state: str
...     foods: dict[str, Any]

>>> restaurant = Restaurant(
...     place="Largo",
...     city="Tampa",
...     state="Florida",
...     foods={
...         "fruit": ["banana", "orange"], "breakfast": "cereal"
...     }
... )

>>> restaurant
Restaurant(place='Largo',
    city='Tampa',
    state='Florida',
    foods={'fruit': ['banana', 'orange'], 'breakfast': 'cereal'})

>>> query = QueryList([restaurant])

>>> query.filter(foods__fruit__in="banana")
[Restaurant(place='Largo',
    city='Tampa',
    state='Florida',
    foods={'fruit': ['banana', 'orange'], 'breakfast': 'cereal'})]

>>> query.filter(foods__fruit__in="banana")[0].city
'Tampa'

>>> query.get(foods__fruit__in="banana").city
'Tampa'

With objects (nested):

>>> from typing import Optional
>>> from dataclasses import dataclass, field

>>> @dataclass()
... class Food:
...     fruit: list[str] = field(default_factory=list)
...     breakfast: Optional[str] = None

>>> @dataclass()
... class Restaurant:
...     place: str
...     city: str
...     state: str
...     food: Food = field(default_factory=Food)

>>> query = QueryList([
...     Restaurant(
...         place="Largo",
...         city="Tampa",
...         state="Florida",
...         food=Food(
...             fruit=["banana", "orange"], breakfast="cereal"
...         )
...     ),
...     Restaurant(
...         place="Chicago suburbs",
...         city="Elmhurst",
...         state="Illinois",
...         food=Food(
...             fruit=["apple", "cantelope"], breakfast="waffles"
...         )
...     )
... ])

>>> query.filter(food__fruit__in="banana")
[Restaurant(place='Largo',
    city='Tampa',
    state='Florida',
    food=Food(fruit=['banana', 'orange'], breakfast='cereal'))]

>>> query.filter(food__fruit__in="banana")[0].city
'Tampa'

>>> query.get(food__fruit__in="banana").city
'Tampa'

>>> query.filter(food__breakfast="waffles")
[Restaurant(place='Chicago suburbs',
    city='Elmhurst',
    state='Illinois',
    food=Food(fruit=['apple', 'cantelope'], breakfast='waffles'))]

>>> query.filter(food__breakfast="waffles")[0].city
'Elmhurst'

>>> query.filter(food__breakfast="non_existent")
[]

data: Sequence[T]

attribute

attribute

data: Sequence[T]

pk_key: str | None

attribute

attribute

pk_key: str | None

__init__(items=None)

method

method

__init__(items=None)

Parameters:

items (Iterable[T] | None)

Return type:

None

items()

method

method

items()

Return type:

list[tuple[str, T]]

filter(matcher=None, **kwargs)

method

method

filter(matcher=None, **kwargs)

Parameters:

• matcher (Callable[[T], bool] | T | None)

• kwargs (Any)

Return type:

QueryList[T]

get(matcher=None, default=no_arg, **kwargs)

method

method

get(matcher=None, default=no_arg, **kwargs)

Parameters:

• matcher (Callable[[T], bool] | T | None)

• default (Any | None)

• kwargs (Any)

Return type:

T | None