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 aListingtoo. The search by id takes constant time.x in listingaccepts an object or an id. mypy in strict mode refuses an id there, because the listing holds objects:listing.get(id) is not Nonetests 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 aLookupError. Two objects with the same id raiseValidationErrorwhen 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
Nonewhen 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, andrevisions.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]