canarieapi.utility_rest

REST API utilities.

This module is a collection of utility functions used mainly by the rest_route module and which are placed here to keep the rest_route module as clean as possible.

Module Contents

Classes

DatabaseRetryFunction	Base class for protocol classes.
AnyIntConverter	Matches one of the items provided.

Functions

request_wants_json(→ bool)	Check if the request type is of type JSON considering both the Accept header and f query parameter.
set_html_as_default_response(→ None)	Set the default response Media-Type, with fallback to JSON.
get_config(→ JSON)	Return the config for the particular service/platform associated with the given route name.
validate_route(→ None)	Check if the route name is a value amongst known services/platforms in the configuration.
get_api_title(→ str)	Get the API title to be shown in rendered html page.
get_canarie_api_response(...)	Provide a valid response for the CANARIE API request based on the service route.
make_error_response(→ Tuple[Union[flask.Response, ...)	Make an error response based on the request type and given information.
get_db(→ sqlite3.Connection)	Get a connection to an existing database.
init_db(→ None)	Initialize a database from a schema.
retry_db_error_after_init(→ DatabaseRetryFunction)	Decorator that will retry a failing operation if an error related to database initialization occurred.

Attributes

APIType
_JSON
JSON
ReturnType

canarieapi.utility_rest.APIType

canarieapi.utility_rest._JSON: typing_extensions.TypeAlias = 'JSON'

canarieapi.utility_rest.JSON

canarieapi.utility_rest.ReturnType

canarieapi.utility_rest.request_wants_json() → bool

Check if the request type is of type JSON considering both the Accept header and f query parameter.

The default Media-Type */* will be interpreted as JSON. Omitting a preferred type entirely will also default to JSON.

canarieapi.utility_rest.set_html_as_default_response() → None

Set the default response Media-Type, with fallback to JSON.

By default, if the accepted mimetypes contains /, JSON format will be used. By calling this function, the / mimetype will be changed explicitly into text/html so that it becomes the mimetype used by default. This is useful for automatically rendering HTML by web browsers that do not provide explicitly the desired mimetype.

canarieapi.utility_rest.get_config(route_name: str, api_type: APIType) → JSON

Return the config for the particular service/platform associated with the given route name.

Parameters:

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

Raises:

Exception if the route is unknown

canarieapi.utility_rest.validate_route(route_name: str, api_type: APIType) → None

Check if the route name is a value amongst known services/platforms in the configuration.

Parameters:

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

Raises:

Exception if the route is unknown

canarieapi.utility_rest.get_api_title(route_name: str, api_type: APIType) → str

Get the API title to be shown in rendered html page.

Parameters:

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

Returns:

An API title

canarieapi.utility_rest.get_canarie_api_response(route_name: str, api_type: APIType, api_request: str) → flask.typing.ResponseReturnValue

Provide a valid response for the CANARIE API request based on the service route.

Parameters:

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

• api_request – The request specified in the URL

Returns:

A valid HTML response

canarieapi.utility_rest.make_error_response(http_status: int | None = None, http_status_response: str | None = None) → Tuple[flask.Response | str, int]

Make an error response based on the request type and given information.

Parameters:

• http_status – HTTP status

• http_status_response – Standard message associated with a status code. Obtained via http.client.responses if not provided.

canarieapi.utility_rest.get_db(allow_cache: bool = True, connect: bool = True) → sqlite3.Connection

Get a connection to an existing database.

If the database does not exist, create a connection to local sqlite3 file. If the local sqlite3 file doesn’t exist, initialize it using a schema.

Stores the established connection in the application’s global context to reuse it whenever required.

canarieapi.utility_rest.init_db(database: sqlite3.Connection) → None

Initialize a database from a schema.

class canarieapi.utility_rest.DatabaseRetryFunction

Bases: typing_extensions.Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing), for example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

__call__(*args: Any, database: sqlite3.Connection | None = None, **kwargs: Any) → ReturnType

canarieapi.utility_rest.retry_db_error_after_init(func: DatabaseRetryFunction) → DatabaseRetryFunction

Decorator that will retry a failing operation if an error related to database initialization occurred.

class canarieapi.utility_rest.AnyIntConverter(mapping: werkzeug.routing.Map, *items: int | str)

Bases: werkzeug.routing.BaseConverter

Matches one of the items provided.

Items must be integer and comma separated with a space to avoid confusion with floating point value in the parser.

For example:

1, 2, 3

And not:

1,2,3

Since it would parse as float 1,2 and 3.