2. Error and Warning messages¶
When a WML or a Lua file contains a problem, wmlxgettext returns a warning (if the problem is not critical) or an error (critical problem) to the end-user to allow him/her to fix his own wesnoth addon.
When wmlxgettext must return an error, it calls wmlerr
function; it calls
wmlwarn
function when it should simply display a warning. Both wmlerr
and wmlwarn
function are defined in ./pywmlx/wmlerr.py
module.
When importing pywmlx, wmlxgettext will import only wmlerr
and
wmlwarn
functions (and ansi_setEnabled
), since all other
classes/functions in ./pywmlx/wmlerr.py
module are only internally required
by wmlerr
and wmlwarn
functions to work properly.
2.1. About ansi_setEnabled function¶
When you import pywmlx
, also ansi_setEnabled
function is imported from
./pywmlx/wmlerr.py
module.
ansi_setEnabled
accepts a boolean value (True
or False
). By default
it is setted to True
, but it will be False
if the flag
--no-ansi-colors
was used in the command line:
# ./wmlxgettext:100
parser.add_argument(
'--no-ansi-colors',
action='store_false',
default=True,
dest='ansi_col',
help=("By default warnings are displayed with colored text. You can " +
"disable this feature using this flag.\n" +
"This option doesn't have any effect on windows, since it " +
"doesn't support ansi colors (on windows colors are ALWAYS" +
'disabled).')
)
# ...
# ./wmlxgettext:141
pywmlx.ansi_setEnabled(args.ansi_col)
When calling this function, wmlxgettext instructs wmlerr
and wmlwarn
to
use (or to don’t use) ansi colors when displaying error messages.
Ansi colors, however, will be displayed only on Posix OSes (Linux and Mac) and
not on Windows, which doesn’t support ansi escape codes.
On windows platform, ansi_setEnable
will be interally ignored, and
warning/error messages will be always displayed non-colored.
2.2. wmlerr() and wmlwarn() usage¶
wmlerr
and wmlwarn
functions requires the same parameters and they
will display the error/warning message in the same way.
wmlerr
and wmlwarn
requires those two string parameters:
- finfo: wich is filename:X (where filename is the .cfg/.lua file that contains the problem, and X is the line number of that file)
- message: the message to display
For example, when printing a warning, the warning message will displayed in this way:
warning: filename:x: my_message
If coloured, “warning” will be blue, “filename:x” will be yellow, and warning message will be white. The same colors will be applied to error message, except the world “error” (wich replace the world “warning”) that will be red.
The last difference:
wmlerr
stops wmlxgettext execution;wmlwarn
, instead, does not stop wmlxgettext execution.
2.3. How wmlerr() and wmlwarn() internally works¶
wmlerr
and wmlwarn
internally behave very differently, since they
use python Exceptions / warning system.
wmlwarn
calls warnings.warn
function, wich was previously
overridden by my_showwarning
fuction defined in ./pywmlx/wmlerr.py
module (line 67). Override was possible thank of:
# ./pywmlx/wmlerr.py: 75
warnings.showwarning = my_showwarning
wmlerr
, instead, raise a python exception (that could be checked on
unittest: see Using unittest with wmlerr()) and replace its default
behaviuour with a custom one.
Python exception system, infact, is very useful while debugging code (it can trace both errors and warnings), but needed the ovverrides already explained. This becouse, by default, python shows line code of the script (in this case: line code of wmlxgettext itself) when displaying and warning, and adds tracback infos returned by the script.
Those kind of infos are completely undersired, since the warnings and errors that wmlxgettext should return to the end-user, must say only infos that end-user actually needs (only the errors and messages infos related to WML and Lua files parsed by wmlxgettext)
Overrides made by my_showwarning
(for warns) and by manually raising an
exception with a coustom behaviour (in wmlerr
function, when an error
occurs) ensures that errors and messages will show only the infos that
are actually expected to be announced to the end-user.
Both wmlerr
and wmlwarn
, however, internally use
dualcol_message(finfo, message)
and print_wmlerr(message, iserr)
functions. Those functions will correctly print error/warning message
dualcol_message
and print_wmlerr
will not add colors:
- if current OS is Windows (even if
ansi_setEnabled
isTrue
)- or if
--no-ansi-colors
flag was used in command line (ansi_setEnabled
isFalse
)
2.4. Using unittest with wmlerr()¶
wmlerr
behave differently if the global variable is_utest
(global
variable of module ./pywmlx/wmlerr.py
) is False
(default value) or if
it is True
(must be True
only on a unittest session).
During an unittest session, infact, it is required to change that value from
True
to False
, calling wmlerr_debug()
function from your unittest
module. For this reason, unittest that requires to check wmlerr
and
wmlwarn
should also explicitly add this import:
from pywmlx.wmlerr import wmlerr_debug()
since wmlerr_debug()
is not imported when you simply import pywmlx
.
The function wmlerr_debug()
must then be called somewhere on your unittest
function before using wmlerr()
.
After setting is_utest
to False
calling wmlerr_debug()
, wmlerr
can raise the exception, maintaining the traceback infos required (on unittest
session) to verify that the exception was correctly raised.