Authoring Python Warning Processors: The csonar_utils Package

• Overview
• Using csonar_utils
• Other Warning Processor Sections

Overview

Location

The csonar_utils package is located at $CSONAR/py/processors/csonar_utils/.

We strongly recommend using the Python installation that ships with CodeSonar.
Your wrapper script can refer to this Python executable using the CSONAR environment variable that is available to the warning processor subprocess: "%CSONAR%\codesonar\bin\cspython.exe" on Windows; "$CSONAR/codesonar/bin/cspython" on other systems.

• Note that the executable is called cspython (rather than python).
• You may find it convenient to put this bin/ directory in your PATH.

Contents

The most important piece of the csonar_utils package is the WarningProcessor class. We provide a brief overview here, for full details see the csonar_utils documentation.

Using csonar_utils

To write a Python warning processor using csonar_utils:

1. Create a new main.py file, and import sys and os:

   import sys, os
         
   

2. Copy and paste the import_module() function definition from $CSONAR/py/processors/bugzilla/main.py into your main.py file, then use it to import csonar_utils.

   def import_module(module_name):
      # ...
      
   import_module('csonar_utils')
   from csonar_utils import WarningProcessor
   

3. Define a subclass of WarningProcessor.

   class MyProcessorName(WarningProcessor):
       # class definitions
      
           
   if __name__ == '__main__':
       m = MyProcessorName()
       m.start()
   

4. For each required command (install, begin, commit, rollback, retry, abort, analysis_transition) that you want to associate functionality with, define the corresponding on_commandname function.
5. To use the XML parser provided by csonar_utils, define one or more of the XML handler methods. Most of the "warning processing" work will generally take place in handle_warning().
6. Make sure your warning processor produces appropriate output (use output() to emit it).
7. Once you have finished writing the Python code for your warning processor, create a file for running it:

   On Windows: create a batch file in hubdir/processors.

   1. Make a clean copy of the template batch file.
      cd processors
      cp $CSONAR/py/processors/wrapper.bat processor_name.bat
   2. Open processor_name.bat for editing; follow the instructions in the file to customize it.

   On other systems: create a wrapper script in hubdir/processors.

   1. Make a clean copy of the template wrapper script and make it executable.
      cd processors
      cp $CSONAR/py/processors/wrapper.sh processor_name.sh
      chmod +x processor_name.sh
   2. Open processor_name.sh for editing; follow the instructions in the file to customize it.
8. Finally, install the processor:
   1. Open the Manage Warning Processors page in the Web GUI and scroll to the Add New Warning Processor section.
   2. Enter a suitable label for the warning processor in the Label field, and processor_name.sh or processor_name.bat (that is, the file name) in the Processor Executable field.
   3. Click the Install button.

Other Warning Processor Sections

The following sections contain further information about warning processors.