api.models

Attributes

_DefaultT
log

Exceptions

ApiException	Base class for all API exceptions.
ApiInvalidParamException	Base class for all API exceptions.

Classes

ApiEndpointItem	A single instance of an item of a specific endpoint.
ApiEndpoint	An API endpoint.
ApiEndpointCollection	A collection of all available API endpoints.
AuthEndpoint	This is a Dummy, because morepath requires a model for linking.
ApiKey	Base class used for declarative class definitions.

Module Contents

api.models._DefaultT

api.models.log

exception api.models.ApiException(message: str = 'Internal Server Error', status_code: int = 500, headers: dict[str, str] | None = None)

Bases: Exception

Base class for all API exceptions.

Mainly used to ensure that all exceptions regarding the API are rendered with the correct content type.

message = 'Internal Server Error'

status_code = 500

headers

classmethod capture_exceptions(default_message: str = 'Internal Server Error', default_status_code: int = 500, headers: dict[str, str] | None = None, exception_type: type[Exception] = Exception) → collections.abc.Iterator[None]

exception api.models.ApiInvalidParamException(message: str = 'Invalid Parameter', status_code: int = 400)

Bases: ApiException

Base class for all API exceptions.

Mainly used to ensure that all exceptions regarding the API are rendered with the correct content type.

message = 'Invalid Parameter'

status_code = 400

class api.models.ApiEndpointItem(request: onegov.core.request.CoreRequest, endpoint: str, id: str)

Bases: Generic[onegov.core.collection._M]

A single instance of an item of a specific endpoint.

Passes all functionality to the specific API endpoint and is mainly used for routing.

request

app

endpoint

id

property api_endpoint: ApiEndpoint[onegov.core.collection._M] | None

property item: onegov.core.collection._M | None

property data: dict[str, Any] | None

property links: dict[str, Any] | None

form(request: onegov.core.request.CoreRequest) → onegov.form.Form | None

class api.models.ApiEndpoint(request: onegov.core.request.CoreRequest, extra_parameters: dict[str, str | None] | None = None, page: int | None = None)

Bases: Generic[onegov.core.collection._M]

An API endpoint.

API endpoints wrap collection and do some filter mapping.

To add a new endpoint, inherit from this class and provide the missing functions and properties at the bottom. Note that the collection is expected to be to provide the functionality of onegov.core.collection.Pagination.

endpoint: str = ''

filters: ClassVar[set[str]]

form_class: ClassVar[type[onegov.form.Form] | None] = None

request

app

extra_parameters

page = None

batch_size = 100

property title: str | None

Return a human readable title for this endpoint

property description: str | None

Return a human readable description for this endpoint

for_page(page: int | None) → Self | None

Return a new endpoint instance with the given page while keeping the current filters.

for_filter(**filters: Any) → Self

Return a new endpoint instance with the given filters while discarding the current filters and page.

for_item(item: None) → None

for_item(item: onegov.core.collection._M) → ApiEndpointItem[onegov.core.collection._M]

Return a new endpoint item instance with the given item.

for_item_id(item_id: None) → None

for_item_id(item_id: Any) → ApiEndpointItem[Any]

Return a new endpoint item instance with the given item id.

get_filter(name: str, default: _DefaultT, empty: _EmptyT) → str | _DefaultT | _EmptyT

get_filter(name: str, default: _DefaultT, empty: None = None) → str | _DefaultT | None

get_filter(name: str, default: None = None, *, empty: _EmptyT) → str | _EmptyT | None

get_filter(name: str, default: None = None, empty: None = None) → str | None

Returns the filter value with the given name.

by_id(id: onegov.core.collection.PKType) → onegov.core.collection._M | None

Return the item with the given ID from the collection.

property session: sqlalchemy.orm.Session

property links: dict[str, Self | None]

Returns a dictionary with pagination instances.

property batch: dict[ApiEndpointItem[onegov.core.collection._M], onegov.core.collection._M]

Returns a dictionary with endpoint item instances and their titles.

abstractmethod item_data(item: onegov.core.collection._M) → dict[str, Any]

Return the data properties of the collection item as a dictionary.

For example:

{
    'name': 'Paul',
    'age': 40
}

abstractmethod item_links(item: onegov.core.collection._M) → dict[str, Any]

Return the link properties of the collection item as a dictionary. Links can either be string or a linkable object.

For example:

{
    'website': 'https://onegov.ch',
    'friends': FriendsApiEndpoint(app).for_item(paul),
    'home': ApiEndpointCollection(app)
}

form(item: onegov.core.collection._M | None, request: onegov.core.request.CoreRequest) → onegov.form.Form | None

Return a form for editing items of this collection.

abstractmethod apply_changes(item: onegov.core.collection._M, form: Any) → None

Apply the changes to the item based on the given form data.

property collection: PaginationWithById[onegov.core.collection._M, Any]

Abstractmethod:

Return an instance of the collection with filters and page set.

assert_valid_filter(param: str) → None

class api.models.ApiEndpointCollection(request: onegov.core.request.CoreRequest)

A collection of all available API endpoints.

request

app

property endpoints: dict[str, ApiEndpoint[Any]]

get_endpoint(name: str, page: int = 0, extra_parameters: dict[str, Any] | None = None) → ApiEndpoint[Any] | None

class api.models.AuthEndpoint(app: onegov.core.Framework)

This is a Dummy, because morepath requires a model for linking.

app

class api.models.ApiKey

Bases: onegov.core.orm.Base

Base class used for declarative class definitions.

The _orm.DeclarativeBase allows for the creation of new declarative bases in such a way that is compatible with type checkers:

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass

The above Base class is now usable as the base for new declarative mappings. The superclass makes use of the __init_subclass__() method to set up new classes and metaclasses aren’t used.

When first used, the _orm.DeclarativeBase class instantiates a new _orm.registry to be used with the base, assuming one was not provided explicitly. The _orm.DeclarativeBase class supports class-level attributes which act as parameters for the construction of this registry; such as to indicate a specific _schema.MetaData collection as well as a specific value for :paramref:`_orm.registry.type_annotation_map`:

from typing_extensions import Annotated

from sqlalchemy import BigInteger
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase

bigint = Annotated[int, "bigint"]
my_metadata = MetaData()


class Base(DeclarativeBase):
    metadata = my_metadata
    type_annotation_map = {
        str: String().with_variant(String(255), "mysql", "mariadb"),
        bigint: BigInteger(),
    }

Class-level attributes which may be specified include:

Parameters:

• metadata – optional _schema.MetaData collection. If a _orm.registry is constructed automatically, this _schema.MetaData collection will be used to construct it. Otherwise, the local _schema.MetaData collection will supersede that used by an existing _orm.registry passed using the :paramref:`_orm.DeclarativeBase.registry` parameter.

• type_annotation_map – optional type annotation map that will be passed to the _orm.registry as :paramref:`_orm.registry.type_annotation_map`.

• registry – supply a pre-existing _orm.registry directly.

Added in version 2.0: Added DeclarativeBase, so that declarative base classes may be constructed in such a way that is also recognized by PEP 484 type checkers. As a result, DeclarativeBase and other subclassing-oriented APIs should be seen as superseding previous “class returned by a function” APIs, namely _orm.declarative_base() and _orm.registry.generate_base(), where the base class returned cannot be recognized by type checkers without using plugins.

__init__ behavior

In a plain Python class, the base-most __init__() method in the class hierarchy is object.__init__(), which accepts no arguments. However, when the _orm.DeclarativeBase subclass is first declared, the class is given an __init__() method that links to the :paramref:`_orm.registry.constructor` constructor function, if no __init__() method is already present; this is the usual declarative constructor that will assign keyword arguments as attributes on the instance, assuming those attributes are established at the class level (i.e. are mapped, or are linked to a descriptor). This constructor is never accessed by a mapped class without being called explicitly via super(), as mapped classes are themselves given an __init__() method directly which calls :paramref:`_orm.registry.constructor`, so in the default case works independently of what the base-most __init__() method does.

Changed in version 2.0.1: _orm.DeclarativeBase has a default constructor that links to :paramref:`_orm.registry.constructor` by default, so that calls to super().__init__() can access this constructor. Previously, due to an implementation mistake, this default constructor was missing, and calling super().__init__() would invoke object.__init__().

The _orm.DeclarativeBase subclass may also declare an explicit __init__() method which will replace the use of the :paramref:`_orm.registry.constructor` function at this level:

class Base(DeclarativeBase):
    def __init__(self, id=None):
        self.id = id

Mapped classes still will not invoke this constructor implicitly; it remains only accessible by calling super().__init__():

class MyClass(Base):
    def __init__(self, id=None, name=None):
        self.name = name
        super().__init__(id=id)

Note that this is a different behavior from what functions like the legacy _orm.declarative_base() would do; the base created by those functions would always install :paramref:`_orm.registry.constructor` for __init__().

__tablename__ = 'api_keys'

id: sqlalchemy.orm.Mapped[uuid.UUID]

user_id: sqlalchemy.orm.Mapped[uuid.UUID]

user: sqlalchemy.orm.Mapped[onegov.user.User]

name: sqlalchemy.orm.Mapped[str]

read_only: sqlalchemy.orm.Mapped[bool]

last_used: sqlalchemy.orm.Mapped[datetime.datetime | None]

key: sqlalchemy.orm.Mapped[uuid.UUID]