UWS API

Models

UWS Job Schema using Pydantic-XML models

class vo_models.uws.models.Parameter(**data)[source]

A UWS Job parameter

Parameters:
  • value (str | int | float | bool | bytes | None) – (content) - the value of the parameter.

  • by_reference (bool | None) – (attr) - If this attribute is true then the content of the parameter represents a URL to retrieve the actual parameter value.

  • id (str) – (attr) - The identifier of the parameter.

  • is_post (bool | None) – (attr) - Undocumented.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

vo_models.uws.models.MultiValuedParameter

Type for a multi-valued parameter.

This type must be used instead of list[Parameter] for parameters that may take multiple values. The resulting model attribute will be a list of Parameter objects with the same id.

alias of Annotated[list[Parameter], BeforeValidator(func=~vo_models.uws.models., json_schema_input_type=PydanticUndefined)]

class vo_models.uws.models.Parameters(**data)[source]

An abstract holder of UWS parameters.

The input parameters to the job. For simple key/value pair parameters, there must be one model field per key, with a type of either Parameter or MultiValuedParameter depending on whether it can be repeated. If the job description language does not naturally have parameters, then this model should contain one element, which is the content of the original POST that created the job.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class vo_models.uws.models.ErrorSummary(**data)[source]

A short summary of an error

A fuller representation of the error may be retrieved from /{jobs}/{job-id}/error

Parameters:
  • message (str) – (element) - A short description of the error.

  • type (ErrorType) – (attr) - Characterization of the type of the error

  • has_detail (bool) – (attr) - If true then there is a more detailed error message available at /{jobs}/{job-id}/error

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class vo_models.uws.models.ResultReference(**data)[source]

A reference to a UWS result.

Parameters:
  • id (str) – (attr) - The identifier of the result.

  • type (XlinkType | None) – (attr) - The xlink type of the result.

  • href (str | None) – (attr) - The link to the result.

  • size (int | None) – (attr) - The size of the result in bytes.

  • mime_type (str | None) – (attr) - The MIME type of the result.

  • any_attrs (Dict[str, str] | None) – (attr) - Any other attributes of the result.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class vo_models.uws.models.Results(**data)[source]

The element returned for /{jobs}/{job-id}/results

Parameters:

results (list[ResultReference] | None) – (element) A list of references to UWS results.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class vo_models.uws.models.ShortJobDescription(**data)[source]

A short description of a job.

Parameters:
  • phase (ExecutionPhase) – (element) - The execution phase - returned at /{jobs}/{job-id}/phase

  • run_id (str | None) – (element) - A client supplied identifier - the UWS system does nothing other than to return it as part of the description of the job

  • owner_id (str | None) – (element) - The owner (creator) of the job - this should be expressed as a string that can be parsed in accordance with IVOA security standards.

  • creation_time (UTCTimestamp | None) – (element) - The instant at which the job was created.

  • job_id (str) – (attr) - The identifier for the job.

  • type (XlinkType | None) – (attr) - The xlink reference type of the job.

  • href (str | None) – (attr) - The link to the job.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class vo_models.uws.models.Jobs(**data)[source]

The list of job references returned at /(jobs)

The list presented may be affected by the current security context and may be filtered

Parameters:
  • jobref (list[ShortJobDescription] | None) – (element) a list of UWS Jobs.

  • version (UWSVersion | None) –

    (attr) - The version of the UWS standard that the server complies with.

    Note that this attribute is actually required by the 1.1 specification - however remains optional in the schema for backwards compatibility. It will be formally required in the next major revision.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class vo_models.uws.models.JobSummary(**data)[source]

The complete representation of the state of a job

Parameters:
  • job_id (str) – (element) - The identifier for the job.

  • run_id (str | None) – (element) - This is a client supplied identifier - the UWS system does nothing other than to return it as part of the description of the job

  • owner_id (str | None) –

    (element) - The owner (creator) of the job - this should be expressed as a string that can be parsed in accordance with IVOA security standards.

    If there was no authenticated job creator then this should be set to NULL.

  • phase (ExecutionPhase) – (element) - The execution phase.

  • quote (UTCTimestamp | None) – (element) - A Quote predicts when the job is likely to complete.

  • creation_time (UTCTimestamp | None) –

    (element) - The instant at which the job was created.

    Note that the version 1.1 of the specification requires that this element be present. It is optional only in versions 1.x of the schema for backwards compatibility. 2.0+ versions of the schema will make this formally mandatory in an XML sense.

  • start_time (UTCTimestamp | None) – (element) - The instant at which the job started execution.

  • end_time (UTCTimestamp | None) – (element) - The instant at which the job finished execution.

  • execution_duration (int | None) –

    (element) - The duration (in seconds) for which the job should be allowed to run.

    A value of 0 is intended to mean unlimited.

  • destruction (UTCTimestamp | None) – (element) - The time at which the whole job + records + results will be destroyed.

  • parameters (ParametersType | None) – (element) - The parameters to the job (where appropriate)

  • results (Results | None) – (element) - The results for the job

  • error_summary (ErrorSummary | None) – (element) - A short summary of an error

  • job_info (list[str] | None) – (element) - This is arbitrary information that can be added to the job description by the UWS implementation.

  • version (UWSVersion | None) –

    (attr) - The version of the UWS standard that the server complies with.

    Note that this attribute is actually required by the 1.1 specification - however remains optional in the schema for backwards compatibility. It will be formally required in the next major revision.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

Simple Types

UWS Simple Types

class vo_models.uws.types.ErrorType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Enum for error types.

TRANSIENT = 'transient'

The error is transient and the job may be rerun.

FATAL = 'fatal'

The error is fatal and the job may not be rerun.

class vo_models.uws.types.UWSVersion(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

The version of the UWS standard that the server complies with.

V1_1 = '1.1'

The server complies with UWS 1.1.

V1_0 = '1.0'

The server complies with UWS 1.0.

class vo_models.uws.types.ExecutionPhase(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Enumeration of possible phases of job execution.

PENDING = 'PENDING'

The first phase a job is entered into - this is where a job is being set up but no request to run has occurred.

QUEUED = 'QUEUED'

A job has been accepted for execution but is waiting in a queue.

EXECUTING = 'EXECUTING'

A job is running

COMPLETED = 'COMPLETED'

A job has completed successfully.

ERROR = 'ERROR'

Some form of error has occurred.

UNKNOWN = 'UNKNOWN'

The job is in an unknown state.

HELD = 'HELD'

The job is HELD pending execution and will not automatically be executed. Can occur after a PHASE=RUN request has been made (cf PENDING).

SUSPENDED = 'SUSPENDED'

The job has been suspended by the system during execution.

ABORTED = 'ABORTED'

The job has been aborted, either by user request or by the server because of lack or overuse of resources.

ARCHIVED = 'ARCHIVED'

The job has been archived by the server at destruction time. An archived job may have deleted the results to reclaim resources, but must have job metadata preserved. This is an alternative that the server may choose in contrast to completely destroying all record of the job.