SCons/Errors.py

   1 # MIT License
   2 #
   3 # Copyright The SCons Foundation
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining
   6 # a copy of this software and associated documentation files (the
   7 # "Software"), to deal in the Software without restriction, including
   8 # without limitation the rights to use, copy, modify, merge, publish,
   9 # distribute, sublicense, and/or sell copies of the Software, and to
  10 # permit persons to whom the Software is furnished to do so, subject to
  11 # the following conditions:
  12 #
  13 # The above copyright notice and this permission notice shall be included
  14 # in all copies or substantial portions of the Software.
  15 #
  16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  17 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  18 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 """SCons exception classes.
  25
  26 Used to handle internal and user errors in SCons.
  27 """
  28
  29 import shutil
  30 import SCons.Util
  31
  32 # Note that not all Errors are defined here, some are at the point of use
  33
  34
  35 class BuildError(Exception):
  36     """SCons Errors that can occur while building.
  37
  38     A :class:`BuildError` exception contains information both
  39     about the erorr itself, and what caused the error.
  40
  41     Attributes:
  42        node: (*cause*) the error occurred while building this target node(s)
  43        errstr: (*info*) a description of the error message
  44        status: (*info*) the return code of the action that caused the build error.
  45           Must be set to a non-zero value even if the build error is not due
  46           to an action returning a non-zero returned code.
  47        exitstatus: (*info*) SCons exit status due to this build error.
  48           Must be nonzero unless due to an explicit :meth:`Exit` call.
  49           Not always the same as ``status``, since actions return a status
  50           code that should be respected, but SCons typically exits with 2
  51           irrespective of the return value of the failed action.
  52        filename: (*info*) The name of the file or directory that caused the
  53           build error. Set to ``None`` if no files are associated with
  54           this error. This might be different from the target
  55           being built. For example, failure to create the
  56           directory in which the target file will appear. It
  57           can be ``None`` if the error is not due to a particular
  58           filename.
  59        executor: (*cause*) the executor that caused the build to fail (might
  60           be ``None`` if the build failures is not due to the executor failing)
  61        action: (*cause*) the action that caused the build to fail (might be
  62           ``None`` if the build failures is not due to the an
  63           action failure)
  64        command: (*cause*) the command line for the action that caused the
  65           build to fail (might be ``None`` if the build failures
  66           is not due to the an action failure)
  67        exc_info: (*info*) Info about exception that caused the build
  68           error. Set to ``(None, None, None)`` if this build
  69           error is not due to an exception.
  70
  71     """
  72
  73     def __init__(self,
  74                  node=None, errstr: str="Unknown error", status: int=2, exitstatus: int=2,
  75                  filename=None, executor=None, action=None, command=None,
  76                  exc_info=(None, None, None)) -> None:
  77
  78         # py3: errstr should be string and not bytes.
  79
  80         self.errstr = SCons.Util.to_String(errstr)
  81         self.status = status
  82         self.exitstatus = exitstatus
  83         self.filename = filename
  84         self.exc_info = exc_info
  85
  86         self.node = node
  87         self.executor = executor
  88         self.action = action
  89         self.command = command
  90
  91         super().__init__(node, errstr, status, exitstatus, filename,
  92                          executor, action, command, exc_info)
  93
  94     def __str__(self) -> str:
  95         if self.filename:
  96             return self.filename + ': ' + self.errstr
  97         else:
  98             return self.errstr
  99
 100 class InternalError(Exception):
 101     pass
 102
 103 class UserError(Exception):
 104     pass
 105
 106 class StopError(Exception):
 107     pass
 108
 109 class SConsEnvironmentError(Exception):
 110     pass
 111
 112 class MSVCError(IOError):
 113     pass
 114
 115 class ExplicitExit(Exception):
 116     def __init__(self, node=None, status=None, *args) -> None:
 117         self.node = node
 118         self.status = status
 119         self.exitstatus = status
 120         super().__init__(*args)
 121
 122 def convert_to_BuildError(status, exc_info=None):
 123     """Convert a return code to a BuildError Exception.
 124
 125     The `buildError.status` we set here will normally be
 126     used as the exit status of the "scons" process.
 127
 128     Args:
 129       status: can either be a return code or an Exception.
 130       exc_info (tuple, optional): explicit exception information.
 131
 132     """
 133
 134     if not exc_info and isinstance(status, Exception):
 135         exc_info = (status.__class__, status, None)
 136
 137
 138     if isinstance(status, BuildError):
 139         buildError = status
 140         buildError.exitstatus = 2   # always exit with 2 on build errors
 141     elif isinstance(status, ExplicitExit):
 142         status = status.status
 143         errstr = 'Explicit exit, status %s' % status
 144         buildError = BuildError(
 145             errstr=errstr,
 146             status=status,      # might be 0, OK here
 147             exitstatus=status,      # might be 0, OK here
 148             exc_info=exc_info)
 149     elif isinstance(status, (StopError, UserError)):
 150         buildError = BuildError(
 151             errstr=str(status),
 152             status=2,
 153             exitstatus=2,
 154             exc_info=exc_info)
 155     elif isinstance(status, shutil.SameFileError):
 156         # PY3 has a exception for when copying file to itself
 157         # It's object provides info differently than below
 158         try:
 159             filename = status.filename
 160         except AttributeError:
 161             filename = None
 162
 163         buildError = BuildError(
 164             errstr=status.args[0],
 165             status=status.errno,
 166             exitstatus=2,
 167             filename=filename,
 168             exc_info=exc_info)
 169
 170     elif isinstance(status, (SConsEnvironmentError, OSError, IOError)):
 171         # If an IOError/OSError happens, raise a BuildError.
 172         # Report the name of the file or directory that caused the
 173         # error, which might be different from the target being built
 174         # (for example, failure to create the directory in which the
 175         # target file will appear).
 176         filename = getattr(status, 'filename', None)
 177         strerror = getattr(status, 'strerror', str(status))
 178         errno = getattr(status, 'errno', 2)
 179
 180         buildError = BuildError(
 181             errstr=strerror,
 182             status=errno,
 183             exitstatus=2,
 184             filename=filename,
 185             exc_info=exc_info)
 186     elif isinstance(status, Exception):
 187         buildError = BuildError(
 188             errstr='%s : %s' % (status.__class__.__name__, status),
 189             status=2,
 190             exitstatus=2,
 191             exc_info=exc_info)
 192     elif SCons.Util.is_String(status):
 193         buildError = BuildError(
 194             errstr=status,
 195             status=2,
 196             exitstatus=2)
 197     else:
 198         buildError = BuildError(
 199             errstr="Error %s" % status,
 200             status=status,
 201             exitstatus=2)
 202
 203     #import sys
 204     #sys.stderr.write("convert_to_BuildError: status %s => (errstr %s, status %s)\n"%(status,buildError.errstr, buildError.status))
 205     return buildError
 206
 207 # Local Variables:
 208 # tab-width:4
 209 # indent-tabs-mode:nil
 210 # End:
 211 # vim: set expandtab tabstop=4 shiftwidth=4: