data_update

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

Check for updates to the installed casarundata and install the update or change to the requested version when appropriate.

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 printed and logged (when a logger is provided).

The path must contain a previously installed version of casarundata. Use pull_data to install casarundata into a new path (empty or does not exist).

If path is None then config.measurespath is used.

If the version is None (the default) then the most recent version returned by data_available is used.

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 available to casaconfig then an error message is printed and nothing is updated. Release version information is only available in monolithic CASA installations.

If a specific version is not requested (the default) and it has been less than data_update_interval (a config value) days since the last check for a more recent version then this function does nothing even if there is a more recent version available from the CASA server. Using force=True forces a check for a more recent version, ignoring the days since the last check. The data_update_interval is always used as an int type (including any truncation of the actual value in config if not an integer).

If force is True then the requested version (or the latest version available now) is installed even if that version is already installed or a check for the latest version has been done within the past 24 hours.

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. That file must already exist in path in order to use this function. Use pull_data to install casarundata into a new location.

When auto_update_rules is True then path must be owned by the user, force must be False and the version must be None. This is used during casatools initialization when data_auto_update is True. Automatic updating happens during casatools initialization so that the updated casarundata and measures are in place before any tool needs to use them.

If an update is to be installed the previously installed files, as listed in the readme.txt file at path, are removed before the contents of the version being installed are unpacked. If the measures contents of path have been updated since the previously installed version of casarundata then those updates will also be removed by this data update while preparing to install the requested version of casarundata (which includes a copy of the measures data that is likely older than today). A data update is typically followed by a measures_update to ensure that the most recent measures data are installed.

A file lock is used to prevent more that 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 data_update gets the lock it checks the readme.txt file in path to make sure that an update is still necessary (if force is True then an update always happens). 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 or is still in process (via a separate instance of CASA) and the contents of path may be suspect. In that case, an error will be reported 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 data_update can be tried again. It may be safest in that case to remove path completely or use a different path and use pull_data to install a fresh copy of the desired version.

Some of the tables installed by data_update are only read when casatools starts. Use of data_update except during CASA startup by the auto update proess 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: data_update requires that the expected readme.txt file already exists at the top-level directory at path. If the file does not exist or can not be interpreted as expected then data_update will return without updating any data.

Note: if auto_update_rules is True the user must own path (in addition to having read and write permissions there). The version must then also be None and the force option must be False.

Note: the most recent casarundata may not include the most recent measures data. A data_update is typically followed by a measures_update.

Parameters

  • path (str=None) - Folder path to update. Must contain a valid readme.txt. If not set then config.measurespath is used.

  • version (str=None) - Version of casarundata to retrieve (usually in the form of casarundata-x.y.z.tar.gz, see data_available()). Default None retrieves the latest.

  • force (bool=False) - If True, always re-download the casarundata. Default False will not download casarundata if updated within the past day unless the version parameter is specified and different from what was last downloaded.

  • logger (casatools.logsink=None) - Instance of the casalogger to use for writing messages. Default None writes messages to the terminal.

  • auto_update_rules (bool=False) - If True then the user must be the owner of path, version must be None, and force must be False.

  • 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.AutoUpdatesNotAllowed - raised when path does not exist as a directory or is not owned by the user

  • casaconfig.BadLock - raised when the lock file was not empty when an attempt was made to obtain the lock

  • casaconfig.BadReadme - raised when the readme.txt file at path did not contain the expected list of installed files or was incorrectly formatted

  • casaconfig.NoReadme - raised when the readme.txt file is not found at path (path also may not exist)

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

  • casaconfig.RemoteError - raised by data_available when the list of available data versions could not be fetched

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

  • Exception - raised when there was an unexpected exception while populating path