core.collection

Module Contents

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.

Attributes

PKType
_M

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

abstract property model_class: type[_M]

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

property term_filter: Iterator[ClauseElement]

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.

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.

abstract property page_index: int

Returns the current page index (starting at 0).

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.

batch_size = 10

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.

cached_subset() → Query[_M]

abstract page_by_index(index: int) → typing_extensions.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).

subset_count() → int

Returns the total number of elements this pagination represents.

batch() → tuple[_M, Ellipsis]

Returns the elements on the current page.

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).

abstract property page_range: tuple[int, int]

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

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.

batch_size = 20

range_limit = 5

abstract subset() → Query[_M]

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

cached_subset() → Query[_M]

abstract by_page_range(page_range: tuple[int, int]) → typing_extensions.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).

subset_count() → int

Returns the total number of elements this pagination represents.

batch() → tuple[_M, Ellipsis]

Returns the elements on the current page range.