"""
XPQLT Database Download Utilities.
This module provides functions to download and cache observation databases
from the XPQLT web service (https://xpqlt.com). The databases contain
metadata for IXPE observations including file locations and observation
parameters.
"""
import os
import urllib.request
from ixpepy import IXPEPY_ROOT
# XPQLT API endpoints
db_source_obsid_url = 'https://xpqlt.com/api/source_obsid/?format=json'
db_obsid_url = 'https://xpqlt.com/api/obsid/?format=json'
[docs]
def download_db(url, file_path, update=True):
"""
Download a database file from a URL if needed.
Parameters
----------
url : str
URL of the database to download
file_path : str
Local file path where the database should be saved
update : bool, optional
If True, download even if file exists. If False, only download
if file doesn't exist. Default is True.
Returns
-------
str
Path to the downloaded database file
Notes
-----
This function will create the directory structure if it doesn't exist.
"""
if update == True or not os.path.exists(file_path):
urllib.request.urlretrieve(url, file_path)
return file_path
[docs]
def download_obsid_db(file_path=None, update=True):
"""
Download the IXPE observation ID database from XPQLT.
This database contains metadata for all IXPE observations including
observation IDs, target names, file URLs, and observation parameters.
Parameters
----------
file_path : str, optional
Custom path to save the database. If None, saves to the default
location in the ixpepy package directory. Default is None.
update : bool, optional
If True, download even if file exists. If False, only download
if file doesn't exist. Default is True.
Returns
-------
str
Path to the downloaded database file
Examples
--------
>>> db_file = download_obsid_db()
>>> import json
>>> with open(db_file) as f:
... obsid_db = json.load(f)
"""
if file_path is None:
file_path = os.path.join(IXPEPY_ROOT, 'io', 'obsid.json')
return download_db(db_obsid_url, file_path, update)
[docs]
def download_source_obsid_db(file_path=None, update=True):
"""
Download the IXPE source-obsid mapping database from XPQLT.
This database maps astronomical source names to their corresponding
IXPE observation IDs, making it easy to find observations of specific
sources.
Parameters
----------
file_path : str, optional
Custom path to save the database. If None, saves to the default
location in the ixpepy package directory. Default is None.
update : bool, optional
If True, download even if file exists. If False, only download
if file doesn't exist. Default is True.
Returns
-------
str
Path to the downloaded database file
Examples
--------
>>> db_file = download_source_obsid_db()
>>> import json
>>> with open(db_file) as f:
... source_db = json.load(f)
"""
if file_path is None:
file_path = os.path.join(IXPEPY_ROOT, 'io', 'source_obsid.json')
return download_db(db_source_obsid_url, file_path, update)
if __name__ == "__main__":
# Download both databases when run as a script
download_obsid_db()
download_source_obsid_db()