def report_errors(api_doc, docindex, parse_errors, field_warnings):
"""A helper function for L{parse_docstring()} that reports any
markup warnings and field warnings that we encountered while
processing C{api_doc}'s docstring."""
if not parse_errors and not field_warnings: return
# Get the name of the item containing the error, and the
# filename of its containing module.
name = api_doc.canonical_name
module = api_doc.defining_module
if module is not UNKNOWN and module.filename not in (None, UNKNOWN):
try:
filename = py_src_filename(module.filename)
except:
filename = module.filename
else:
filename = '??'
# [xx] Don't report markup errors for standard builtins.
# n.b. that we must use 'is' to compare pyvals here -- if we use
# 'in' or '==', then a user __cmp__ method might raise an
# exception, or lie.
if isinstance(api_doc, ValueDoc) and api_doc != module:
if module not in (None, UNKNOWN):
return
for builtin_val in builtins.__dict__.values():
if builtin_val is api_doc.pyval:
return
# Get the start line of the docstring containing the error.
startline = api_doc.docstring_lineno
if startline in (None, UNKNOWN):
startline = introspect_docstring_lineno(api_doc)
if startline in (None, UNKNOWN):
startline = None
# Display a block header.
header = 'File %s, ' % filename
if startline is not None:
header += 'line %d, ' % startline
header += 'in %s' % name
log.start_block(header)
# Display all parse errors. But first, combine any errors
# with duplicate description messages.
if startline is None:
# remove dups, but keep original order:
dups = {}
for error in parse_errors:
message = error.descr()
if message not in dups:
log.docstring_warning(message)
dups[message] = 1
else:
# Combine line number fields for dup messages:
messages = {} # maps message -> list of linenum
for error in parse_errors:
error.set_linenum_offset(startline)
message = error.descr()
messages.setdefault(message, []).append(error.linenum())
message_items = sorted(messages.items(), key=lambda a: min(a[1]))
for message, linenums in message_items:
linenums = [n for n in linenums if n is not None]
if len(linenums) == 0:
log.docstring_warning(message)
elif len(linenums) == 1:
log.docstring_warning("Line %s: %s" % (linenums[0], message))
else:
linenums = ', '.join(['%s' % l for l in linenums])
log.docstring_warning("Lines %s: %s" % (linenums, message))
# Display all field warnings.
for warning in field_warnings:
log.docstring_warning(warning)
# End the message block.
log.end_block()
def report_errors(api_doc, docindex, parse_errors, field_warnings):
"""A helper function for L{parse_docstring()} that reports any
markup warnings and field warnings that we encountered while
processing C{api_doc}'s docstring."""
if not parse_errors and not field_warnings: return
# Get the name of the item containing the error, and the
# filename of its containing module.
name = api_doc.canonical_name
module = api_doc.defining_module
if module is not UNKNOWN and module.filename not in (None, UNKNOWN):
try: filename = py_src_filename(module.filename)
except: filename = module.filename
else:
filename = '??'
# [xx] Don't report markup errors for standard builtins.
# n.b. that we must use 'is' to compare pyvals here -- if we use
# 'in' or '==', then a user __cmp__ method might raise an
# exception, or lie.
if isinstance(api_doc, ValueDoc) and api_doc != module:
if module not in (None, UNKNOWN) and module.pyval is exceptions:
return
for builtin_val in __builtin__.__dict__.values():
if builtin_val is api_doc.pyval:
return
# Get the start line of the docstring containing the error.
startline = api_doc.docstring_lineno
if startline in (None, UNKNOWN):
startline = introspect_docstring_lineno(api_doc)
if startline in (None, UNKNOWN):
startline = None
# Display a block header.
header = 'File %s, ' % filename
if startline is not None:
header += 'line %d, ' % startline
header += 'in %s' % name
log.start_block(header)
# Display all parse errors. But first, combine any errors
# with duplicate description messages.
if startline is None:
# remove dups, but keep original order:
dups = {}
for error in parse_errors:
message = error.descr()
if message not in dups:
log.docstring_warning(message)
dups[message] = 1
else:
# Combine line number fields for dup messages:
messages = {} # maps message -> list of linenum
for error in parse_errors:
error.set_linenum_offset(startline)
message = error.descr()
messages.setdefault(message, []).append(error.linenum())
message_items = messages.items()
message_items.sort(lambda a,b:cmp(min(a[1]), min(b[1])))
for message, linenums in message_items:
linenums = [n for n in linenums if n is not None]
if len(linenums) == 0:
log.docstring_warning(message)
elif len(linenums) == 1:
log.docstring_warning("Line %s: %s" % (linenums[0], message))
else:
linenums = ', '.join(['%s' % l for l in linenums])
log.docstring_warning("Lines %s: %s" % (linenums, message))
# Display all field warnings.
for warning in field_warnings:
log.docstring_warning(warning)
# End the message block.
log.end_block()