canarieapi.utility_rest ======================= .. py:module:: canarieapi.utility_rest .. autoapi-nested-parse:: 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. Attributes ---------- .. autoapisummary:: canarieapi.utility_rest.APIType canarieapi.utility_rest._JSON canarieapi.utility_rest.JSON canarieapi.utility_rest.ReturnType Classes ------- .. autoapisummary:: canarieapi.utility_rest.DatabaseRetryFunction canarieapi.utility_rest.AnyIntConverter Functions --------- .. autoapisummary:: canarieapi.utility_rest.request_wants_json canarieapi.utility_rest.set_html_as_default_response canarieapi.utility_rest.get_config canarieapi.utility_rest.validate_route canarieapi.utility_rest.get_api_title canarieapi.utility_rest.get_canarie_api_response canarieapi.utility_rest.make_error_response canarieapi.utility_rest.get_db canarieapi.utility_rest.init_db canarieapi.utility_rest.retry_db_error_after_init Module Contents --------------- .. py:data:: APIType .. py:data:: _JSON :type: typing_extensions.TypeAlias :value: 'JSON' .. py:data:: JSON .. py:data:: ReturnType .. py:function:: 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. .. py:function:: 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. .. py:function:: get_config(route_name: str, api_type: APIType) -> JSON Return the config for the particular service/platform associated with the given route name. :param route_name: Route name of the service/platform coming from the URL e.g. : ['pavics', 'node', 'bias', etc.] :param api_type: Api type of the route which must be one of platform or service :raises: Exception if the route is unknown .. py:function:: validate_route(route_name: str, api_type: APIType) -> None Check if the route name is a value amongst known services/platforms in the configuration. :param route_name: Route name of the service/platform coming from the URL e.g. : ['pavics', 'node', 'bias', etc.] :param api_type: Api type of the route which must be one of platform or service :raises: Exception if the route is unknown .. py:function:: get_api_title(route_name: str, api_type: APIType) -> str Get the API title to be shown in rendered html page. :param route_name: Route name of the service/platform coming from the URL e.g. : ['pavics', 'node', 'bias', etc.] :param api_type: Api type of the route which must be one of platform or service :returns: An API title .. py:function:: 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. :param route_name: Route name of the service/platform coming from the URL e.g. : ['pavics', 'node', 'bias', etc.] :param api_type: Api type of the route which must be one of platform or service :param api_request: The request specified in the URL :returns: A valid HTML response .. py:function:: make_error_response(http_status: Optional[int] = None, http_status_response: Optional[str] = None) -> Tuple[Union[flask.Response, str], int] Make an error response based on the request type and given information. :param http_status: HTTP status :param http_status_response: Standard message associated with a status code. Obtained via :py:data:`http.client.responses` if not provided. .. py:function:: 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. .. py:function:: init_db(database: sqlite3.Connection) -> None Initialize a database from a schema. .. py:class:: DatabaseRetryFunction Bases: :py:obj:`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: ... .. py:method:: __call__(*args: Any, database: Optional[sqlite3.Connection] = None, **kwargs: Any) -> ReturnType .. py:function:: retry_db_error_after_init(func: DatabaseRetryFunction) -> DatabaseRetryFunction Decorator that will retry a failing operation if an error related to database initialization occurred. .. py:class:: AnyIntConverter(mapping: werkzeug.routing.Map, *items: Union[int, str]) Bases: :py:obj:`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. .. py:attribute:: regex :value: '(?:)'