Changes between Version 1 and Version 2 of PythonPort/Design/ErrorReporting


Ignore:
Timestamp:
Oct 28, 2007, 3:38:50 PM (18 years ago)
Author:
ghost
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • PythonPort/Design/ErrorReporting

    v1 v2  
    1 
    21= Error reporting guidelines for Boost.Build Python port =
    32
    … …  
    1817It's possible that we detect an error that is not directly traceable to user action, or Python interpreter itself detects an error and raise an Exception. We'll have try/except blocks at strategic places to associate such exceptions with user contexts.
    1918
    20 The error handling documented here is
     19The error handling documented here is implemented by the {{{boost.build.build.errors}}} module. The main class there is {{{Errors}}}, and an instance of that call can be obtained by calling the {{{errors()}}} method on the Manager class.
    2120
    2221== Reporting errors ==
    … …  
    3231
    3332== Maintaining user context and handling stray exceptions ==
     33
     34'''Todo''': implement function decorator for this
    3435
    3536Any function that does something on interest to user must be written like this:
    … …  
    6263== Capturing context ==
    6364
     65'''Todo''': actually implement this.
    6466The targets are created when we parse Jamfiles, and built as a separate step. For all errors during
    6567building, it's desirable to report from where the target was declared. To that end:
    6668  1. When the target is declared, we grab the current user context, calling {{{Errors.capture_user_context}}}.
    67   2. When actually building, the call to {{{Errors.
     69  2. When actually building, the call to {{{Errors.push_user_context}}} should provide a message describing what is done, and additionally, pass the previously captured context as the value of the {{{nested}}} parameter.
    6870
     71== Top-level error reporting ==
    6972
     73All functions called from Jam, including the main function of Boost.Build, will have try/catch blocks. When
     74{{{ExceptionWithUserContext}}} is caught, its {{{report}}} method will be printed. Should stray exception be
     75caught, despite all efforts, we'll also nicely print it.
    7076
     77== Raw backtrace ==
    7178
    72 1. For each error, we clearly will be able to produce
    73 a raw stacktrace, but it's not very useful. Therefore,
    74 we need some 'user-context' mode of error reporting, where
    75 user is told what high-level actions were performed when
    76 the error happened. For example:
     79[The behaviour described in this section is not yet implemented]
    7780
    78         error: invalid feature 'non-existent'
    79         - when computing build properties for target 'foo'
    80         - when build project in '.'
    81 
    82 To implement this we need:
    83 
    84   - Maintain those user-contexts
    85   - Arrange for user-context to be printed or recorded when
    86   error happens
    87   - Do something about 'stray' exceptions through in
    88   Python code, like caused by bugs
    89 
    90 2. We should have a module errors with two functions:
    91 'push-context' and 'pop-context'. The first takes a
    92 string description of what we're doing now. Every function
    93 that does something interesting from the user's point of
    94 view should be written like:
    95 
    96         try:
    97                 errors.push_context("Doing something")
    98                 # do something
    99         finally:
    100                 errors.pop_context()
    101 
    102 The try/finally is needed so that if stray exception is thrown,
    103 the pushed used context does not stay pushed forever.
    104 
    105 3. Whenever we run into error condition that can be explained in
    106 user terms, we'll use errors.error(). That function will
    107 create new exception type, record current user context into
    108 it, and raise that exception.
    109 
    110 4. Python exception should never be allowed to escape back to jam.
    111 Every function called from bjam should try/catch and print
    112 the exception.
    113 
    114 5. Every function called from bjam will get bjam stack trace
    115 and add it to user context. So, if error happens user will
    116 see what line from Jamfile caused it.
    117 
    118 6. It's possible that we either detect error at too low
    119 level to provide any explanation, or the error is detected
    120 by Python interpreter. In which case, an ordinary exception
    121 will be thrown. To still provide some context, we should
    122 use try/catch at various strategic places, catch such stray
    123 exceptions, and throw new exception, that holds current user
    124 context and the original exception. So, if we try to say
    125 interate over None somewhere deep, we'll get an error message
    126 like this:
    127 
    128         internal-error: Itetarion over non-sequence
    129         - when building target 'foo'
    130 
    131         Use --backtrace to see Python backtrace
    132 
    133 Note that this output is not very useful to debug anything.
    134 It's primarily meant to avoid completely freaking out users
    135 who are not accustomed to Python stacktraces. This way, they'll
    136 at least have the time to open Python docs before getting
    137 real Python stracktrace.
    138 
    139 7. When printing real stacktrace, we can be inside Python code
    140 called from Jam code, called from Python code etc. Technically,
     81If a {{{--stacktrace}}} parameter is specified on the command line, we'll print raw Python backtrace.
     82Such a backtrace can include Python code called from Jam code, called from Python code etc. Technically,
    14183it appears possible to interleave stacktraces, something like:
    14284
    … …  
    14486        Jamroot:12
    14587        project.py:70
     88
     89an so we'll try to do that.
     90