Professional IronPython

Understanding IronPython Warnings
 
❘
 
249
Working with Messages
A message is simply the text that you want to appear as part of the warning. The message is specific 
information about the warning so that someone viewing the warning will know precisely why the 
warning is issued. For example, if you issue a 
DeprecationWarning
category warning, the output will 
automatically tell the viewer that something is deprecated. As a result, your message doesn’t have to 
tell the viewer that something is deprecated, but it does have to tell the viewer what is deprecated. In 
many cases, this means supplying the name of the feature such as a method name, attribute, function, 
or even a class.
Simply telling someone that a feature is deprecated usually isn’t enough information. At a mini-
mum, you must include information about an alternative. For example, you might want to suggest 
another class or a different function. Even if there is no alternative, you should at least tell the 
viewer that there isn’t an alternative. Otherwise, the viewer is going to spend hours looking for 
something that doesn’t exist.
You can’t always tell someone why something is deprecated, but you should when you can. For 
example, it would be helpful to know that an old function is unstable and that the new function 
fixes this problem. It’s a good idea to extend this information by saying that the old function is 
supplied for backward compatibility (assuming that this really is the case).
In some cases, you also need to provide some idea of when a feature is deprecated, especially if the 
action occurs in the future. Perhaps your organization knows that a function is unstable but hasn’t 
come up with a fix yet. The fix will appear in the next version of a module as a new function. Having 
this information will help organizations that rely on your module to plan ahead for required updates.
The point of messages is that they should provide robust information — everything that someone 
needs to make good decisions. Of course, you don’t want to provide too much information either 
(anything over three well-written sentences is too much). If you feel the viewer needs additional infor-
mation, you can always provide it as part of the feature’s help. That way, people who are curious can 
always find more information. Make sure you note the availability of additional information as part 
of your message.
Message consistency is another consideration. Remember that filters work with messages as well as 
categories and other warning elements. If two modules require the same message, make sure you use 
the same message to ensure filtering works as anticipated. In fact, copying and pasting the message 
is encouraged to reduce the risk of typographical errors.
If you ever want to see how your message will appear to others, you can use the 
formatwarning()
function to perform the task. Try it out now. Open a copy of the IronPython console and try the 
following code.
import warnings 
warnings.formatwarning(‘Bad Input’, UserWarning, ‘My.py’, 5, ‘import warnings’)
You’ll see results similar to those shown in Figure 12-5. Notice that the output contains linefeeds 
like this: 
‘My.py:5: UserWarning: Bad Input\n import warnings\n‘
. When you work with 
the printed version, the warning appears on multiple lines, as shown near the bottom of Figure 12-5.
548592c12.indd 249
2/24/10 12:48:46 PM
www.finebook.ir

---