Client#

Grad300Client#

class grad300_client.Grad300Client[source]#

Bases: object

Python client for the GRAD300 backend API.

Wraps the /api/v1 REST endpoints and returns results as astropy.table.Table (for listing/querying) or astropy.io.fits.HDUList / pathlib.Path (for downloads).

Authentication is handled automatically: supply either a token or a user + password pair and the client acquires a Bearer token on your behalf.

Examples

>>> from grad300_client import Grad300
>>> with Grad300(user="me@example.com", password="secret") as client:
...     table = client.query_source("Sun")

__init__(base_url=None, *, api_prefix=None, timeout=None, token=None, user=None, password=None, transport=None)[source]#

Initialise the client and optionally authenticate.

Parameters:

base_url (str | None, optional) – Root URL of the GRAD300 server. Defaults to base_url.
api_prefix (str | None, optional) – Path prefix for all API calls (for example /api/v1). Defaults to api_prefix.
timeout (float | None, optional) – HTTP timeout in seconds. Defaults to timeout.
token (str | None, optional) – Pre-obtained Bearer token. Mutually exclusive with user and password.
user (str | None, optional) – E-mail address used for username/password login.
password (str | None, optional) – Password for username/password login.
transport (httpx.BaseTransport | None, optional) – Custom HTTP transport, for example httpx.MockTransport in tests.

Raises:

ValueError – If both token and user/password are provided, or if only one of user/password is provided.

Return type:

None

property base_api_url: str#

Return the fully normalized API base URL.

Returns:: Base URL used by the underlying HTTP client.
Return type:: str

clear_token()[source]#

Remove the current Bearer token from the HTTP headers.

Return type:: None

close()[source]#

Close the underlying HTTP connection pool.

Return type:: None

download(record, *, destination_dir=None, overwrite=False)[source]#

Download the FITS file associated with a scan record.

The return type depends on the scan type and whether destination_dir is given:

TPI without destination_dir → astropy.table.Table
Other types without destination_dir → astropy.io.fits.HDUList
With destination_dir → pathlib.Path of the saved file

Parameters:

record (ScanRecord | Mapping[str, Any] | astropy.table.Row) – Scan record with id, scan_type and file_name.
destination_dir (str | pathlib.Path | None, optional) – Directory where the file is written. If None, data is returned in memory.
overwrite (bool, default=False) – Overwrite existing destination file.

Returns:

In-memory data or path to the saved file.

Return type:

DownloadResult

Raises:

FileExistsError – If destination exists and overwrite is False.

download_by_id(*, scan_type, scan_id, destination_dir=None, file_name=None, overwrite=False)[source]#

Download a scan by its database ID.

Parameters:

scan_type (ScanType | str) – Scan type of the target record.
scan_id (int) – Database identifier of the scan.
destination_dir (str | pathlib.Path | None, optional) – Directory where the file is written.
file_name (str | None, optional) – Override output filename when writing to disk.
overwrite (bool, default=False) – Overwrite an existing file.

Returns:

In-memory data or path to the saved file.

Return type:

DownloadResult

download_by_scan_name(scan_name, *, scan_type=None, destination_dir=None, overwrite=False)[source]#

Download a scan by its exact filename.

Queries the API for scan_name first and expects exactly one result with a matching file_name.

Parameters:

scan_name (str) – Exact filename of the scan.
scan_type (ScanType | str | None, optional) – Narrow search to a specific scan type.
destination_dir (str | pathlib.Path | None, optional) – Directory where the file is written.
overwrite (bool, default=False) – Overwrite an existing file.

Returns:

In-memory data or path to the saved file.

Return type:

DownloadResult

Raises:

LookupError – If zero or multiple scans match scan_name.

get_json(path, *, params=None)[source]#

Send a GET request and decode JSON payload.

Parameters:

path (str) – Path relative to base_api_url.
params (dict[str, Any] | None, optional) – Query-string parameters.

Returns:

Decoded JSON payload.

Return type:

Any

list(scan_type, *, offset=0, limit=None, source=None, scan_name=None, date_from=None, date_to=None)[source]#

Return a single page of scans as an astropy.table.Table.

Parameters:

scan_type (ScanType | str) – Scan type to list ("TPI", "Images", "Spectrum", or "OnOff").
offset (int, default=0) – Number of records to skip.
limit (int | None, optional) – Maximum number of records to return. Defaults to default_page_size.
source (str | None, optional) – Filter by source name.
scan_name (str | None, optional) – Filter by partial filename.
date_from (datetime | None, optional) – Lower bound for observation date (inclusive).
date_to (datetime | None, optional) – Upper bound for observation date (inclusive).

Returns:

One row per scan.

Return type:

astropy.table.Table

list_records(scan_type, *, offset=0, limit=None, source=None, scan_name=None, date_from=None, date_to=None)[source]#

Like list() but return structured Python records.

Parameters:

scan_type (ScanType | str) – Scan type to list.
offset (int, default=0) – Number of records to skip.
limit (int | None, optional) – Maximum number of records to return.
source (str | None, optional) – Filter by source name.
scan_name (str | None, optional) – Filter by partial filename.
date_from (datetime | None, optional) – Lower bound for observation date.
date_to (datetime | None, optional) – Upper bound for observation date.

Returns:

Structured scan records.

Return type:

list[ScanRecord]

login(email, password)[source]#

Authenticate with username and password.

Acquires a Bearer token from /login/access-token and stores it automatically. Subsequent requests are authenticated.

Parameters:

email (str) – User e-mail address.
password (str) – User password.

Returns:

Raw Bearer token.

Return type:

str

Raises:

grad300_client.Grad300Error – If the response does not include access_token.
grad300_client.AuthenticationError – If credentials are rejected by the server.

query(*, scan_type=None, source=None, scan_name=None, date_from=None, date_to=None, page_size=None, max_results=None)[source]#

Query scans across all pages with optional filters.

Iterates through paginated results until all matching records have been collected or max_results is reached. Client-side date and name filtering is applied as a safety net when the backend does not support those parameters.

Parameters:

scan_type (ScanType | str | None, optional) – Restrict to a single scan type. None queries all scan types.
source (str | None, optional) – Filter by source name.
scan_name (str | None, optional) – Filter by partial filename.
date_from (datetime | None, optional) – Lower bound for observation date (inclusive).
date_to (datetime | None, optional) – Upper bound for observation date (inclusive).
page_size (int | None, optional) – Records fetched per HTTP request. Defaults to default_page_size.
max_results (int | None, optional) – Stop after collecting this many records.

Returns:

One row per matching scan.

Return type:

astropy.table.Table

query_date_range(*, date_from=None, date_to=None, scan_type=None, page_size=None, max_results=None)[source]#

Query scans observed within a date range.

Convenience wrapper around query(). At least one of date_from or date_to should be provided.

Parameters:

date_from (datetime | None, optional) – Lower bound for observation date (inclusive).
date_to (datetime | None, optional) – Upper bound for observation date (inclusive).
scan_type (ScanType | str | None, optional) – Restrict to a single scan type.
page_size (int | None, optional) – Records per HTTP request.
max_results (int | None, optional) – Maximum number of records to return.

Returns:

One row per matching scan.

Return type:

astropy.table.Table

query_records(*, scan_type=None, source=None, scan_name=None, date_from=None, date_to=None, page_size=None, max_results=None)[source]#

Query scans across all pages and return structured records.

Parameters:

scan_type (ScanType | str | None, optional) – Restrict to a single scan type. None queries all scan types.
source (str | None, optional) – Filter by source name.
scan_name (str | None, optional) – Filter by partial filename.
date_from (datetime | None, optional) – Lower bound for observation date.
date_to (datetime | None, optional) – Upper bound for observation date.
page_size (int | None, optional) – Records fetched per HTTP request.
max_results (int | None, optional) – Stop after collecting this many records.

Returns:

Matching scan records.

Return type:

list[ScanRecord]

query_scan_name(scan_name, *, scan_type=None, page_size=None, max_results=None)[source]#

Query scans whose filename contains scan_name.

Convenience wrapper around query().

Parameters:

scan_name (str) – Partial filename fragment to search for.
scan_type (ScanType | str | None, optional) – Restrict to a single scan type.
page_size (int | None, optional) – Records per HTTP request.
max_results (int | None, optional) – Maximum number of records to return.

Returns:

One row per matching scan.

Return type:

astropy.table.Table

query_source(source, *, scan_type=None, page_size=None, max_results=None)[source]#

Query all scans for a given source name.

Convenience wrapper around query().

Parameters:

source (str) – Source name to search for.
scan_type (ScanType | str | None, optional) – Restrict to a single scan type.
page_size (int | None, optional) – Records per HTTP request.
max_results (int | None, optional) – Maximum number of records to return.

Returns:

One row per matching scan.

Return type:

astropy.table.Table

request(method, path, **kwargs)[source]#

Send a raw HTTP request to the GRAD300 API.

Parameters:

method (str) – HTTP method ("GET", "POST", …).
path (str) – Path relative to base_api_url.
**kwargs (Any) – Additional keyword arguments passed to httpx.Client.request.

Returns:

Raw response object.

Return type:

httpx.Response

set_token(token)[source]#

Set the Bearer token used for authenticated requests.

Parameters:: token (str) – A valid Bearer token.
Return type:: None

test_token()[source]#

Verify that the current token is valid.

Returns:: JSON payload returned by /login/test-token.
Return type:: dict[str, Any]
Raises:: grad300_client.AuthenticationError – If the token is missing or rejected.

Grad300 (alias)#

class grad300_client.Grad300[source]#

Bases: Grad300Client

Alias class for a compact astroquery-like import style.

Client#

Grad300Client#

Grad300 (alias)#

This Page