Data Servces

Base DataService Class

tom_dataservices.dataservices.get_data_service_classes()

Imports the Dataservice class from relevant apps and generates a list of data service names.

Each dataservice class should be contained in a list of dictionaries in an app’s apps.py dataservices method. Each dataservice dictionary should contain a ‘class’ key with the dot separated path to the dataservice class (typically an extension of DataService).

FOR EXAMPLE: [{‘class’: ‘path.to.dataservice.class’}]

tom_dataservices.dataservices.get_data_service_class(name)

Gets the specific dataservice class for a given dataservice name.

Returns:

Broker class

Return type:

class

exception tom_dataservices.dataservices.QueryServiceError

Represents a higher level error when an underlying service or client library fails.

class tom_dataservices.dataservices.DataService(query_parameters=None, *args, **kwargs)

Base class for all Data Services. Data Services are classes that are responsible for querying external services and returning data.

abstract query_service(query_parameters, **kwargs)

Takes in the serialized data from the query form and actually submits the query to the service

pre_query_validation(query_parameters)

Same thing as query_service, but a dry run

build_query_parameters(parameters, **kwargs)

Builds the query parameters from the form data

build_headers(*args, **kwargs)

Builds the headers for the query

classmethod get_form_class()

Returns the full form class for querying this service

classmethod configuration() → dict

Returns the configuration dictionary for this service

classmethod get_configuration(config_type=None, value=None, **kwargs)

Get all of the configuration or specific configuration values associated with this dataservice.

Syntax:

get_configuration([config_type], [value])

Parameters:

• config_type – The type of configuration to return. If None, returns all configurations.

• value – The default value to return if configuration not found.

Returns:

A list of available configurations, or a requested configuration, or if not found, the default value.

classmethod get_credentials(**kwargs)

Returns the credentials for this service. Checks the configuration for an api_key by default.

classmethod urls(**kwargs) → dict

Dictionary of URLS for the DataService

classmethod get_urls(url_type=None, value=None, **kwargs)

Get all urls or a specific url associated with the dataservice.

Syntax:

get_urls([url_type], [value])

Parameters:

• url_type – The type of URL to return. If None, returns all available url types.

• value – The default value to return if the requested url is not found.

Returns:

A list of available uls, or a requested url, or if not found, the default value.

get_additional_context_data()

Called by the View.get_context_data() and adds DataService context to the View’s context dictionary

get_success_message(**kwargs)

Returns a success message to display in the UI after making the query.

get_simple_form_partial()

Returns a path to a simplified bare-minimum partial form that can be used to access the DataService.

get_advanced_form_partial()

Returns a path to a full or advanced partial form that can be used to access the DataService.

query_forced_photometry(query_parameters, **kwargs)

Set up and run a specialized query for a DataService’s forced photometry service.

query_photometry(query_parameters, **kwargs)

Set up and run a specialized query for a DataService’s photometry service.

query_spectroscopy(query_parameters, **kwargs)

Set up and run a specialized query for a DataService’s spectroscopy service.

query_reduced_data(query_parameters, **kwargs)

Set up and run a specialized query to retrieve Reduced Datums from a Data Service

query_aliases(query_parameters, **kwargs) → List

Set up and run a specialized query for retrieving target names from a DataService. This method will usually call query_service() and translate the results from the dataservice into a list of target names.

Parameters:

query_parameters – This is the output from build_query_parameters()

Returns:

A list of target names

Return type:

List

query_targets(query_parameters, **kwargs) → List[dict]

Set up and run a specialized query for retrieving targets from a DataService. This method will usually call query_service() and translate the results from the dataservice into a list of dictionaries describing the returned targets.

Parameters:

query_parameters – This is the output from build_query_parameters()

Returns:

A list of dictionaries describing the resulting targets. Include ‘reduced_datums’ and/or ‘aliases’ as

keys in this dictionary to add associated data and alternate names without perfoming additional queries. :rtype: List[dict]

to_data_product(query_results=None, **kwargs)

Upper level function to create a new DataProduct from the query results Can take either new query results, or use stored results form a recent query_service() :param query_results: Query results from the DataService :returns: DataProduct object

create_data_product_from_query(query_results=None, **kwargs)

Create a new DataProduct from the query results

to_reduced_datums(target, data_results=None, **kwargs)

Upper level function to create a new ReducedDatum from the query results This method is not intended to be extended. This method passes the output of query_reduced_data() to create_reduced_datums_from_query() :param target: Target object to associate with the ReducedDatum :param data_results: Query results from the DataService storing observation data. This should be a dictionary with each key being a data_type (i.e. Photometry, Spectroscopy, etc.)

create_reduced_datums_from_query(target, data=None, data_type=None, **kwargs)

Create and save new reduced_datums of the appropriate data_type from the query results

to_target(target_result=None, **kwargs) → Tuple[dict, dict, dict]

Upper level function to create a new target from the query results This method is not intended to be extended. This method passes a single instance of the output of query_targets() to create_target_from_query(), create_target_extras_from_query() and create_aliases_from_query(). Intended usage: Call to_target on each element of the target_data list of dictionaries from query_target. (see views.py::CreateTargetFromQueryView) :param target_results: Dictionary containing target information. :returns: Target object, dictionary of target_extras, and list of aliases

create_target_from_query(target_result, **kwargs)

Create a new target from a single instance of the target results. :param target_result: dictionary describing target details based on query result :returns: target object :rtype: Target

create_target_extras_from_query(query_results, **kwargs)

Create a new target from the query results :returns: dict of extras to be added to a new Target :rtype: dict

create_aliases_from_query(alias_results: List, **kwargs) → List

Create a new target from the query results This method should be over ridden with a method that creates a list of TargetName objects: TargetName(name=alias) that will be saved as part of the Target.save(extras=extras, names=aliases) call. :param query_result: list of dictionaries describing target details based on query result :returns: list of TargetName objects to be added to a new Target :rtype: list

TNS

class tom_dataservices.data_services.tns.TNSDataService(query_parameters=None, *args, **kwargs)

The TNSDataService is the interface to the Transient Name Server. For information regarding the TNS, please see https://www.wis-tns.org/

Requires the following configuration in settings.py:

DATA_Services = {
    'TNS': {
        'api_key': os.getenv('TNS_API_KEY', 'DO NOT COMMIT API TOKENS TO GIT!'),
        'bot_id': os.getenv('TNS_BOT_ID ', 'My TNS Bot ID'),
        'bot_name': os.getenv('TNS_BOT_NAME', 'BestTOMBot'),
        'base_url': 'https://sandbox.wis-tns.org/',  # Note this is the Sandbox URL
        'group_name': os.getenv('TNS_GROUP_NAME', 'BestTOMGroup'),
    },
}

get_simple_form_partial()

Returns a path to a simplified bare-minimum partial form that can be used to access the DataService.

classmethod urls(**kwargs) → dict

Dictionary of URLS for the TNS API.

build_query_parameters(parameters, **kwargs)

Args:

parameters: dictionary containing days_ago (str), min_date (str) and either:

• Right Ascension, declination (can be deg, deg or h:m:s, d:m:s) of the target,

  and search radius and search radius unit (“arcmin”, “arcsec”, or “deg”), or

• TNS name without the prefix (eg. 2024aa instead of AT2024aa)

Returns:

json containing response from TNS including TNS name and prefix.

query_targets(query_parameters)

Set up and run a specialized query for retrieving targets from a DataService.

create_target_from_query(target_results, **kwargs)

Returns a Target instance for an object defined by a query result,

Returns:

target object

Return type:

Target