__init__.py

00001 # mbed SDK
00002 # Copyright (c) 2011-2013 ARM Limited
00003 #
00004 # Licensed under the Apache License, Version 2.0 (the "License");
00005 # you may not use this file except in compliance with the License.
00006 # You may obtain a copy of the License at
00007 #
00008 #     http://www.apache.org/licenses/LICENSE-2.0
00009 #
00010 # Unless required by applicable law or agreed to in writing, software
00011 # distributed under the License is distributed on an "AS IS" BASIS,
00012 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 # See the License for the specific language governing permissions and
00014 # limitations under the License.
00015 
00016 from __future__ import print_function, division, absolute_import
00017 
00018 from abc import ABCMeta, abstractmethod
00019 
00020 
00021 class Notifier (object):
00022     """
00023     Notifiers send build system events to a front end or may implement a front
00024     end themselves, displaying warnings and errors for a user.
00025 
00026     This is different from a logger in a few ways:
00027      * The structure of the events are defined by this interface.
00028      * A "progress" level is included allowing signaling completion status to
00029        users.
00030      * It's tailored to providing events from a build system.
00031 
00032     The structure of a message is a dict with a 'type' key. The type key
00033     determines the remaining keys as follows:
00034       type       | description and remaining keys
00035       ---------- | ------------------------------
00036       info       | A simple message. The 'message' key contains the message
00037       debug      | Another simple message; this one is less useful when compiles
00038                  | are working. Again, the 'message' key contains the message
00039       progress   | A progress indicator, which may include progress as a
00040                  | percentage. The action key includes what action was taken to
00041                  | make this progress, the file key what file was used to make
00042                  | this progress, and the percent key, when present, indicates
00043                  | how far along the build is.
00044       tool_error | When a compile fails, this contains the entire output of the
00045                  | compiler.
00046       var        | Provides a key, in the 'key' key, and a value, in the 'value'
00047                  | key, for use in a UI. At the time of writing it's used to
00048                  | communicate the binary location to the online IDE.
00049     """
00050 
00051     __metaclass__ = ABCMeta
00052 
00053     @abstractmethod
00054     def notify (self, event):
00055         """
00056         Send the user a notification specified in the event.
00057         """
00058         raise NotImplemented
00059 
00060     def info (self, message):
00061         """
00062         Send the user a simple message.
00063         """
00064         self.notify ({'type': 'info', 'message': message})
00065 
00066     def debug (self, message):
00067         """
00068         Send a debug message to the user.
00069         """
00070         if isinstance(message, list):
00071             message = ' '.join(message)
00072         self.notify ({'type': 'debug', 'message': message})
00073 
00074     def cc_info(self, info=None):
00075         if info is not None:
00076             info['type'] = 'cc'
00077             self.notify (info)
00078 
00079     def cc_verbose(self, message, file=""):
00080         self.notify ({
00081             'type': 'cc',
00082             'severity': 'verbose',
00083             'file': file,
00084             'message': message
00085         })
00086 
00087     def progress (self, action, file, percent=None):
00088         """
00089         Indicate compilation progress to a user.
00090         """
00091         msg = {'type': 'progress', 'action': action, 'file': file}
00092         if percent:
00093             msg['percent'] = percent
00094         self.notify (msg)
00095 
00096     def tool_error (self, message):
00097         """
00098         Communicate a full fatal error to a user.
00099         """
00100         self.notify ({'type': 'tool_error', 'message': message})
00101 
00102     def var (self, key, value):
00103         """
00104         Update a UI with a key, value pair
00105         """
00106         self.notify ({'type': 'var', 'key': key, 'val': value})