civiqhub.listing

The collection that every navigation returns.

project.proposals and proposal.revisions are each a Listing: an ordered, immutable sequence that is also searched by id.

class civiqhub.listing.Listing(items=())[source]

Bases: Sequence[ItemT]

An ordered, immutable sequence of objects, also searched by id.

It is built from objects that each have an id, and keeps their order. Read an object by position (listing[0], listing[-1]) or by id (listing["p-01"]); a slice (listing[1:3]) is a Listing too. The search by id takes constant time.

x in listing accepts an object or an id. mypy in strict mode refuses an id there, because the listing holds objects: listing.get(id) is not None tests an id as well. Two listings are equal when they hold the same objects in the same order.

An unknown id raises NotFoundError, which is also a LookupError. Two objects with the same id raise ValidationError when the listing is built.

Parameters:

items (Iterable[ItemT]) – The objects, in order.

property ids: tuple[str, ...]

The ids of the objects, in order.

get(id)[source]

Return the object with this id, or None when there is none.

Parameters:

id (str) – The id of the object.

Return type:

ItemT | None

where(test=None, /, **equals)[source]

Keep the objects that pass a test and whose attributes equal the values given.

proposals.where(author_id="m-003") keeps the proposals of one author, and revisions.where(lambda revision: revision.number > 1) the revisions after the first. Without an argument, it returns an equal listing.

Parameters:
  • test (Callable[[ItemT], bool] | None) – A function that tells whether to keep an object.

  • **equals (object) – Names of attributes, each with the value that the attribute must equal.

Return type:

Listing[ItemT]