API reference

ska_telmodel.data

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

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)

get(key: str) → TMObject[source]

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

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

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[source]

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)[source]

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)[source]

Copy object data to a file.

Parameters:

dest – Path of destination file

get() → bytes[source]

Access data at given key as raw bytes

Returns:

Raw object data

get_dict(**kwargs) → dict[source]

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

property is_cached: bool
property is_large_file: bool
open() → IO[bytes][source]

Access object data as a read-only file object

Parameters:

key – Key to query

Returns:

File-like object

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)[source]

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[source]

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[source]

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)[source]

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 (0: permissive warnings, 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.