Command Line Usage

The library provides the ska-telmodel command line utility that can be used to perform basic data retrieval and validation tasks. Usage examples:

ska-telmodel [-vULS<uris>] cat [<key>]
ska-telmodel [-vULS<uris>] cp [-R] <key> [<path>]
ska-telmodel [-vULS<uris>] ls [<prefix>]
ska-telmodel [-vULS<uris>] pin
ska-telmodel [-vULS<uris>] validate [-tR] <key/path>
ska-telmodel help [<command>]

Options:
  -L, --local        Equivalent to "--sources=file://."
  -R, --recursive    Copy / validate keys or files recursively
  -S <uris>, --sources <uris>
                     Set telescope model data sources of truth
                     (','-separated list of URIs)
  -t, --strict       Strict validation mode
  -U, --update       Update source list
  -v, --verbose      Verbose mode

See Data Sources for explanations about telescope model data sources.

ska_telmodel.cli.cmd_cat(args, data)

Retrieves and prints the telescope model data identifed by the given key to stdout.

Usage:

ska-telmodel [-vUs<uris>] cat [<key>]

Use ska-telmodel ls to obtain a list of valid keys.

How exactly the object is retrieved depends on the backend and the state of the cache. For a GitLab backend, the typical behaviour is to download a tarball either from the SKAO central artefact repository, or from GitLab directly. The latter should be avoided and will generate a warning.

ska_telmodel.cli.cmd_cp(args, srcs)

Retrieves specified telescope model data, and copies it to the given path.

Usage:

ska-telmodel [-vUs<uris>] cp [-R] <key> [<path>]

If -R is given, the key can be a key directory, in which all keys that start with <path>/ will be copied. Note that you can especially give the empty string ("") as <key>, in which case all available telescope model data will be copied.

This is especially useful for serving telescope model data either partially or completely from storage. For instance:

$ ska-telmodel cp -UR "" tmdata
$ export SKA_TELMODEL_SOURCES=file://$(pwd)/tmdata

Would completely mirror the telescope model to the given location.

ska_telmodel.cli.cmd_ls(args, data)

List telescope model keys with a particular prefix

Usage:

ska-telmodel [-vUs<uris>] ls [<prefix>]

ska_telmodel.cli.cmd_pin(args, data)

Generates a “pinned” telescope model data source list, where all URIs replaced such that they will uniquely identify the contents of the telescope model data repository.

Usage:

ska-telmodel [-vUs<uris>] pin

After pinning, the source list precisely identifies the contents of the all telescope model data. For instance, this will replace GitLab URIs like gitlab://gitlab.com/grp/proj#path with gitlab://gitlab.com/grp/proj?[commit]#path, therefore baking in the exact commit referenced. You can set pinned sources in the environment as follows:

$ export $(ska-telmodel pin -U)
$ export $(ska-telmodel pin -US [custom sources])

This will especially prevent the ska-telmodel tool from infrequently (once a day) re-checking whether cached telescope model data contents is still current. The -U flag forces the cache refresh, which is generally a good idea before pinning.

ska_telmodel.cli.cmd_validate(args, srcs)

Validates given keys (or files) against applicable schemas from the telescope model library

Usage:

ska-telmodel [-vUs<uris>] validate [-tlR] [<key/path>]*

If -R is given, the key can be a key directory, in which all keys that start with <path>/ will be copied. Note that you can especially give the empty string ("") as <key>, in which case all available telescope model data will be copied.

This is especially useful for serving telescope model data either partially or completely from storage. For instance:

$ ska-telmodel cp -R "" tmdata
$ export SKA_TELMODEL_SOURCES=file://$(pwd)/tmdata

Would completely mirror the telescope model to the given location.