diff --git a/modules/miscutil/doc/hacking/miscutil-dateutils.webdoc b/modules/miscutil/doc/hacking/miscutil-dateutils.webdoc
index e539d3dd0..0e81cfa46 100644
--- a/modules/miscutil/doc/hacking/miscutil-dateutils.webdoc
+++ b/modules/miscutil/doc/hacking/miscutil-dateutils.webdoc
@@ -1,180 +1,179 @@
+## -*- mode: html; coding: utf-8; -*-
## $Id$
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: Date library -->
-<!-- WebDoc-Page-Navbar-Name:hacking-miscutil-dateutils -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<WEBURL>/help/hacking">Hacking CDS Invenio</a> > <a class="navtrail" href="<WEBURL>/miscutil-internals">MiscUtil Internals</a> -->
-<!-- WebDoc-Page-Navbar-Select: hacking-miscutil-dateutils> -->
<!-- WebDoc-Page-Revision: $Id$-->
<p>These are the functions and methodologies for date handling in CDS Invenio.</p>
<h2>Contents</h2>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#converting">Converting dates</a></li>
<li><a href="#i18n">Internationalizing parts of dates</a></li>
<li><a href="#generating">Generating GUI elements</a></li>
</ol>
<h2>1. <a name="overview">Overview</a></h2>
Three ways of representing dates are handled by this library:
<dl>
<dt><b>datetext:</b></dt>
<dd>textual format => <code>'YEAR-MONTH-DAY HOUR:MINUTE:SECOND'</code><br />
e.g. <code>'2005-11-16 15:11:44'</code><br />
default value: <code>'0000-00-00 00:00:00'</code><br />
This format is the the one used by current Database for storing dates.
</dd>
<dt><b>datestruct:</b></dt>
<dd>
tuple format => see <a href="http://docs.python.org/lib/module-time.html">Python reference</a> <br />
<code>(YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, WEEKDAY, YEARDAY, DAYLIGHT)</code><br />
e.g. <code>(2005, 11, 16, 15, 11, 44, 2, 320, 0)</code><br />
default value: <code>(0, 0, 0, 0, 0, 0, 0, 0, 0)</code><br />
This format is the one used by python. Time module provides methods for
calculations.
</dd>
<dt><b>dategui:</b></dt>
<dd>
textual format for output => <code>'DAY MONTH YEAR, HOUR:MINUTE'</code><br />
e.g. <code>'16 nov 2005, 15:11'</code>
default value: <code>_("N/A")</code>
</dd>
</dl>
<p>The dateutils python module provides ways of converting between these formats.
The default value is used whenever a date is non-valid (for python, dates before
epoch are unvalid!).</p>
<h2>2. <a name="converting">Converting dates</a></h2>
The functions for conversion are listed below.
<dl>
<dt><b><code>convert_datestruct_to_dategui(datestruct, ln=cdslang)</code></b></dt>
<dd>
<code>(2005, 11, 16, 15, 11, 44, 2, 320, 0) => '16 nov 2005, 15:11'</code><br/>
Month is internationalized
</dd>
<dt><b><code>convert_datestruct_to_datetext(datestruct)</code></b></dt>
<dd>
<code>(2005, 11, 16, 15, 11, 44, 2, 320, 0) => '2005-11-16 15:11:57'</code>
</dd>
<dt><b><code>convert_datetext_to_dategui(datetext, ln=cdslang)</code></b></dt>
<dd>
<code>'2005-11-16 15:11:57' => '16 nov 2005, 15:11'</code><br />
Month is internationalized
</dd>
<dt><b><code>convert_datetext_to_datestruct(datetext)</code></b></dt>
<dd>
<code>'2005-11-16 15:11:57' => (2005, 11, 16, 15, 11, 44, 2, 320, 0)</code>
</dd>
<dt><b><code>get_datestruct(year, month, day)</code></b></dt>
<dd>
<code>year=2005, month=11, day=16 => (2005, 11, 16, 0, 0, 0, 2, 320, -1)</code>
</dd>
<dt><b><code>get_datetext(year, month, day)</code></b></dt>
<dd>
<code>year=2005, month=11, day=16 => '2005-11-16 00:00:00'</code>
</dd>
</dl>
<h2>3. <a name="i18n">Internationalizing parts of dates</a></h2>
The following functions provide means of internationalizing part of dates.
<dl>
<dt>
<b><code>get_i18n_day_name(day_nb, display='short', ln=cdslang)</code></b>
</dt>
<dd>
get the string representation of a weekday, internationalized<br />
<code>
@param day_nb: number of weekday UNIX like. => 0=Sunday<br />
@param ln: language for output<br />
@return the string representation of the day
</code>
</dd>
<dt>
<b><code>get_i18n_month_name(month_nb, display='short', ln=cdslang)</code></b>
</dt>
<dd>
get a non-numeric representation of a month, internationalized.<br />
<code>
@param month_nb: number of month, (1 based!) => 1=jan,..,12=dec<br />
@param ln: language for output<br />
@return the string representation of month
</code>
</dd>
</dl>
<h2>4. <a name="generating">Generating GUI elements</a></h2>
The following functions create HTML fields for date selection:
<dl>
<dt>
<b><code>create_day_selectbox(name, selected_day=0, ln=cdslang)</code></b>
</dt>
<dd>Creates an HTML menu for day selection. (<code>0..31</code> values).<br />
<code>@param name: name of the control (i.e. name of the var you'll get)<br />
@param selected_day: preselect a day. Use 0 for the label 'Day'<br />
@param ln: language of the menu<br />
@return html as string
</code>
</dd>
<dt>
<b><code>create_month_selectbox(name, selected_month=0, ln=cdslang)</code></b>
</dt>
<dd>Creates an HTML menu for month selection. Value of selected field is numeric<br />
<code>@param name: name of the control (your form will be sent with name=value...)<br />
@param selected_month: preselect a month. use 0 for the Label 'Month'<br />
@param ln: language of the menu<br />
@return html as string
</code>
</dd>
<dt>
<b><code>create_year_inputbox(name, value=0)</code></b>
</dt>
<dd>
Creates an HTML field (simple input) for year selection.<br />
<code>@param name: name of the control (i.e. name of the variable you'll get)<br />
@param value: prefilled value (int)<br />
@return html as string
</code>
<dt>
<b><code>create_year_selectbox(name, from_year=-1, length=10, selected_year=0, ln=cdslang)</code></b>
</dt>
<dd>
Creates an HTML menu (dropdownbox) for year selection.<br />
<code>@param name: name of control( i.e. name of the variable you'll get)<br />
@param from_year: year on which to begin. if <0 assume it is current year<br />
@param length: number of items in menu<br />
@param selected_year: initial selected year (if in range), else: label is selected<br />
@param ln: language<br />
@return html as string
</code>
</dl>
diff --git a/modules/miscutil/doc/hacking/miscutil-dbquery.webdoc b/modules/miscutil/doc/hacking/miscutil-dbquery.webdoc
index 04e7b2836..4fccadf5a 100644
--- a/modules/miscutil/doc/hacking/miscutil-dbquery.webdoc
+++ b/modules/miscutil/doc/hacking/miscutil-dbquery.webdoc
@@ -1,177 +1,176 @@
+## -*- mode: html; coding: utf-8; -*-
## $Id$
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: Database access API -->
-<!-- WebDoc-Page-Navbar-Name: hacking-miscutil -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<WEBURL>/help/hacking">Hacking CDS Invenio</a> > <a class="navtrail" href="miscutil-internals">MiscUtil Internals</a> -->
<!-- WebDoc-Page-Navbar-Select: hacking-miscutil-dbquery -->
-
<p>dbquery module handles automatically connection (and reconnection)
to the database and provides the <code>run_sql()</code> function to
perform SQL queries and <code>run_sql_cached()</code> for rarely
changing SELECT queries. It also exports DB exceptions for the client
code to use (see below).
</p>
<h3><code>run_sql()</code> API</h3>
<p><code>run_sql()</code> signature:
<blockquote>
<pre>
def run_sql(sql, param=None, n=0, with_desc=0):
"""Run SQL on the server with PARAM and return result.
@param param: tuple of string params to insert in the query
(see notes below)
@param n: number of tuples in result (0 for unbounded)
@param with_desc: if true, will return a
DB API 7-tuple describing columns in query
@return: if SELECT, SHOW, DESCRIBE statements: tuples of data, followed
by description if parameter
provided
if INSERT: last row id.
else: SQL result as provided by database
When the site is closed for maintenance (as governed by the
config variable CFG_ACCESS_CONTROL_LEVEL_SITE), do not attempt
to run any SQL queries but return empty list immediately.
Useful to be able to have the website up while MySQL database
is down for maintenance, hot copies, table repairs, etc.
In case of problems, exceptions are returned according to the
Python DB API 2.0. The client code can import them from this
file and catch them.
"""
</pre>
</blockquote>
</p>
<p><code>run_sql()</code> normally escapes its parameters if you
pass them in a tuple. Usually the params must use the string format (<code>%s<code>):
<blockquote>
<pre>
from invenio.dbquery import run_sql
[...]
res = run_sql("SELECT id FROM collection WHERE name=%s", (c,))
if res:
colID = res[0][0]
</pre>
</blockquote>
If you want to escape the parameters yourself in the client code, you
could in principle import and make use of the
function <code>escape_string()</code>:
<blockquote>
<pre>
from invenio.dbquery import run_sql, escape_string
[...]
res = run_sql("SELECT id FROM collection WHERE name='%s'" % escape_string(c), None)
if res:
colID = res[0][0]
</pre>
</blockquote>
but beware, this function is not UTF-8 safe! So better do not use it.
</p>
<p>The <code>run_sql()</code> raises Python DB API 2.0 exceptions that
the client code should catch and handle. An example:
<blockquote>
<pre>
from invenio.dbquery import run_sql, OperationalError
[...]
query = "select citation_data from rnkCITATIONDATA"
try:
compressed_citation_dic = run_sql(query)
except OperationalError:
compressed_citation_dic = []
</pre>
</blockquote>
</p>
<p>For the list of all exceptions and the conditions when they are
raised, see <a href="http://www.python.org/dev/peps/pep-0249/">PEP 249</a>.
<h3>Note for handling date types</h3>
<p>There is an incompatibility in handling date types between MySQLdb 0.9 and MySQLdb 1.2 (while using Python 2.2 or 2.3). If a date field is in the received tuple, its format will be:</p>
<ul>
<li>string with MySQLdb 0.9</li>
<li>datetime with MySQLdb 1.2</li>
</ul>
<p>As Python 2.2 doesn't provide <code>datetime</code> class, handling of this
problem should be done for backwards compatibility reasons. The
solution is to force MySQL to convert date to a textual format:</p>
<pre>
SELECT DATE_FORMAT(date_field,'%%Y-%%m-%%d %%H:%%i:%%s') FROM table
</pre>
<p>This conversion will return a datetext format as described in <a href="miscutil-dateutils">dateutils library</a><code>(YEAR-MONTH-DAY HOUR:MINUTE:SECOND)</code>.</p>
<h3><code>run_sql_cached()</code> API</h3>
<p> If you execute a certain SELECT query often, you can
use <code>run_sql_cached()</code> that will cache its result in memory
and return it faster next time. The function signature and usage is
similar to the one known from <code>run_sql()</code>:
<blockquote>
<pre>
def run_sql_cached(sql, param=None, n=0, with_desc=0, affected_tables=[]):
"""
Run the SQL query and cache the SQL command for later reuse.
@param param: tuple of string params to insert in the query
(see notes below)
@param n: number of tuples in result (0 for unbounded)
@param with_desc: if true, will return a
DB API 7-tuple describing columns in query
@param affected_tables is a list of tablenames of affected tables,
used to decide whether we should update the cache or whether we
can return cached result, depending on the last modification time
for corresponding tables. If empty, and if the cached result is
present in the cache, always return the cached result without
recomputing it. (This is useful to speed up queries that operate
on objects that virtually never change, e.g. list of defined
logical fields, that remain usually constant in between Apache
restarts. Note that this may be a bit dangerous as a default for
any query.)
@return the result as provided by run_sql
Note that it is pointless and even wrong to use this function with
SQL commands different from SELECT.
"""
</pre>
</blockquote>
</p>
<h3>Logging SQL Queries</h3>
<p>If you want to investigate some DB related problems, note that you
can uncomment some lines in <code>dbquery.py</code> to obtain detailed
log of every SQL query and its parameters. Look for
string <code>log_sql_query</code> to know more.
</p>
diff --git a/modules/miscutil/doc/hacking/miscutil-errorlib.webdoc b/modules/miscutil/doc/hacking/miscutil-errorlib.webdoc
index c4e1da57c..9ccc2a251 100644
--- a/modules/miscutil/doc/hacking/miscutil-errorlib.webdoc
+++ b/modules/miscutil/doc/hacking/miscutil-errorlib.webdoc
@@ -1,320 +1,319 @@
+## -*- mode: html; coding: utf-8; -*-
## $Id$
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: Error Library -->
-<!-- WebDoc-Page-Navbar-Name: hacking-miscutil -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<WEBURL>/help/hacking">Hacking CDS Invenio</a> > <a class="navtrail" href="miscutil-internals">MiscUtil Internals</a> -->
-<!-- WebDoc-Page-Navbar-Select: hacking-miscutil-error-management -->
<!-- WebDoc-Page-Revision: $Id$-->
<p>
These are the functions and methodologies for error handling in CDS Invenio.
</p>
<h2>Contents</h2>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#creating">Creating errors</a></li>
<li><a href="#using">Using error library</a></li>
<li><a href="#troubleshooting">Troubleshooting</a></li>
</ol>
<h2>1. <a name="overview">Overview</a></h2>
<p>This API handles two concepts: Errors and Warnings.
<p>An error is an unexpected behavior that leads to the stopping of current process.
Discussing of web pages, errors should be displayed by instead of the
requested page. Errors are logged into <code>cds-invenio/var/log/cds-invenio.err</code>.
Errors can be logged with client information and a tracestack.</p>
<p>A warning is an unexpected behavior that can be ignored. Warnings are logged into
<code>cds-invenio/var/log/cds-invenio.log</code> with just the warning message.</p>
<p>Errors and warnings should be internationalized (see <a href="#i18n">below</a>).</p>
<h2>2. <a name="creating">Creating errors</a></h2>
<h3>2.1 Configuration file</h3>
<p>Every module should create a file containing error definitions, warning
definitions, variables avoiding "magic" number or strings, etc.</p>
<p>This file has to be named against a convention:</p>
<pre>
<module-name>_config.py
</pre>
<p>e.g. <code>webmessage_config.py</code> for the WebMessage module.</p>
<h3>2.2 Dictionaries of errors</h3>
<p>Errors and warnings are eventually stored into dictionaries. The dictionaries
are to be named against the following convention:</p>
<pre>
CFG_<MODULENAME>_ERROR_MESSAGES and
CFG_<MODULENAME>_WARNING_MESSAGES
</pre>
<p>These two dictionaries (one can choose to implement only one if he doesn't
need warnings, for example) contain an error-name -> displayable message
association.</p>
<p>Errors are to be named against the following convention:</p>
<pre>
ERR_<MODULE-NAME>_ERROR_NAME
</pre>
<p>Please note the use of uppercase.</p>
<p>Warnings can also be named as errors if convenient, and so have to
follow one of these rules:</p>
<pre>
WRN_<MODULE-NAME>_WARNING_NAME or
ERR_<MODULE-NAME>_WARNING_NAME
</pre>
<p>The associated message can obviously contain substituted variables like <code>%s</code>, <code>%d</code>...
<h3><a name="i18n">Internationalization</a></h3>
<p>Errors should also be internationalized. As the config file cannot receive
parameters, this is done by the error handling library. The convenient way that has
been chosen is to nest the classical <code>_()</code> function inside the string.</p>
<p>An internationalized error message should look like this:</p>
<pre>
'_("Internationalized error (%s) message")'
</pre>
<p>A complete example of correct dictionary is given below:</p>
<pre>
CFG_WEBCOMMENT_ERROR_MESSAGES =
{ 'ERR_WEBCOMMENT_RECID_INVALID' : '_("%i is an invalid record ID")',
'ERR_WEBCOMMENT_RECID_NAN' : '_("Record ID %i is not a number")',
'ERR_WEBCOMMENT_UID_INVALID' : '_("%i is an invalid user ID")'
}
</pre>
<h2>3. <a name="using">Using error library</a></h2>
<h3>3.1 From a web interface</h3>
<p>When displaying a page, the <code>modules/webstyle/lib/webpage.py</code> python module should
be used. This module provides a <code>page()</code> function, convenient for webpage output,
which can handle errors (display and log).<br />
A call to this function should use the following arguments, assuming that language
information is stored in a variable called <code>ln</code>, and request information
are stored in req (will be used for IP logging, for example):</p>
<pre>
page(...,
req=req,
language=ln,
errors=error_list,
warnings=warnings_list,
...)
</pre>
<p>list of errors and warnings are behaving the same way. They are lists of tuples:</p>
<pre>
[(error_name, param1, ..., paramN), ...]
</pre>
<p>The params are used to represent substitued values in messages. For example if
you want to throw one of the errors above, error_list should look like this:</p>
<pre>
error_list = [('ERR_WEBCOMMENT_RECID_INVALID', 123456)]
</pre>
<h4>Example</h4>
<p>Business logic should be separated from web interface. We consider three files in the
following (real) example:
<ol>
<li><code>webmessage_webinterface.py</code>, which is the page as viewed by a browser,</li>
<li><code>webmessage.py</code>, which contains the business logic,</li>
<li><code>webmessage_config</code>, which contains error definitions</li>
</ol>
<p>In this example, a user tries to read a message. We must ensure he doesn't
read another message, and that this message really exist in the system. For
a more convenient reading, some (non error-related) parts of code have been suppressed.</p>
<h5>webmessage_config.py</h5>
<pre>
# error messages. (should not happen, except in case of reload, or url altering)
CFG_WEBMESSAGE_ERROR_MESSAGES = \
{ 'ERR_WEBMESSAGE_NOTOWNER': '_("This message is not in your mailbox")',
'ERR_WEBMESSAGE_NONICKNAME':'_("No nickname or user for uid #%s")',
'ERR_WEBMESSAGE_NOMESSAGE': '_("This message doesn\'t exist")'
}
</pre>
<h5>webmessage.py: business logic</h5>
<pre>
from invenio.webmessage_config import CFG_WEBMESSAGE_ERROR_MESSAGES
def perform_request_display_msg(uid, msgid, ln=cdslang):
uid = wash_url_argument(uid, 'int')
msgid = wash_url_argument(msgid, 'int')
ln = wash_language(ln)
errors = []
warnings = []
body = ""
if (check_user_owns_message(uid, msgid) == 0):
# The user doesn't own this message
errors.append(('ERR_WEBMESSAGE_NOTOWNER',))
else:
(msg_id, ...) = get_message(uid, msgid)
if (msg_id == ""):
# The message exists in table user_msgMESSAGE
# but not in table msgMESSAGE => table inconsistency
errors.append(('ERR_WEBMESSAGE_NOMESSAGE',))
else:
body = webmessage_templates.tmpl_display_msg( ... )
return (body, errors, warnings)
</pre>
<h5>webmessage_webinterface.py: web interface</h5>
<pre>
from invenio.webpage import page
from invenio.webmessage import perform_request_display_msg
def display_msg(req, msgid=-1, ln=cdslang):
_ = gettext_set_language(ln)
# Generate content
(body, errors, warnings) = perform_request_display_msg(uid, msgid, ln)
title = _("Read a message")
return page(title = title,
body = body,
navtrail = get_navtrail(ln, title),
uid = uid,
lastupdated = __lastupdated__,
req = req,
language = ln,
errors = errors,
warnings = warnings)
</pre>
<h3>3.2 From a command line interface</h3>
<p>The following functions can be useful (see source code for other functions):</p>
<pre>
get_msgs_for_code_list(code_list, stream='error', ln=cdslang)
Returns formatted strings for the given errors
@param code_list: list of tuples [(err_name, arg1, ..., argN), ...]
@param stream: 'error' or 'warning'
@return list of tuples of length 2 [('ERR_...', err_msg), ...]
if code_list empty, will return None.
if errors retrieving error messages, will append an error to
the list
register_errors(errors_or_warnings_list, stream, req=None)
log errors to invenio.err and warnings to invenio.log
errors will be logged with client information (if req is given)
and a tracestack
warnings will be logged with just the warning message
@param errors_or_warnings_list: list of tuples (err_name, err_msg)
@param stream: 'error' or 'warning'
@param req = mod_python request
@return integer 1 if successfully wrote to stream, integer 0 if not
will append another error to errors_list if unsuccessful
send_error_report_to_admin(header, url, time, browser, client,
error, sys_error, traceback)
Sends an email to the admin with client info and tracestack
</pre>
<h4>Example</h4>
<p>In the following example, two files are used:</p>
<ol>
<li><code>webmessage_config</code>, containing error messages</li>
<li><code>webmessage_example_bin.py</code>, containing business logic</li>
</ol>
<p>Scenario: a function receives an error and wants to register it only if it is not a
messaging error</p>
<h5>webmessage_config.py</h5>
<pre>
# error messages. (should not happen, except in case of reload, or url altering)
CFG_WEBMESSAGE_ERROR_MESSAGES = \
{ 'ERR_WEBMESSAGE_NOTOWNER': '_("This message is not in your mailbox")',
'ERR_WEBMESSAGE_NONICKNAME':'_("No nickname or user for uid #%s")',
'ERR_WEBMESSAGE_NOMESSAGE': '_("This message doesn\'t exist")'
}
</pre>
<h5>webmessage_example_bin.py</h5>
<pre>
from invenio.webmessage_config import CFG_WEBMESSAGE_ERROR_MESSAGES
from invenio.errorlib import get_msgs_for_code_list, register_errors
def handle_error(error):
errorlist = get_msgs_for_code_list([error])
# error is a tuple of error name, arguments => we only need the name
if CFG_WEBMESSAGE_ERROR_MESSAGES[error[0]]:
print("Error in webmessage: %s" % errorlist[0][1])
else:
for error in errorlist:
print("Error: %s" % error[1])
register_errors(errorlist, 'error')
</pre>
<h2>4. <a name="troubleshooting">Troubleshooting</a></h2>
<p>MiscUtil can generate errors. See miscutil_config.py for a complete list.
One can see below some usual errors and their solutions:</p>
<dl>
<dt><b><code>ERR_MISCUTIL_IMPORT_ERROR</code></b></dt>
<dd>The <code><module-name>_config.py</code> file has not been found. Check it
has the correct name and is deployed.<br />
Check that the error is named following this pattern:
<pre>
WRN_<MODULE-NAME>_WARNING_NAME or
ERR_<MODULE-NAME>_WARNING_NAME
</pre>
</dd>
<dt><b><code>ERR_MISCUTIL_NO_DICT</code></b></dt>
<dd>No dictionary could be found in <code><module-name>_config.py</code>. Check
that your dictionary is correctly named:
<pre>
CFG_<MODULENAME>_ERROR_MESSAGES
</pre>
You could also have inverted errors and warnings if only one dictionary was provided.<br/>
This can also happen when using direct API if the <code>stream</code> argument is misspelled.
</dd>
<dt><b><code>ERR_MISCUTIL_NO_MESSAGE_IN_DICT</code></b></dt>
<dd>A dictionary was found but not the error in it. You probably misspelled
<code>error_name</code>, or inverted errors and warnings dictionaries.
</dd>
<dt><b><code>ERR_MISCUTIL_UNDEFINED_ERROR</code></b></dt>
<dd>The library couldn't guess the name of module. Check that the error name is beginning
with <code>ERR_MODULE-NAME_</code> or <code>WRN_MODULE-NAME_</code>. This library uses
underscores as separators to guess module name.
</dd>
<dt><b><code>ERR_MISCUTIL_TOO_MANY_ARGUMENT</code></b></dt>
<dd>As the library was rendering the display of error, a surnumerous text substitute was
found (surnumerous are ignored for final rendering, and this error is appened to list of errors):
<pre>
# Module knights:
'ERR_KNIGHTS': '_("We are the knights who say %s!")'
errors = ('ERR_KNIGHTS', 'ni', 'ni')
</pre>
</dd>
<dt><b><code>ERR_MISCUTIL_TOO_FEW_ARGUMENT</code></b></dt>
<dd>Not enough arguments (text substitutes) were given for an error. Missing ones are
replaced by <code>'???'</code>:
<pre>
# Module knights
'ERR_KNIGHTS': '_("We are the knights who say %s! We demand a %s")'
errors = ('ERR_KNIGHTS', 'ni') # so, where is the shrubbery??
</pre>
</dd>
<dt><b><code>ERR_MISCUTIL_BAD_ARGUMENT_TYPE</code></b></dt>
<dd>Your arguments (text substitutes) did not match with the error declaration<br />
e.g. inversion between integer (<code>%i</code>) and string (<code>%s</code>)
</dd>
</dl>
diff --git a/modules/miscutil/doc/hacking/miscutil-internals.webdoc b/modules/miscutil/doc/hacking/miscutil-internals.webdoc
index 46650776d..99d3cd98b 100644
--- a/modules/miscutil/doc/hacking/miscutil-internals.webdoc
+++ b/modules/miscutil/doc/hacking/miscutil-internals.webdoc
@@ -1,39 +1,39 @@
+## -*- mode: html; coding: utf-8; -*-
## $Id$
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: MiscUtil Internals -->
-<!-- WebDoc-Page-Navbar-Name: hacking-miscutil -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<WEBURL>/help/hacking">Hacking CDS Invenio</a> -->
-<!-- WebDoc-Page-Navbar-Select: hacking-miscutil-index -->
+<!-- WebDoc-Page-Revision: $Id$-->
This page summarizes all the information suitable to dig inside
the MiscUtil internals.
<blockquote>
<dl>
<dt><a href="miscutil-dbquery">Database access API</a> </dt>
<dd>Explains how to access CDS Invenio database from your Python programs.</dd>
<dt><a href="miscutil-errorlib">Error handling library</a> </dt>
<dd>Explains how to create errors and warnings and how to manage them.</dd>
<dt><a href="miscutil-dateutils">Date handling library</a> </dt>
<dd>Explains how to handle dates in CDS Invenio. All mentioned functions are represented with signature and additional explanations.</dd>
</dl>
</blockquote>