Source code for civiqhub.listing

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at https://mozilla.org/MPL/2.0/.

"""The collection that every navigation returns.

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

from collections.abc import Callable, Iterable, Iterator, Sequence
from typing import Protocol, TypeVar, overload

from .errors import NotFoundError, ValidationError

__all__ = ["Listing"]


class _Identified(Protocol):
    @property
    def id(self) -> str: ...


ItemT = TypeVar("ItemT", bound=_Identified)

# How many ids a NotFoundError cites, and how many ids repr shows.
_CITED = 8
_SHOWN = 3


[docs] class Listing(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 :class:`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 :class:`~civiqhub.errors.NotFoundError`, which is also a :class:`LookupError`. Two objects with the same id raise :class:`~civiqhub.errors.ValidationError` when the listing is built. Args: items: The objects, in order. """ __slots__ = ("_by_id", "_items") def __init__(self, items: Iterable[ItemT] = ()) -> None: self._items: tuple[ItemT, ...] = tuple(items) self._by_id: dict[str, ItemT] = {} for item in self._items: if item.id in self._by_id: raise ValidationError( f"Two objects of this listing have the id {item.id!r}; " "an id appears once in a listing." ) self._by_id[item.id] = item @overload def __getitem__(self, key: int) -> ItemT: ... @overload def __getitem__(self, key: str) -> ItemT: ... @overload def __getitem__(self, key: slice) -> "Listing[ItemT]": ... def __getitem__(self, key: int | str | slice) -> "ItemT | Listing[ItemT]": if isinstance(key, str): try: return self._by_id[key] except KeyError: raise NotFoundError(self._describe_unknown(key)) from None if isinstance(key, slice): return Listing(self._items[key]) return self._items[key] def __len__(self) -> int: return len(self._items) def __iter__(self) -> Iterator[ItemT]: return iter(self._items) def __contains__(self, item: object) -> bool: if isinstance(item, str): return item in self._by_id key = getattr(item, "id", None) if not isinstance(key, str): return False found = self._by_id.get(key) return found is not None and found == item def __eq__(self, other: object) -> bool: if not isinstance(other, Listing): return NotImplemented return self._items == other._items def __hash__(self) -> int: return hash(self._items) def __repr__(self) -> str: if not self._items: return f"{type(self).__name__}(0)" shown = ", ".join(self.ids[:_SHOWN]) more = ", ..." if len(self) > _SHOWN else "" return f"{type(self).__name__}({len(self)}: {shown}{more})" @property def ids(self) -> tuple[str, ...]: """The ids of the objects, in order.""" return tuple(self._by_id)
[docs] def get(self, id: str) -> ItemT | None: """Return the object with this id, or ``None`` when there is none. Args: id: The id of the object. """ return self._by_id.get(id)
[docs] def where( self, test: Callable[[ItemT], bool] | None = None, /, **equals: object ) -> "Listing[ItemT]": """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. Args: test: A function that tells whether to keep an object. **equals: Names of attributes, each with the value that the attribute must equal. """ return Listing( item for item in self._items if (test is None or test(item)) and all(getattr(item, name) == value for name, value in equals.items()) )
def _describe_unknown(self, key: str) -> str: if not self._items: return f"No object has the id {key!r}: this listing is empty." cited = ", ".join(self.ids[:_CITED]) if len(self) > _CITED: return ( f"No object has the id {key!r} in this listing. Its first ids are: {cited}, " f"and {len(self) - _CITED} more." ) return f"No object has the id {key!r} in this listing. Its ids are: {cited}."