core.collection

Attributes

PKType
_M

Classes

GenericCollection	Abstract base class for generic types.
SearcheableCollection	Requires a self.locale and self.term
Pagination	Provides collections with pagination, if they implement a few
RangedPagination	Provides a pagination that supports loading multiple pages at once.

Module Contents

core.collection.PKType

core.collection._M

class core.collection.GenericCollection(session: sqlalchemy.orm.Session, **kwargs: Any)

Bases: Generic[_M]

Abstract base class for generic types.

A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default

session

property model_class: type[_M]

Abstractmethod:

property primary_key: Column[str] | Column[UUID] | Column[int]

query() → Query[_M]

by_id(id: PKType) → _M | None

by_ids(ids: Collection[PKType]) → list[_M]

add(**kwargs: Any) → _M

add_by_form(form: _FormThatSupportsGetUsefulData, properties: Iterable[str] | None = None) → _M

delete(item: _M) → None

class core.collection.SearcheableCollection(session: sqlalchemy.orm.Session, **kwargs: Any)

Bases: GenericCollection[_M]

Requires a self.locale and self.term

static match_term(column: Column[str] | Column[str | None], language: str, term: str) → sqlalchemy.sql.elements.ClauseElement

Usage: model.filter(match_term(model.col, ‘german’, ‘my search term’))

static term_to_tsquery_string(term: str) → str

Returns the current search term transformed to use within Postgres to_tsquery function. Removes all unwanted characters, replaces prefix matching, joins word together using FOLLOWED BY.

filter_text_by_locale(column: Column[str] | Column[str | None], term: str, locale: str | None = None) → sqlalchemy.sql.elements.ClauseElement

Returns an SqlAlchemy filter statement based on the search term. If no locale is provided, it will use english as language.

to_tsquery creates a tsquery value from term, which must consist of single tokens separated by the Boolean operators & (AND), | (OR) and ! (NOT).

to_tsvector parses a textual document into tokens, reduces the tokens to lexemes, and returns a tsvector which lists the lexemes together with their positions in the document. The document is processed according to the specified or default text search configuration.

property locale: str

Abstractmethod:

property term_filter: Iterator[ClauseElement]

query() → Query[_M]

class core.collection.Pagination(page: int = 0)

Bases: Generic[_M]

Provides collections with pagination, if they implement a few documented properties and methods.

See onegov.ticket.TicketCollection for an example.

batch_size = 10

page

abstract __eq__(other: object) → bool

Returns True if the current and the other Pagination instance are equal. Used to find the current page in a list of pages.

abstract subset() → Query[_M]

Returns an SQLAlchemy query containing all records that should be considered for pagination.

property cached_subset: Query[_M]

property page_index: int

Abstractmethod:

Returns the current page index (starting at 0).

abstract page_by_index(index: int) → Self

Returns the page at the given index. A page here means an instance of the class inheriting from the Pagination base class.

transform_batch_query(query: Query[_M]) → Query[_M]

Allows subclasses to transform the given query before it is used to retrieve the batch. This is a good place to add additional loading that should only apply to the batch (say joining other values to the batch which are then not loaded by the whole query).

property subset_count: int

Returns the total number of elements this pagination represents.

property batch: tuple[_M, Ellipsis]

Returns the elements on the current page.

property offset: int

Returns the offset applied to the current subset.

property pages_count: int

Returns the number of pages.

property name_of_view: str

The name of the view to link to. If omitted, the the default view is looked up..

property pages: Iterator[Self]

Yields all page objects of this Pagination.

property previous: Self | None

Returns the previous page or None.

property next: Self | None

Returns the next page or None.

class core.collection.RangedPagination

Bases: Generic[_M]

Provides a pagination that supports loading multiple pages at once.

This is useful in a context where a single button is used to ‘load more’ results one by one. In this case we need an URL that represents what’s happening on the screen (multiple pages are shown at the same time).

batch_size = 20

range_limit = 5

abstract subset() → Query[_M]

Returns an SQLAlchemy query containing all records that should be considered for pagination.

property cached_subset: Query[_M]

property page_range: tuple[int, int]

Abstractmethod:

Returns the current page range (starting at (0, 0)).

abstract by_page_range(page_range: tuple[int, int]) → Self

Returns an instance of the collection limited to the given page range.

limit_range(page_range: Sequence[int] | None, direction: Literal['up', 'down']) → tuple[int, int]

Limits the range to the range limit in the given direction.

For example, 0-99 will be limited to 89-99 with a limit of 10 and ‘up’. With ‘down’ it will be limited to 0-9.

transform_batch_query(query: Query[_M]) → Query[_M]

Allows subclasses to transform the given query before it is used to retrieve the batch. This is a good place to add additional loading that should only apply to the batch (say joining other values to the batch which are then not loaded by the whole query).

property subset_count: int

Returns the total number of elements this pagination represents.

property batch: tuple[_M, Ellipsis]

Returns the elements on the current page range.

property pages_count: int

Returns the number of pages.

property previous: Self | None

Returns the previous page or None.

property next: Self | None

Returns the next page range or None.