new exceptions in CasaconfigErrors.py, used throughout, new verbose a…

…rgument and casaconfig_verbose config value, documentation updates

casaconfig/__init__.py

@@ -12,3 +12,4 @@
 from .private.set_casacore_path import set_casacore_path
 from .private.get_config import get_config
 from .private.get_data_info import get_data_info
+from .private.CasaconfigErrors import *

casaconfig/__main__.py

@@ -44,68 +44,96 @@
     config.measurespath = flags.measurespath
 
 # watch for measurespath of None, that likely means that casasiteconfig.py is in use and this has not been set. It can't be used then.
-if flags.measurespath is None:
-    print("measurespath has been set to None, likely in casasiteconfig.py.")
-    print("Either provide a measurespath on the casaconfig command line or edit casasiteconfig.py or other a user config.py to set measurespath to a location.")
-    sys.exit(1)
+try:
+    if flags.measurespath is None:
+        print("measurespath has been set to None in the user or site config file.")
+        print("Either provide a measurespath on the casaconfig command line or edit the user or site config file to set measurespath to a location.")
+        sys.exit(1)
 
-# do any expanduser and abspath - this is what should be used
-measurespath = os.path.abspath(os.path.expanduser(flags.measurespath))
+    # do any expanduser and abspath - this is what should be used
+    measurespath = os.path.abspath(os.path.expanduser(flags.measurespath))
 
-if flags.currentdata:
-    if not os.path.exists(measurespath) or not os.path.isdir(measurespath):
-        print("No data installed at %s. The measurespath does not exist or is not a directory." % measurespath)
-    else:
-        from casaconfig import get_data_info
-        print("current data installed at %s" % measurespath)
-        dataInfo = get_data_info(measurespath)
-
-        # casarundata
-        casarunInfo = dataInfo['casarundata']
-        if casarunInfo is None or casarunInfo['version'] == "invalid":
-            print("No casarundata found (missing or unexpected readme.txt contents, not obviously legacy casa data).")
-        elif casarunInfo['version'] == "unknown":
-            print("casarundata version is unknown (probably legacy casa data not maintained by casaconfig).")
+    if flags.currentdata:
+        if not os.path.exists(measurespath) or not os.path.isdir(measurespath):
+            print("No data installed at %s. The measurespath does not exist or is not a directory." % measurespath)
         else:
-            currentVersion = casarunInfo['version']
-            currentDate = casarunInfo['date']
-            print('casarundata version %s installed on %s' % (currentVersion, currentDate))
+            print("current data installed at %s" % measurespath)
+            dataInfo = casaconfig.get_data_info(measurespath)
+
+            # casarundata
+            casarunInfo = dataInfo['casarundata']
+            if casarunInfo is None or casarunInfo['version'] == "invalid":
+                print("No casarundata found (missing readme.txt and not obviously legacy casa data).")
+            if casarunInfo['version'] == "error":
+                print("Unexpected casarundata readme.txt content; casarundata should be reinstalled.")
+            elif casarunInfo['version'] == "unknown":
+                print("casarundata version is unknown (probably legacy casa data not maintained by casaconfig).")
+            else:
+                currentVersion = casarunInfo['version']
+                currentDate = casarunInfo['date']
+                print('casarundata version %s installed on %s' % (currentVersion, currentDate))
 
-        # measures
-        measuresInfo = dataInfo['measures']
-        if measuresInfo is None or measuresInfo['version'] == "invalid":
-            print("No measures data found (missing or unexpected readme.txt, not obviously legacy measures data).")
-        elif measuresInfo['version'] == "unknown":
-            print("measures version is unknown (probably legacy measures data not maintained by casaconfig).")
-        else:
-            currentVersion = measuresInfo['version']
-            currentDate = measuresInfo['date']
-            print('measures version %s installed on %s' % (currentVersion, currentDate))
+            # measures
+            measuresInfo = dataInfo['measures']
+            if measuresInfo is None or measuresInfo['version'] == "invalid":
+                print("No measures data found (missing readme.txt and not obviously legacy measures data).")
+            if measuresInfo['version'] == "error":
+                print("Unexpected measures readme.txt content; measures should be reinstalled.")
+            elif measuresInfo['version'] == "unknown":
+                print("measures version is unknown (probably legacy measures data not maintained by casaconfig).")
+            else:
+                currentVersion = measuresInfo['version']
+                currentDate = measuresInfo['date']
+                print('measures version %s installed on %s' % (currentVersion, currentDate))
 
-    # ignore any other arguments
-elif flags.summary:
-    from casaconfig.private.summary import summary
-    summary(config)
-    # ignore any other arguments
-else:
-    if flags.referencetesting:
-        print("reference testing using pull_data and 'release' version into %s" % measurespath)
-        casaconfig.pull_data(measurespath,'release')
-        # ignore all other options
+        # ignore any other arguments
+    elif flags.summary:
+        from casaconfig.private.summary import summary
+        summary(config)
+        # ignore any other arguments
     else:
-        # the update options, update all does everything, no need to invoke anything else
-        print("Checking for updates into %s" % measurespath)
-        if flags.updateall:
-            casaconfig.update_all(measurespath,force=flags.force)
+        if flags.referencetesting:
+            print("reference testing using pull_data and 'release' version into %s" % measurespath)
+            casaconfig.pull_data(measurespath,'release')
+            # ignore all other options
         else:
-            # do any pull_update first
-            if flags.pulldata:
-                casaconfig.pull_data(measurespath)
-            # then data_update, not necessary if pull_data just happened
-            if flags.dataupdate and not flags.pulldata:
-                casaconfig.data_update(measurespath, force=flags.force)
-            # then measures_update
-            if flags.measuresupdate:
-                casaconfig.measures_update(measurespath, force=flags.force)
+            # the update options, update all does everything, no need to invoke anything else
+            print("Checking for updates into %s" % measurespath)
+            if flags.updateall:
+                casaconfig.update_all(measurespath,force=flags.force)
+            else:
+                # do any pull_update first
+                if flags.pulldata:
+                    casaconfig.pull_data(measurespath)
+                # then data_update, not necessary if pull_data just happened
+                if flags.dataupdate and not flags.pulldata:
+                    casaconfig.data_update(measurespath, force=flags.force)
+                # then measures_update
+                if flags.measuresupdate:
+                    casaconfig.measures_update(measurespath, force=flags.force)
+
+except casaconfig.UnsetMeasurespath as exc:
+    # UnsetMeasurespath should not happen because measurespath is checked to not be None above, but just in case
+    print(str(exc))
+    print("This exception should not happen, check the previous messages for additional information and try a different path")
+    sys.exit(1)
+
+except casaconfig.BadReadme as exc:
+    print(str(exc))
+    sys.exit(1)
+
+except casaconfig.RemoteError as exc:
+    print(str(exc))
+    print("This is likely due to no network connection or bad connectivity to a remote site, wait and try again")
+    sys.exit(1)
+
+except casaconfig.BadLock as exc:
+    # the output produced by the update functions is sufficient, just re-echo the exception text itself
+    print(str(exc))
+    sys.exit(1)
+
+except casaconfig.NotWritable as exc:
+    print(str(exc))
+    sys.exit(1)
 
 sys.exit(0)

casaconfig/private/CasaconfigErrors.py

@@ -0,0 +1,42 @@
+# Copyright 2024 AUI, Inc. Washington DC, USA
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+"""
+this module will be included in the api
+"""
+
+class AutoUpdatesNotAllowed(Exception):
+    """Raised when a path does not exist or is not owned by the user"""
+    pass
+
+class BadLock(Exception):
+    """Raised when the lock file is not empty and a lock attempt was made"""
+    pass
+
+class BadReadme(Exception):
+    """Raised when a readme.txt file does not contain the expected contents"""
+    pass
+
+class NoReadme(Exception):
+    """Raised when the readme.txt file is not found at path (path also may not exist)"""
+
+class RemoteError(Exception):
+    """Raised when there is an error fetching some remote content"""
+    pass
+
+class NotWritable(Exception):
+    """Raised when the path is not writable by the user"""
+
+class UnsetMeasurespath(Exception):
+    """Raised when a path argument is None"""
+    pass

casaconfig/private/config_defaults_static.py

@@ -51,3 +51,6 @@
 
 # include the user's local site-packages in the python path if True. May conflict with CASA modules
 user_site = False
+
+# verbosity level for casaconfig
+casaconfig_verbose = 1

casaconfig/private/data_available.py

@@ -29,18 +29,25 @@ def data_available():
     changing casaconfig functions that use those tarballs). The full filename is
     the casarundata version expected in casaconfig functions.
 
-    Parameters
+    Parameters:
        None
     
-    Returns
-       list - version names returned as list of strings
+    Returns:
+       list: version names returned as list of strings
+
+    Raises:
+       casaconfig.RemoteError: Raised when there is an error fetching some remote content
+       Exception: Unexpected exception while getting list of available casarundata versions
 
     """
 
     import html.parser
     import urllib.request
+    import urllib.error
     import ssl
     import certifi
+
+    from casaconfig import RemoteError
 
     class LinkParser(html.parser.HTMLParser):
         def reset(self):
@@ -67,10 +74,13 @@ def handle_starttag(self, tag, attrs):
 
         # return the sorted list, earliest versions are first, newest is last
         return sorted(parser.rundataList)
-
+
+    except urllib.error.URLError as urlerr:
+        raise RemoteError("Unable to retrieve list of available casarundata versions : " + str(urlerr)) from None
+
     except Exception as exc:
-        print("ERROR! : unexpected exception while getting list of available casarundata versions")
-        print("ERROR! : %s" % exc)
+        msg = "Unexpected exception while getting list of available casarundata versions : " + str(exc)
+        raise Exception(msg)
 
     # nothing to return if it got here, must have been an exception
     return []