gavo.votable.tapquery module

An interface to querying TAP servers (i.e., a TAP client).

This is deprecated. Use pyvo.dal.tap instead.

class gavo.votable.tapquery.ADQLEndpoint(endpointURL)

Bases: gavo.votable.tapquery._WithEndpoint

A facade for an ADQL endpoint.

This is only needed for inspecting server metadata (i.e., in general only for rather fancy applications).

property available

returns True, False, or None (undecidable).

None is returned when /availability gives a 404 (which is legal) or the returned document doesn’t parse.

property capabilities

returns a dictionary containing some meta info on the remote service.

Keys to look for include title, identifier, contact (the mail address), and referenceURL.

If the remote server doesn’t return capabilities as expected, an empty dict is returned.

createJob(query, lang='ADQL-2.0', userParams={})

property tables

returns a sequence of table definitions for the tables accessible through this service.

The table definitions come as gavo.votable.Table instances.

class gavo.votable.tapquery.ADQLSyncJob(endpointURL, query=None, jobId=None, lang='ADQL', userParams={}, timeout=None)

Bases: gavo.votable.tapquery._WithEndpoint

A facade for a synchronous TAP Job.

This really is just a very glorified urllib.urlopen. Maybe some superficial parallels to ADQLTAPJob are useful.

You can construct it, add uploads, and then start or run the thing. Methods that make no sense at all for sync jobs (“phase”) silently return some more or less sensible fakes.

abort()

does nothing.

You could argue that this could come from a different thread and we could try to interrupt the ongoing request. Well, if you want it, try it yourself or ask the author.

addUpload(name, data)

property allResults

delete(usePOST=None)

getErrorFromServer()

property info

openResult(simple=True)

property owner

property parameters

property phase

postToService(params)

property quote

raiseIfError()

run(pollInterval=None)

setParameter(key, value)

start()

waitForPhases(phases, pollInterval=None, increment=None, giveUpAfter=None)

class gavo.votable.tapquery.ADQLTAPJob(endpointURL, query=None, jobId=None, lang='ADQL', userParams={}, timeout=None)

Bases: gavo.votable.tapquery._WithEndpoint

A facade for an ADQL-based async TAP job.

Construct it with the URL of the async endpoint and a query.

Alternatively, you can give the endpoint URL and a jobId as a keyword parameter. This only makes sense if the service has handed out the jobId before (e.g., when a different program takes up handling of a job started before).

See adql.html for details.

abort()

asks the remote side to abort the job.

addUpload(name, data)

adds uploaded tables, either from a file or as a remote URL.

You should not try to change UPLOAD yourself (e.g., using setParameter).

Data is either a string (i.e. a URI) or a file-like object (an upload).

property allResults

returns a list of UWSResult instances.

delete(usePOST=False)

removes the job on the remote side.

usePOST=True can be used for servers that do not support the DELETE HTTP method (a.k.a. “are broken”).

property destruction

property executionDuration

getErrorFromServer()

returns the error message the server gives, verbatim.

getResultURL(simple=True)

returns the URL of the ADQL result table.

property info

returns a dictionary of much job-related information.

makeJobURL(jobPath)

openResult(simple=True)

returns a file-like object you can read the default TAP result off.

To have the embedded VOTable returned, say votable.load(job.openResult()).

If you pass simple=False, the URL will be taken from the service’s result list (the first one given there). Otherwise (the default), results/result is used.

property owner

returns the owner of the job.

property parameters

returns a dictionary mapping passed parameters to server-provided string representations.

To set a parameter, use the setParameter function. Changing the dictionary returned here will have no effect.

property phase

returns the phase the job is in according to the server.

property quote

returns the estimate the server gives for the run time of the job.

raiseIfError()

raises an appropriate error message if job has thrown an error or has been aborted.

run(pollInterval=1)

runs the job and waits until it has finished.

The function raises an exception with an error message gleaned from the server.

setParameter(key, value)

start()

asks the remote side to start the job.

waitForPhases(phases, pollInterval=1, increment=1.189207115002721, giveUpAfter=None)

waits for the job’s phase to become one of the set phases.

This method polls. Initially, it does increases poll times exponentially with increment until it queries every two minutes.

The magic number in increment is 2**(1/4.).

giveUpAfter, if given, is the number of iterations this method will do. If none of the desired phases have been found until then, raise a ProtocolError.

exception gavo.votable.tapquery.Error(msg='', hint=None)

Bases: gavo.utils.excs.Error

The base class for all TAP-related exceptions.

class gavo.votable.tapquery.LocalResult(data, id, type)

Bases: object

exception gavo.votable.tapquery.NetworkError(msg='', hint=None)

Bases: gavo.votable.tapquery.Error

is raised when a generic network error happens (can’t connect,…)

exception gavo.votable.tapquery.ProtocolError(msg='', hint=None)

Bases: gavo.votable.tapquery.Error

is raised when the remote server violated the local assumptions.

exception gavo.votable.tapquery.RemoteAbort

Bases: gavo.votable.tapquery.Error

is raised by certain check functions when the remote side has aborted the job.

exception gavo.votable.tapquery.RemoteError(remoteMessage)

Bases: gavo.votable.tapquery.Error

is raised when the remote size signals an error.

The content of the remote error document can be retrieved in the remoteMessage attribute.

class gavo.votable.tapquery.UWSResult(href, id=None, type=None)

Bases: object

a container type for a result returned by an UWS service.

It exposes id, href, and type attributes.

exception gavo.votable.tapquery.WrongStatus(msg, foundStatus, payload, hint=None)

Bases: gavo.votable.tapquery.ProtocolError

is raised when request detects the server returned an invalid status.

These are constructed with the status returned (available as foundStatus) data payload of the response (available as payload).

gavo.votable.tapquery.request(scheme, host, path, data='', customHeaders={}, method='GET', expectedStatus=None, followRedirects=False, setResponse=None, timeout=None)

returns a HTTPResponse object for an HTTP request to path on host.

This function builds a new connection for every request.

On the returned object, you cannot use the read() method. Instead any data returned by the server is available in the data attribute.

data usually is a byte string, but you can also pass a dictionary which then will be serialized using _FormData above.

You can set followRedirects to True. This means that the 303 “See other” codes that many UWS action generate will be followed and the document at the other end will be obtained. For many operations this will lead to an error; only do this for slightly broken services.

In setResponse, you can pass in a callable that is called with the server response body as soon as it is in. This is for when you want to store the response even if request raises an error later on (i.e., for sync querying).