pull_data

pull_data(path=None, version=None, force=False, logger=None, verbose=None)[source]

Pull the casarundata contents from the CASA host and install it in path.

The verbose argument controls the level of information provided when this function when the data are unchanged for expected reasons. A level of 0 prints and logs nothing. A value of 1 logs the information and a value of 2 logs and prints the information. Error messages are always logged and printed.

The path must either contain a previously installed version of casarundata or it must not exist or be empty.

If path is None then config.measurespath will be used.

If version is None (the default) then the most recent version is pulled.

If version is “release” then the version associated with the release in the dictionary returned by get_data_info is used. If there is no release version information known then an error message is printed and nothing is checked or installed.

If force is True then the requested version is installed even if that version is already installed.

Results and errors are always printed. They are also logged to the logger if available.

A text file (readme.txt at path) records the version string, the date when that version was installed in path, and the files installed into path. This file is used to determine if the contents are a previously installed version. If path is not empty then this file must exist with the expected contents in order for pull_data to proceed.

If the version to be pulled matches the version in the readme.txt file then pull_data does nothing unless force is True. No error messages will result when the version already matches what was previously installed (no installation is then necessary unless force is True).

The measures tables included in casarundata will typically not be the most recent version. To get the most recent measures data, measures_update should be used after pull_data.

If path contains a previously installed version then all of the files listed in the manifest part of the readme.txt file are first removed from path. This ensures that files not present in the version being installed are removed in moving to the other version.

A file lock is used to prevent more than one data update (pull_data, measures_update, or data_update) from updating any files in path at the same time. When locked, the lock file (data_update.lock in path) contains information about the process that has the lock. When pull_data gets the lock it checks the readme.txt file in path to make sure that a copy of the data should still be pulled (the version doesn’t match what was requested, or force is True). If the lock file is not empty then a previous update of path (pull_data, data_update, or measures_update) did not exit as expected and the contents of path are suspect. In that case, pull_data will report that as an error and nothing will be updated. The lock file can be checked to see the details of when that file was locked. The lock file can be removed and pull_data can then be used to install the desired version. It may be safest in that case to remove path completely or use a different path and run pull_data to install a fresh copy of the desired version.

Some of the tables installed by pull_data are only read when casatools starts. Use of pull_data should typically be followed by a restart of CASA so that any changes are seen by the tools and tasks that use this data.

Note: When version is None (the default), data_available is always used to find out what versions are available. There is no check on when the data were last updated before calling data_available (as there is in the two update functions).

Parameters

  • path (str) - Folder path to place casarundata contents. It must be empty or not exist or contain a valid, previously installed version. If not set then config.measurespath is used.

  • version (str=None) - casadata version to retrieve. Default None gets the most recent version.

  • force (bool=False) - If True, re-download and install the data even when the requested version matches what is already installed. Default False will not download data if the installed version matches the requested version.

  • logger (casatools.logsink=None) - Instance of the casalogger to use for writing messages. Messages are always written to the terminal. Default None does not write any messages to a logger.

  • verbose (int) - Level of output, 0 is none, 1 is to logger, 2 is to logger and terminal, defaults to casaconfig_verbose in the config dictionary.

Returns

None

Raises

  • casaconfig.BadLock - raised when the lock file is not empty when a lock is requested

  • casaconfig.BadReadme - raised when the readme.txt file found at path does not contain the expected list of installed files or there was an unexpected change while the data lock is on

  • casaconfig.NoNetwork - raised where this is no network

  • casaconfig.NotWritable - raised when the user does not have write permission to path

  • casaconfig.RemoteError - raised by data_available when the list of available data versions could not be fetched for some reason other than no network

  • casaconfig.UnsetMeasurespath - raised when path is None and and measurespath has not been set in config.