poiesis.api package¶

Subpackages¶

Submodules¶

poiesis.api.api_handlers module¶

poiesis.api.app module¶

Main module of the Poiesis API.

This module creates and configures the connexion app.

poiesis.api.app.create_app()[source]¶

Create the connexion app.

Returns:: The connexion app.
Return type:: AsyncApp

poiesis.api.asgi module¶

Configure Gunicorn to run the ASGI server.

Uses Uvicorn as the worker for the Poiesis API.

poiesis.api.asgi.import_app_from_string(import_string)[source]¶

Import an application object from a string.

Parameters:: import_string (str) – The import string in the format “<module>:<attribute>”.
Returns:: The imported attribute object.
Return type:: Any
Raises:: ImportError – If the import string is invalid or the attribute is not found.

poiesis.api.asgi.run()[source]¶: Run the Gunicorn server with the Poiesis app.

poiesis.api.constants module¶

Poiesis API constants.

class poiesis.api.constants.PoiesisApiConstants[source]¶

Bases: object

Constants used in the Poiesis API.

SPEC_GIT_HASH¶

The git hash of the OpenAPI specification that the API uses. This refers to the git commit from where the specification was copied and then modified if needed without changing the TES specification.

Note: The openAPI specification file is named as: “<SPEC_GIT_HASH>.openapi.yaml”, but it is not verbatim.

class Auth(AUTH='dummy')[source]¶

Bases: object

Constants used in the authentication.

AUTH¶: The authentication method.

AUTH: Literal['oidc', 'dummy'] = 'dummy'¶

class OIDC[source]¶

Bases: object

Constants used in the generic OpenID Connect client.

ISSUER¶: The OpenID Connect issuer URL.

CLIENT_ID¶: The OpenID Connect client identifier.

INTROSPECT_ENDPOINT¶: URL to validate tokens (optional).

CLIENT_ID = None¶

DISCOVERY_URL = 'None/.well-known/openid-configuration'¶

ISSUER = None¶

BASE_PATH = 'ga4gh/tes/v1'¶

class Gunicorn[source]¶

Bases: object

Constants used in the Gunicorn server.

PORT¶: The port on which the Gunicorn server listens.

WORKERS¶: The number of Gunicorn workers. Note: Defaults to the (number of CPU cores) * 2 + 1.

TIMEOUT¶: The timeout for the Gunicorn server.

HOST = '127.0.0.1'¶

PORT = '8000'¶

TIMEOUT = '120'¶

WORKERS = None¶

SPEC_GIT_HASH = 'c4c17c9'¶

TES_VERSION = 'v1.1.0'¶

class Task[source]¶

Bases: object

Constants used in the Task.

NAME = 'poiesis-tes-task'¶

poiesis.api.constants.get_poiesis_api_constants()[source]¶

Get the Poiesis API constants.

Returns:: The Poiesis API constants.
Return type:: PoiesisApiConstants

poiesis.api.exceptions module¶

Exceptions and their handlers for the platform backend.

exception poiesis.api.exceptions.APIException(message=None, details=None)[source]¶

Bases: Exception

Base exception for all API errors.

error_code = 'internal_error'¶

status_code = 500¶

to_dict()[source]¶

Convert exception to a dict representation.

Return type:: dict[str, Any]

exception poiesis.api.exceptions.BadRequestException(message=None, details=None)[source]¶

Bases: APIException

The request was invalid or cannot be served.

error_code = 'bad_request'¶

status_code = 400¶

exception poiesis.api.exceptions.DBException(message=None, details=None)[source]¶

Bases: APIException

An error occurred with the database.

error_code = 'db_error'¶

status_code = 500¶

exception poiesis.api.exceptions.InternalServerException(message=None, details=None)[source]¶

Bases: APIException

An unexpected condition was encountered.

error_code = 'internal_error'¶

status_code = 500¶

exception poiesis.api.exceptions.NotFoundException(message=None, details=None)[source]¶

Bases: APIException

The requested resource was not found.

error_code = 'not_found'¶

status_code = 404¶

exception poiesis.api.exceptions.UnauthorizedException(message=None, details=None)[source]¶

Bases: APIException

The request is unauthorized.

error_code = 'unauthorized'¶

status_code = 401¶

poiesis.api.exceptions.handle_api_exception(request, exc)[source]¶

Handler for our custom APIException hierarchy.

Return type:: ConnexionResponse

poiesis.api.exceptions.handle_unexpected_exception(request, exc)[source]¶

Handler for unexpected exceptions.

Return type:: ConnexionResponse

poiesis.api.models module¶

Models used by the API.

These are extensions of the models defined in the TES API specification.

class poiesis.api.models.MinimalTesTask(**data)[source]¶

Bases: BaseModel

Minimal task model.

id: str¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

state: str¶

class poiesis.api.models.TesListTasksFilter(**data)[source]¶

Bases: BaseModel

Filter for listing tasks.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name_prefix: str | None¶

state: TesState | None¶

tag_key: list[str] | None¶

tag_value: list[str] | None¶

view: TesView¶

class poiesis.api.models.TesView(*values)[source]¶

Bases: Enum

View of the task.

BASIC = 'BASIC'¶

FULL = 'FULL'¶

MINIMAL = 'MINIMAL'¶

poiesis.api.security module¶

Handles security for the API.

Entrypoint of token validations.

poiesis.api.security.validate_bearer_token(token)[source]¶

Validate bearer token.

This function validates a bearer token and returns the token info. This info is then added to the context for use in the API handlers.

Parameters:: token (str) – The bearer token.
Returns:: The token info.
Return type:: dict[str, Any]

poiesis.api.utils module¶

Utility functions for the API.

poiesis.api.utils.get_oidc_introspect_url()[source]¶

Get the OIDC introspect URL.

Returns:: The OIDC introspect URL.
Return type:: str

poiesis.api.utils.get_oidc_jwks_uri()[source]¶

Get the OIDC JWKS URI from the discovery document.

Return type:: str

poiesis.api.utils.pydantic_to_dict_response(func)[source]¶

Decorator that converts a Pydantic model return value to a dict.

This decorator is useful for API endpoints that return Pydantic models, automatically converting the model to a dictionary using the model_dump method.

Parameters:: func (Callable[..., Any]) – The function to decorate.
Return type:: Callable[..., Any]
Returns:: A wrapped function that converts Pydantic model returns to dictionaries.

Example

```python from pydantic import BaseModel

class User(BaseModel):: name: str age: int

@pydantic_to_dict_response def get_user() -> User:

return User(name=”John”, age=30)

# When called, get_user() will return a dict: {“name”: “John”, “age”: 30} ```

poiesis.api.utils.task_to_basic_task(task)[source]¶

Convert a task to a basic task.

Return type:: TesTask

Task message will include all fields EXCEPT:

tesTask.ExecutorLog.stdout
tesTask.ExecutorLog.stderr
tesInput.content
tesTaskLog.system_logs

poiesis.api.utils.task_to_minimal_task(task)[source]¶

Convert a task to a minimal task.

Return type:: TesTask

Note: The TES specification says that the task should only return the id, state.: However, the openAPI spec has the executors as required fields, so we need to return a minimal task.

Module contents¶

poiesis API.