Record

class pyvo.dal.Record(results, index, *, session=None)

Bases: Mapping

one record from a DAL query result. The column values are accessible as dictionary items. It also provides special added functions for accessing the dataset the record corresponds to. Subclasses may provide additional functions for access to service type-specific data.

Methods Summary

cachedataset(*[, filename, dir, timeout, ...])	retrieve the dataset described by this record and write it out to a file with the given name.
get(key[, default, decode])	This method mimics the dict get method and adds a decode parameter to allow decoding of binary strings.
getbyucd(ucd[, default, decode])	return the column with the given ucd.
getbyutype(utype[, default, decode])	return the column with the given utype.
getdataformat()	return the mimetype of the dataset described by this record.
getdataobj()	return the appropriate data object suitable for the data content behind this record.
getdataset([timeout])	Get the dataset described by this record from the server.
getdataurl()	return the URL contained in the access URL column which can be used to retrieve the dataset described by this record.
make_dataset_filename(*[, dir, base, ext])	create a viable pathname in a given directory for saving the dataset available via getdataset().
suggest_dataset_basename()	return a default base filename that the dataset available via getdataset() can be saved as.
suggest_extension(*[, default])	returns a recommended filename extension for the dataset described by this record.

Methods Documentation

cachedataset(*, filename=None, dir='.', timeout=None, bufsize=None)

retrieve the dataset described by this record and write it out to a file with the given name. If the file already exists, it will be over-written.

Parameters:

filenamestr

the name of the file to write dataset to. If the value represents a relative path, it will be taken to be relative to the value of the dir parameter. If None, a default name is attempted based on the record title and format.

dirstr

the directory to write the file into. This value will be ignored if filename is an absolute path.

timeoutint

the time in seconds to allow for a successful connection with server before failing with an IOError (specifically, socket.timeout) exception

bufsizeint

a buffer size in bytes for copying the data to disk (default: 0.5 MB)

Raises:

KeyError

if no datast access URL is included in the record

URLError

if the dataset access URL is invalid

HTTPError

if an HTTP error occurs while accessing the dataset

socket.timeout

if the timeout is exceeded before a connection is established. (note: subclass of IOError)

IOError

if an error occurs while writing out the dataset

get(key, default=None, decode=False)

This method mimics the dict get method and adds a decode parameter to allow decoding of binary strings.

getbyucd(ucd, default=None, decode=False)

return the column with the given ucd.

getbyutype(utype, default=None, decode=False)

return the column with the given utype.

Raises:

KeyError

if theres no column with the given utype.

getdataformat()

return the mimetype of the dataset described by this record.

getdataobj()

return the appropriate data object suitable for the data content behind this record.

getdataset(timeout=None)

Get the dataset described by this record from the server.

Parameters:

timeoutfloat

the time in seconds to allow for a successful connection with server before failing with an IOError (specifically, socket.timeout) exception

Returns:

A file-like object which may be read to retrieve the referenced

dataset.

Raises:

KeyError

if no datast access URL is included in the record

URLError

if the dataset access URL is invalid (note: subclass of IOError)

HTTPError

if an HTTP error occurs while accessing the dataset (note: subclass of IOError)

socket.timeout

if the timeout is exceeded before a connection is established. (note: subclass of IOError)

IOError

if some other error occurs while establishing the data stream.

getdataurl()

return the URL contained in the access URL column which can be used to retrieve the dataset described by this record. None is returned if no such column exists.

make_dataset_filename(*, dir='.', base=None, ext=None)

create a viable pathname in a given directory for saving the dataset available via getdataset(). The pathname that is returned is guaranteed not to already exist (under single-threaded conditions).

This implementation will first try combining the base name with the file extension (with a dot). If this file already exists in the directory, a name that appends an integer suffix (“-#”) to the base before joining with the extension will be tried. The integer will be incremented until a non-existent filename is created.

Parameters:

dirstr

the directory to save the dataset under. This must already exist.

basestr

a basename to use to as the base of the filename. If None, the result of suggest_dataset_basename() will be used.

extstr

the filename extension to use. If None, the result of suggest_extension() will be used.

suggest_dataset_basename()

return a default base filename that the dataset available via getdataset() can be saved as. This function is specialized for a particular service type this record originates from so that it can be used by cachedataset() via make_dataset_filename().

suggest_extension(*, default=None)

returns a recommended filename extension for the dataset described by this record. Typically, this would look at the column describing the format and choose an extension accordingly. This function is specialized for a particular service type this record originates from so that it can be used by cachedataset() via make_dataset_filename().