AsyncJob

When do I need this? Most queries return in a few seconds and you will never touch this class. Use it when a query is large enough (multi-year pulls, very wide cone searches) that the synchronous TAP endpoint would time out before returning. In that case, call submit_async() on an archive object instead of a query_* method; it hands you back an AsyncJob handle immediately. You can then poll job.phase, call job.wait() to block until the server finishes, and collect the full astropy.table.Table with job.result(). See the async example in Quickstart.

class nexsci_rv.async_job.AsyncJob(status_url, session, *, output_format='votable', conf=None)

Bases: object

Handle to an IVOA async TAP job.

Parameters:

  • status_url (str) – Full URL of the job’s status resource (returned by the TAP server on submit).

  • session (requests.Session) – HTTP session to use for polling and result fetches; supplied by the originating Archive.

  • output_format (OutputFormat) – Format requested when the job was submitted; needed to parse result() correctly.

  • conf (Conf | None) – Process configuration.

property status_url: str

Full URL of the job’s status resource.

property job_id: str

Server-assigned job identifier.

property phase: Literal['pending', 'queued', 'executing', 'completed', 'error', 'aborted']

Current phase as last seen by refresh().

property result_url: str | None

URL of the completed result resource (None until completed).

property error: str | None

Server-side error message if the job is in the error phase.

property times: dict[str, datetime]

Map of startTime / endTime / destruction / executionDuration.

Only the keys present in the server’s UWS response are populated.

property is_terminal: bool

True if the job is in completed, error, or aborted.

refresh()

Poll the status URL once and update local state.

Return type:

None

wait(*, timeout=None, poll_interval=5.0)

Block until the job reaches a terminal phase or timeout elapses.

Raises:
Parameters:
Return type:

None

result()

Fetch and parse the result table. Job must be completed.

Return type:

Table

abort()

Request that the server abort the job.

Return type:

None