API

Class hierarchy

Models are organised in a class hierarchy. At the base of the hierarchy is katsdpmodels.model.Model. It contains general metadata about the model, as well as a to_file() method to serialise the model to a file.

For each model type there is a subclass. For example, RFI masks are described by katsdpmodels.rfi_mask.RFIMask. These classes contain further properties and methods to interrogate the model. They are further subclassed into concrete classes that are specific to the format (such as RFIMaskRanges). To use a model it is generally not necessary to know about these concrete classes, and it is recommended that one works just with the abstract classes; this allows for new model formats to be defined and deployed without requiring changes to your code. When creating new models it is necessary to use the format-specific classes.

Fetching

The katsdpmodels.fetch sub-package provides modules for retrieving models over HTTP. For code using asyncio, use katsdpmodels.fetch.aiohttp; for synchronous code, use katsdpmodels.fetch.requests. These depend on the aiohttp and requests packages respectively. When installing katsdpmodels, specify the dependency as katsdpmodels[aiohttp] or katsdpmodels[requests] to pull in the appropriate dependencies.

Other than the use of coroutines, the two APIs are very similar, so only the synchronous API is described here.

The fetcher operates on URLs. It does not know how to construct an URL for a specific target or configuration. For retrieving models stored in a MeerKAT data set, refer to Telescope state integration for a convenience wrapper that extracts URLs encoded into the data set.

To fetch models one first creates a Fetcher. This wraps a requests.Session. Once it is no longer needed, it can be closed to release the OS resources. It can also be used as a context manager for this purpose. Then use get() to retrieve a model.

Warning

Closing a fetcher invalidates all the models it returned. The fetcher should only be closed once the models are no longer being used.

A fetcher caches all the models it fetches. It is thus reasonably cheap to re-fetch a model. More importantly, some models with different URLs may be in fact be the same model (due to aliasing), and the fetcher will re-use the same model in such cases rather than fetching a duplicate copy.

When fetching a model, the type should be known in advance. This is indicated by passing the type-specific class (such as RFIMask, not RFIMaskRanges). The fetcher validates the retrieved model against this type and raises an exception if it does not match.

It is possible to provide your own requests.Session when constructing the fetcher. This could be used to set additional headers (such as for authentication) or otherwise customize behaviour. If you supply your own session, you are responsible for closing it.

Exception handling

The base class ModelError is used for all errors relating to the content of model files. It has properties original_url and url which respectively contain the requested URL and the final URL (after redirections and aliases) of the problematic model. If the model was not retrieved via HTTP these may be None. See the reference documentation for subclasses that indicate more specific errors.

This exception is not used for transport-level errors when fetching a model, such as OSError for file errors or exceptions from the HTTP library when fetching over HTTP.