# lxml.doctestcompare module

lxml-based doctest output comparison.

Note: normally, you should just import the lxml.usedoctest and lxml.html.usedoctest modules from within a doctest, instead of this one:

    >>> import lxml.usedoctest # for XML output

    >>> import lxml.html.usedoctest # for HTML output

To use this module directly, you must call `lxmldoctest.install()`, which will cause doctest to use this in all subsequent calls.

This changes the way output is checked and comparisons are made for XML or HTML-like content.

XML or HTML content is noticed because the example starts with `<` (it’s HTML if it starts with `<html`). You can also use the `PARSE_HTML` and `PARSE_XML` flags to force parsing.

Some rough wildcard-like things are allowed. Whitespace is generally ignored (except in attributes). In text (attributes and text in the body) you can use `...` as a wildcard. In an example it also matches any trailing tags in the element, though it does not match leading tags. You may create a tag `<any>` or include an `any` attribute in the tag. An `any` tag matches any tag, while the attribute matches any and all attributes.

When a match fails, the reformatted example and gotten text is displayed (indented), and a rough diff-like output is given. Anything marked with `+` is in the output but wasn’t supposed to be, and similarly `-` means its in the example but wasn’t in the output.

You can disable parsing on one line with `# doctest:+NOPARSE_MARKUP`

class lxml.doctestcompare.LHTMLOutputChecker

  Bases: `LXMLOutputChecker`

  _do_a_fancy_diff(want, got, optionflags)
  _looks_like_markup(s)
  _toAscii(s)

    Convert string to hex-escaped ASCII string.

  check_output(want, got, optionflags)

    Return True iff the actual output from an example (got) matches the expected output (want). These strings are always considered to match if they are identical; but depending on what option flags the test runner is using, several non-exact match types are also possible. See the documentation for TestRunner for more information about option flags.

  collect_diff(want, got, html, indent)
  collect_diff_end_tag(want, got)
  collect_diff_tag(want, got)
  collect_diff_text(want, got, strip=True)
  compare_docs(want, got)
  format_doc(doc, html, indent, prefix='')
  format_end_tag(el)
  format_tag(el)
  format_text(text, strip=True)
  get_default_parser()
  get_parser(want, got, optionflags)
  html_empty_tag(el, html=True)
  output_difference(example, got, optionflags)

    Return a string describing the differences between the expected output for a given example (example) and the actual output (got). optionflags is the set of option flags used to compare want and got.

  tag_compare(want, got)
  text_compare(want, got, strip)
  empty_tags = ('param', 'img', 'area', 'br', 'basefont', 'input', 'base', 'meta', 'link', 'col')

class lxml.doctestcompare.LXMLOutputChecker

  Bases: `OutputChecker`

  _do_a_fancy_diff(want, got, optionflags)
  _looks_like_markup(s)
  _toAscii(s)

    Convert string to hex-escaped ASCII string.

  check_output(want, got, optionflags)

    Return True iff the actual output from an example (got) matches the expected output (want). These strings are always considered to match if they are identical; but depending on what option flags the test runner is using, several non-exact match types are also possible. See the documentation for TestRunner for more information about option flags.

  collect_diff(want, got, html, indent)
  collect_diff_end_tag(want, got)
  collect_diff_tag(want, got)
  collect_diff_text(want, got, strip=True)
  compare_docs(want, got)
  format_doc(doc, html, indent, prefix='')
  format_end_tag(el)
  format_tag(el)
  format_text(text, strip=True)
  get_default_parser()
  get_parser(want, got, optionflags)
  html_empty_tag(el, html=True)
  output_difference(example, got, optionflags)

    Return a string describing the differences between the expected output for a given example (example) and the actual output (got). optionflags is the set of option flags used to compare want and got.

  tag_compare(want, got)
  text_compare(want, got, strip)
  empty_tags = ('param', 'img', 'area', 'br', 'basefont', 'input', 'base', 'meta', 'link', 'col')

class lxml.doctestcompare._RestoreChecker(dt_self, old_checker, new_checker, check_func, clone_func, del_module)

  Bases: `object`

  call_super(*args, **kw)
  install_clone()
  install_dt_self()
  uninstall_clone()
  uninstall_dt_self()
  uninstall_module()

lxml.doctestcompare._find_doctest_frame()

lxml.doctestcompare.html_fromstring(html)

lxml.doctestcompare.install(html=False)

  Install doctestcompare for all future doctests.

  If html is true, then by default the HTML parser will be used; otherwise the XML parser is used.

lxml.doctestcompare.norm_whitespace(v)

lxml.doctestcompare.strip(v)

lxml.doctestcompare.temp_install(html=False, del_module=None)

  Use this inside a doctest to enable this checker for this doctest only.

  If html is true, then by default the HTML parser will be used; otherwise the XML parser is used.