RSPDiscovery#

class lsst.rsp.RSPDiscovery(dataset, *, discovery_url=None, token=None)#

Bases: object

Look up Rubin Science Platform services and construct clients.

Provides an API to discover the URLs of services, build clients that send appropriate authentication credentials to service requests, and build PyVO clients for services where appropriate.

This class may be used either inside Nublado notebooks, in which case service discovery and authentication is automatic, or outside of the Rubin Science Platform. In the latter case, the caller will have to provide service discovery and authentication credentials for the RSP instance they wish to access.

Parameters:

dataset (str) – Label for the dataset that will be accessed. Create a separate instance of RSPDiscovery for each dataset you wish to use.
discovery_url (str | None, default: None) – Base URL to discovery services. This should not be provided when running inside Nublado. It allows the class to be used outside of Nublado and pointed to a particular instance of the Rubin Science Platform. If given, the URL should be the base URL for the Repertoire service.
token (str | None, default: None) – Authentication token to use. This parameter can and should be omitted when called from inside a Nublado notebook.

Raises:

DiscoveryNotAvailableError – Raised if no service discovery information is available.
InvalidDiscoveryError – Raised if the discovery information has an invalid syntax.
TokenNotAvailableError – Raised if there is no Gafaelfawr token available.
UnknownDatasetError – Raised if this dataset is not present in the environment.

Methods Summary

`get_datalink_results`(result)	Return the DataLink part of an ObsCore record.
`get_service_url`(service, *[, version])	Get the API URL for a service.
`get_session`()	Get a requests session that sends a token only to service URLs.
`get_sia_client`()	Get a configured PyVO SIAv2 client for this dataset.
`get_tap_client`()	Get a configured PyVO TAP client for this dataset's TAP service.
`get_tap_job`(url)	Retrieve a TAP UWS job with appropriate authentication.
`get_token`()	Return the Nublado access token when inside Nublado.
`list_datasets`(*[, discovery_url])	List the available datasets.

Methods Documentation

get_datalink_results(result)#

Return the DataLink part of an ObsCore record.

This is the record returned by, for example, an SIAv2 query. The resulting object can be used to follow DataLink pointers.

Parameters:: result (ObsCoreRecord) – Result record.
Returns:: Results object that can be used to follow DataLink pointers.
Return type:: DatalinkResults

get_service_url(service, *, version=None)#

Get the API URL for a service.

Parameters:

service (str) – Name of the service.
version (str | None, default: None) – Optional API version. If given, get the specific base URL of that version of the API instead of the base URL of the service as a whole.

Returns:

Base URL for the service API.

Return type:

str

Raises:

UnknownServiceError – Raised if this service is not provided for this dataset.

get_session()#

Get a requests session that sends a token only to service URLs.

The resulting requests session can be used to make any HTTP requests, and will include the bearer token in the Authorization header only if the request goes to a URL under one of the base service URLs.

Returns:: Requests session configured to send an authentication token if the request is to an RSP service.
Return type:: requests.Session

get_sia_client()#

Get a configured PyVO SIAv2 client for this dataset.

Returns:: PyVO SIAv2 client configured with an appropriate base URL and authentication credentials.
Return type:: SIA2Service
Raises:: UnknownServiceError – Raised if there is no SIA2 service for this dataset.

get_tap_client()#

Get a configured PyVO TAP client for this dataset’s TAP service.

Returns:: PyVO TAP client configured with an appropriate base URL and authentication credentials.
Return type:: TAPService
Raises:: UnknownServiceError – Raised if there is no TAP service for this dataset.

get_tap_job(url)#

Retrieve a TAP UWS job with appropriate authentication.

This can be used to retrieve the results of a previous TAP query if one has the URL to the UWS job in the TAP server.

Parameters:: url (str) – URL of the TAP job. In PyVO, this is the value of job.url after successfully submitting an async TAP job using the submit_job method.
Returns:: Object representing the underlying job, which can be used to retrieve its results or other metadata.
Return type:: AsyncTAPJob

classmethod get_token()#

Return the Nublado access token when inside Nublado.

This is provided as a way to get the Nublado token for callers that want to use a different HTTP library or other Nublado tools that require the token. Where possible, prefer using the regular methods on RSPDiscovery that return pre-configured clients or HTTP sessions instead of using this method.

This method can only be used from a Nublado notebook. To get a token that can be used outside of the Rubin Science Platform, see the RSP documentation.

Returns:: Token to use to authenticate to RSP services. This token should only be used from inside the Nublado notebook where this method was called.
Return type:: str
Raises:: TokenNotAvailableError – Raised if there is no Gafaelfawr token available.

classmethod list_datasets(*, discovery_url=None)#

List the available datasets.

These will be the valid arguments for the dataset parameter to the RESPDiscovery constructor.

Parameters:

discovery_url (str | None, default: None) – Base URL to discovery services. This should not be provided when running inside Nublado. It allows the class to be used outside of Nublado and pointed to a particular instance of the Rubin Science Platform. If given, the URL should be the base URL for the Repertoire service.

Returns:

List of valid dataset labels.

Return type:

list of str

Raises:

DiscoveryNotAvailableError – Raised if no service discovery information is available.
InvalidDiscoveryError – Raised if the discovery information has an invalid syntax.