API Reference

ska_telmodel.data

class ska_telmodel.data.TMData(source_uris: list[str] | None = None, prefix: str = '', update: bool = False, backend_pars: dict = {}, yield_hidden: bool = False)

Represents a tree of telescope model data.

Data is retrieved from specified sources (or using default sources if not passed). Depending on backend, this might cause data to be loaded from remote locations, such as the SKAO central artefact repository or Gitlab.

Objects of this class provide a hierarchical dict/h5py-like interface. For instance, you can print all objects with keys starting with instrument/layout as follows:

layouts = tmdata['instrument/layout']
for key in layouts:
   print(f"Data for {key}: ", layouts[key].get())

This works because __getitem__() will redirect to get_subtree() or get() depending on whether a valid key is passed (i.e. it has an extension). The TMObject object can then be used to access the underlying telescope model data.

Parameters:

source_uris – List of telescope model data sources. If not passed, defaults to SKA_TELMODEL_SOURCES enviroment variable, then in-built DEFAULT_SOURCES.
prefix – Key prefix for sub-tree selection
update – Update cached data sources (if any)
backend_pars – Extra parameters to specific backend (types)
yield_hidden – If set, __iter__ will yield hidden files

ALIASES_FILENAME = '.tmaliases'

get(key: str) → TMObject

Returns the telescope model object with the given key

Parameters:: key – Key to retrieve. Must be a valid telescope model key (i.e. have a file type extension)
Returns:: TMObject object
Raises:: KeyError if object doesn’t exist

classmethod get_schema_uri(key: str) → str | None

Returns the schema URI corresponding to the input key.

Parameters:: key – Key to query
Returns:: Corresponding schema URI from schema-path maps

get_sources(pinned: bool = False) → list[str]

Returns list of source URIs

Parameters:: pinned – Attempt to return URIs that will continue to refer to this specific version of telescope model data. E.g. for GitLab URIs, this replaces tags or branches by the concrete commit hash.
Returns:: list of sources

get_subtree(prefix: str) → TMData

Returns clone of TMData object with given prefix

Note that no checking is done whether any keys with the given prefix exist.

Parameters:: prefix – Prefix to narrow scope to. Must be a valid telescope model prefix
Returns:: TMData object using prefix

class ska_telmodel.data.TMObject(source: TMDataBackend, key: str, large_file: bool = False)

Represents a telescope model data object. Provides a number of ways to access the data.

Parameters:

source – Backend to use to retrieve object data
key – Key associated with object

copy(dest: str)

Copy object data to a file.

Parameters:: dest – Path of destination file

get() → bytes

Access data at given key as raw bytes

Returns:: Raw object data

get_dict(**kwargs) → dict

Access object as a dictionary

Will only work if the key ends with a known extension – e.g. .json or .yaml.

Parameters:: kwargs – Extra parameters to [json/yaml].load
Returns:: Parsed dictionary

get_link_contents()

property is_cached: bool

property is_large_file: bool

property key: str: Returns the key associated with the object.

open() → IO[bytes]

Access object data as a read-only file object

Parameters:: key – Key to query
Returns:: File-like object

property schema_uri: str | None: Returns the schema URI corresponding to the object’s key.

property size: int

property source: TMDataBackend: Get the Data Backend for this object

ska_telmodel.schema

Support for validating and generating examples for SKA telescope model schemas.

class ska_telmodel.schema.SchemaUri(version: str)

Convenience class for manipulating version URIs.

Parameters:: version – Interface URI

property major_minor: Tuple[int, int]

Get the major and minor parts of the version.

Returns:: tuple of major and minor versions

property prefix: str

Get the prefix.

Returns:: prefix

property prefix_before_version: str

Get the version without the prefix.

Returns:: version

property version: str

Get the version.

Returns:: version

ska_telmodel.schema.example_by_uri(version: str, *args) → dict

Generates an example for a particular schema

Parameters:

version – Interface URI
args – Extra parameters depending on interface (strings)

Returns:

Dictionary

ska_telmodel.schema.schema_by_uri(version: str, strict: int = 1, **kwargs) → Schema

Looks up interface schema based on interface identifier

Parameters:

version – Interface URI
strict – Strictness level

Returns:

Interface schema

ska_telmodel.schema.validate(version: str | None, config: dict, strictness: int = 1, jsonschema_fallback=False)

Validate a dictionary against schema

Will automatically determine the schema to check against

Parameters:

version – Interface with version
config – Dictionary to validate
strictness –
Strictness level (1: permissive errors + strict warnings, 2: strict errors).

Note that with strictness level 2, a lot of generally harmless schema violations will cause an exception to be raised. This is generally inadvisable in production consumer code (“be liberal in what you accept”!).Therefore, strictness 2 checks will only be allowed to raise errors when running in testing mode (either PYTEST_VERSION or SKA_TELMODEL_ALLOW_STRICT_VALIDATION) is set.
jsonschema_fallback –
Schema Validation Strategy. The system uses a configurable fallback mechanism controlled by the jsonschema_fallback flag. by default, this flag is set to False. validation process is below. in what you accept”!).

First attempts validation using the local TMSchema object. If local validation fails with SchemaError, automatically falls back to external schema validation. External validation uses the provided document URL.

Raises:

ValueError – Raised if the object fails permissive checks at strictness level 1. At strictness level 2, raised if the object fails any schema check 3.Raised if fails external validation using documented URL.