UWSApplication¶

class safir.uws.UWSApplication(config)¶

Bases: object

Glue between a FastAPI application and the UWS implementation.

An instance of this class should be created during construction of the service that will use the UWS layer. It provides methods to initialize the UWS database, build route handlers, install error handlers, and build the UWS database worker. Construction of the backend worker that does the work of the service is handled separately so that it can have minimal dependencies.

Parameters:: config (UWSConfig) – UWS configuration.

Methods Summary

`build_worker`(logger, *[, check_schema, ...])	Construct an arq worker configuration for the UWS worker.
`initialize_fastapi`([logger, check_schema, ...])	Initialize the UWS subsystem for FastAPI applications.
`initialize_uws_database`(logger, *[, reset, ...])	Initialize the UWS database.
`install_error_handlers`(app)	Install error handlers that follow DALI and UWS conventions.
`install_handlers`(router)	Install the route handlers for the service.
`install_middleware`(app)	Install FastAPI middleware needed by UWS.
`is_schema_current`([logger, config_path])	Check that the database schema is current using Alembic.
`override_arq_queue`(arq_queue)	Change the arq used by the FastAPI route handlers.
`shutdown_fastapi`()	Shut down the UWS subsystem for FastAPI applications.

Methods Documentation

build_worker(logger, *, check_schema=False, alembic_config_path=PosixPath('alembic.ini'))¶

Construct an arq worker configuration for the UWS worker.

All UWS job status and results must be stored in the underlying database, since the API serves job information from there. To minimize dependencies for the worker, which may (for example) pin its own version of SQLAlchemy that may not be compatible with that used by the application, the actual worker is not responsible for storing the results in SQL. Instead, it returns results via arq, which temporarily puts them in Redis then uses on_job_start and after_job_end to notify a different queue. Those results are recovered and stored in the database by separate a separate arq worker.

This function returns a class suitable for assigning to a module variable and referencing as the argument to the arq command-line tool to start the worker.

Parameters:

logger (BoundLogger) – Logger to use for messages.
check_schema (bool, default: False) – Whether to check the database schema version with Alembic on startup.
alembic_config_path (Path, default: PosixPath('alembic.ini')) – When checking the schema, use this path to the Alembic configuration.

Return type:

WorkerSettings

async initialize_fastapi(logger=None, *, check_schema=False, alembic_config_path=PosixPath('alembic.ini'))¶

Initialize the UWS subsystem for FastAPI applications.

This must be called before any UWS routes are accessed, normally from the lifespan function of the FastAPI application.

Parameters:

logger (BoundLogger | None, default: None) – Logger to use to report any problems.
check_schema (bool, default: False) – If True, check whether the database schema for the UWS database is up to date using Alembic.
alembic_config_path (Path, default: PosixPath('alembic.ini')) – When checking the schema, use this path to the Alembic configuration.

Raises:

DatabaseSchemaError – Raised if the UWS database schema is out of date.

Return type:

None

async initialize_uws_database(logger, *, reset=False, use_alembic=False, alembic_config_path=PosixPath('alembic.ini'))¶

Initialize the UWS database.

Parameters:

logger (BoundLogger) – Logger to use.
reset (bool, default: False) – If True, also delete all data in the database.
use_alembic (bool, default: False) – Whether to stamp the UWS database with Alembic.
alembic_config_path (Path, default: PosixPath('alembic.ini')) – When stamping the database, use this path to the Alembic configuration.

Return type:

None

install_error_handlers(app)¶

Install error handlers that follow DALI and UWS conventions.

This method must be called during application setup for any FastAPI app using the UWS layer for correct error message handling. This will change the error response for all parameter validation errors from FastAPI.

Currently these error handlers return text/plain errors. VOTable errors may be a better choice, but revision 1.0 of the SODA standard only allows text/plain errors for sync routes.

Parameters:: app (FastAPI)
Return type:: None

install_handlers(router)¶

Install the route handlers for the service.

This method will always install a POST handler at the root of the router that creates an async job, and handlers under /jobs that implement the UWS protocol for managing those jobs. If sync_post_route is set in the UWSConfig that this application was configured with, a POST handler for /sync to create a sync job will be added. If sync_get_route is set, a GET handler for /sync to create a sync job will be added.

Parameters:: router (APIRouter)
Return type:: None

install_middleware(app)¶

Install FastAPI middleware needed by UWS.

UWS unfortunately requires that the key portion of query parameters be case-insensitive, so UWS FastAPI applications need to add custom middleware to lowercase query parameter keys. This method does that.

Parameters:: app (FastAPI) – FastAPI app.
Return type:: None

async is_schema_current(logger=None, config_path=PosixPath('alembic.ini'))¶

Check that the database schema is current using Alembic.

Parameters:

logger (BoundLogger | None, default: None) – Logger to use to report any problems.
config_path (Path, default: PosixPath('alembic.ini')) – Path to the Alembic configuration.

Return type:

bool

override_arq_queue(arq_queue)¶

Change the arq used by the FastAPI route handlers.

This method is probably only useful for the test suite.

Parameters:: arq_queue (ArqQueue) – New arq queue.
Return type:: None

async shutdown_fastapi()¶

Shut down the UWS subsystem for FastAPI applications.

This should be called during application shutdown, normally from the lifespan function of the FastAPI application.

Return type:: None