def parse(docstring, markup='plaintext', errors=None, **options):
"""
Parse the given docstring, and use it to construct a
C{ParsedDocstring}. If any fatal C{ParseError}s are encountered
while parsing the docstring, then the docstring will be rendered
as plaintext, instead.
@type docstring: C{string}
@param docstring: The docstring to encode.
@type markup: C{string}
@param markup: The name of the markup language that is used by
the docstring. If the markup language is not supported, then
the docstring will be treated as plaintext. The markup name
is case-insensitive.
@param errors: A list where any errors generated during parsing
will be stored. If no list is specified, then fatal errors
will generate exceptions, and non-fatal errors will be
ignored.
@type errors: C{list} of L{ParseError}
@rtype: L{ParsedDocstring}
@return: A L{ParsedDocstring} that encodes the contents of
C{docstring}.
@raise ParseError: If C{errors} is C{None} and an error is
encountered while parsing.
"""
# Initialize errors list.
raise_on_error = (errors is None)
if errors == None: errors = []
# Normalize the markup language name.
markup = markup.lower()
# Is the markup language valid?
if not re.match(r'\w+', markup):
_parse_warn('Bad markup language name %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Is the markup language supported?
if markup not in _markup_language_registry:
_parse_warn('Unsupported markup language %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Get the parse function.
parse_docstring = _markup_language_registry[markup]
# If it's a string, then it names a function to import.
if isinstance(parse_docstring, basestring):
try:
exec('from %s import parse_docstring' % parse_docstring)
except ImportError, e:
_parse_warn('Error importing %s for markup language %s: %s' %
(parse_docstring, markup, e))
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
_markup_language_registry[markup] = parse_docstring
def parse(docstring, markup='plaintext', errors=None, **options):
"""
Parse the given docstring, and use it to construct a
C{ParsedDocstring}. If any fatal C{ParseError}s are encountered
while parsing the docstring, then the docstring will be rendered
as plaintext, instead.
@type docstring: C{string}
@param docstring: The docstring to encode.
@type markup: C{string}
@param markup: The name of the markup language that is used by
the docstring. If the markup language is not supported, then
the docstring will be treated as plaintext. The markup name
is case-insensitive.
@param errors: A list where any errors generated during parsing
will be stored. If no list is specified, then fatal errors
will generate exceptions, and non-fatal errors will be
ignored.
@type errors: C{list} of L{ParseError}
@rtype: L{ParsedDocstring}
@return: A L{ParsedDocstring} that encodes the contents of
C{docstring}.
@raise ParseError: If C{errors} is C{None} and an error is
encountered while parsing.
"""
# Initialize errors list.
raise_on_error = (errors is None)
if errors == None: errors = []
# Normalize the markup language name.
markup = markup.lower()
# Is the markup language valid?
if not re.match(r'\w+', markup):
_parse_warn('Bad markup language name %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Is the markup language supported?
if markup not in _markup_language_registry:
_parse_warn('Unsupported markup language %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Get the parse function.
parse_docstring = _markup_language_registry[markup]
# If it's a string, then it names a function to import.
if isinstance(parse_docstring, basestring):
try: exec('from %s import parse_docstring' % parse_docstring)
except ImportError, e:
_parse_warn('Error importing %s for markup language %s: %s' %
(parse_docstring, markup, e))
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
_markup_language_registry[markup] = parse_docstring
_markup_language_registry[markup] = parse_docstring
# Keep track of which markup languages have been used so far.
MARKUP_LANGUAGES_USED.add(markup)
# Parse the docstring.
try:
parsed_docstring = parse_docstring(docstring, errors, **options)
except KeyboardInterrupt:
raise
except Exception, e:
if epydoc.DEBUG: raise
log.error('Internal error while parsing a docstring: %s; '
'treating docstring as plaintext' % e)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Check for fatal errors.
fatal_errors = [e for e in errors if e.is_fatal()]
if fatal_errors and raise_on_error: raise fatal_errors[0]
if fatal_errors:
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
return parsed_docstring
# only issue each warning once:
_parse_warnings = {}
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
_markup_language_registry[markup] = parse_docstring
# Keep track of which markup languages have been used so far.
MARKUP_LANGUAGES_USED.add(markup)
# Parse the docstring.
try: parsed_docstring = parse_docstring(docstring, errors, **options)
except KeyboardInterrupt: raise
except Exception, e:
if epydoc.DEBUG: raise
log.error('Internal error while parsing a docstring: %s; '
'treating docstring as plaintext' % e)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Check for fatal errors.
fatal_errors = [e for e in errors if e.is_fatal()]
if fatal_errors and raise_on_error: raise fatal_errors[0]
if fatal_errors:
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
return parsed_docstring
# only issue each warning once:
_parse_warnings = {}
def _parse_warn(estr):
"""
Print a warning message. If the given error has already been
def parse(docstring, markup='plaintext', errors=None, **options):
"""
Parse the given docstring, and use it to construct a
C{ParsedDocstring}. If any fatal C{ParseError}s are encountered
while parsing the docstring, then the docstring will be rendered
as plaintext, instead.
@type docstring: C{string}
@param docstring: The docstring to encode.
@type markup: C{string}
@param markup: The name of the markup language that is used by
the docstring. If the markup language is not supported, then
the docstring will be treated as plaintext. The markup name
is case-insensitive.
@param errors: A list where any errors generated during parsing
will be stored. If no list is specified, then fatal errors
will generate exceptions, and non-fatal errors will be
ignored.
@type errors: C{list} of L{ParseError}
@rtype: L{ParsedDocstring}
@return: A L{ParsedDocstring} that encodes the contents of
C{docstring}.
@raise ParseError: If C{errors} is C{None} and an error is
encountered while parsing.
"""
# Initialize errors list.
raise_on_error = (errors is None)
if errors == None: errors = []
# Normalize the markup language name.
markup = markup.lower()
# Is the markup language valid?
if not re.match(r'\w+', markup):
_parse_warn('Bad markup language name %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Is the markup language supported?
if markup not in _markup_language_registry:
_parse_warn('Unsupported markup language %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Get the parse function.
parse_docstring = _markup_language_registry[markup]
# If it's a string, then it names a function to import.
if isinstance(parse_docstring, str):
try:
exec('from %s import parse_docstring' % parse_docstring)
except ImportError as e:
_parse_warn('Error importing %s for markup language %s: %s' %
(parse_docstring, markup, e))
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
_markup_language_registry[markup] = parse_docstring
# Keep track of which markup languages have been used so far.
MARKUP_LANGUAGES_USED.add(markup)
# Parse the docstring.
try:
parsed_docstring = parse_docstring(docstring, errors, **options)
except KeyboardInterrupt:
raise
except Exception as e:
if epydoc.DEBUG: raise
log.error('Internal error while parsing a docstring: %s; '
'treating docstring as plaintext' % e)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Check for fatal errors.
fatal_errors = [e for e in errors if e.is_fatal()]
if fatal_errors and raise_on_error: raise fatal_errors[0]
if fatal_errors:
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
return parsed_docstring
def parse(docstring, markup='plaintext', errors=None, **options):
"""
Parse the given docstring, and use it to construct a
C{ParsedDocstring}. If any fatal C{ParseError}s are encountered
while parsing the docstring, then the docstring will be rendered
as plaintext, instead.
@type docstring: C{string}
@param docstring: The docstring to encode.
@type markup: C{string}
@param markup: The name of the markup language that is used by
the docstring. If the markup language is not supported, then
the docstring will be treated as plaintext. The markup name
is case-insensitive.
@param errors: A list where any errors generated during parsing
will be stored. If no list is specified, then fatal errors
will generate exceptions, and non-fatal errors will be
ignored.
@type errors: C{list} of L{ParseError}
@rtype: L{ParsedDocstring}
@return: A L{ParsedDocstring} that encodes the contents of
C{docstring}.
@raise ParseError: If C{errors} is C{None} and an error is
encountered while parsing.
"""
# Initialize errors list.
raise_on_error = (errors is None)
if errors == None: errors = []
# Normalize the markup language name.
markup = markup.lower()
# Is the markup language valid?
if not re.match(r'\w+', markup):
_parse_warn('Bad markup language name %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Is the markup language supported?
if markup not in _markup_language_registry:
_parse_warn('Unsupported markup language %r. Treating '
'docstrings as plaintext.' % markup)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Get the parse function.
parse_docstring = _markup_language_registry[markup]
# If it's a string, then it names a function to import.
if isinstance(parse_docstring, str):
try: exec('from %s import parse_docstring' % parse_docstring)
except ImportError as e:
_parse_warn('Error importing %s for markup language %s: %s' %
(parse_docstring, markup, e))
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
_markup_language_registry[markup] = parse_docstring
# Keep track of which markup languages have been used so far.
MARKUP_LANGUAGES_USED.add(markup)
# Parse the docstring.
try: parsed_docstring = parse_docstring(docstring, errors, **options)
except KeyboardInterrupt: raise
except Exception as e:
if epydoc.DEBUG: raise
log.error('Internal error while parsing a docstring: %s; '
'treating docstring as plaintext' % e)
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
# Check for fatal errors.
fatal_errors = [e for e in errors if e.is_fatal()]
if fatal_errors and raise_on_error: raise fatal_errors[0]
if fatal_errors:
import epydoc.markup.plaintext as plaintext
return plaintext.parse_docstring(docstring, errors, **options)
return parsed_docstring
