Package lxml :: Package html |
[hide private]
[frames] | no frames]

# Source Code for Package lxml.html

       1  """The ``lxml.html`` tool set for HTML handling.
       2  """
       3
       4  import threading
       5  import re
       6  try:
       7      from urlparse import urljoin
       8  except ImportError:
       9      # Python 3
      10      from urllib.parse import urljoin
      11  import copy
      12  from lxml import etree
      13  from lxml.html import defs
      14  from lxml import cssselect
      15  from lxml.html._setmixin import SetMixin
      16  try:
      17      from UserDict import DictMixin
      18  except ImportError:
      19      # DictMixin was introduced in Python 2.4
      20      from lxml.html._dictmixin import DictMixin
      21  try:
      22      set
      23  except NameError:
      24      # Python 2.3
      25      from sets import Set as set
      26  try:
      27      bytes = __builtins__["bytes"]
      28  except (KeyError, NameError):
      29      # Python < 2.6
      30      bytes = str
      31  try:
      32      unicode = __builtins__["unicode"]
      33  except (KeyError, NameError):
      34      # Python 3
      35      unicode = str
      36  try:
      37      basestring = __builtins__["basestring"]
      38  except (KeyError, NameError):
      39      # Python 3
      40      basestring = (str, bytes)
      41
      42 -def __fix_docstring(s):
      43      if not s:
      44          return s
      45      import sys
      46      if sys.version_info[0] >= 3:
      47          sub = re.compile(r"^(\s*)u'", re.M).sub
      48      else:
      49          sub = re.compile(r"^(\s*)b'", re.M).sub
      50      return sub(r"\1'", s)
      51
      52  __all__ = [
      53      'document_fromstring', 'fragment_fromstring', 'fragments_fromstring', 'fromstring',
      54      'tostring', 'Element', 'defs', 'open_in_browser', 'submit_form',
      55      'find_rel_links', 'find_class', 'make_links_absolute',
      56      'resolve_base_href', 'iterlinks', 'rewrite_links', 'open_in_browser', 'parse']
      57
      58  XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml"
      59
      60  _rel_links_xpath = etree.XPath("descendant-or-self::a[@rel]|descendant-or-self::x:a[@rel]",
      61                                 namespaces={'x':XHTML_NAMESPACE})
      62  _options_xpath = etree.XPath("descendant-or-self::option|descendant-or-self::x:option",
      63                               namespaces={'x':XHTML_NAMESPACE})
      64  _forms_xpath = etree.XPath("descendant-or-self::form|descendant-or-self::x:form",
      65                             namespaces={'x':XHTML_NAMESPACE})
      66  #_class_xpath = etree.XPath(r"descendant-or-self::*[regexp:match(@class, concat('\b', $class_name, '\b'))]", {'regexp': 'http://exslt.org/regular-expressions'})
      67  _class_xpath = etree.XPath("descendant-or-self::*[@class and contains(concat(' ', normalize-space(@class), ' '), concat(' ', $class_name, ' '))]")
      68  _id_xpath = etree.XPath("descendant-or-self::*[@id=$id]")
      69  _collect_string_content = etree.XPath("string()")
      70  _css_url_re = re.compile(r'url\(('+'["][^"]*["]|'+"['][^']*[']|"+r'[^)]*)\)', re.I)
      71  _css_import_re = re.compile(r'@import "(.*?)"')
      72  _label_xpath = etree.XPath("//label[@for=$id]|//x:label[@for=$id]",
      73                             namespaces={'x':XHTML_NAMESPACE})
      74  _archive_re = re.compile(r'[^ ]+')
      75
      76 -def _unquote_match(s, pos):
      77      if s[:1] == '"' and s[-1:] == '"' or s[:1] == "'" and s[-1:] == "'":
      78          return s[1:-1], pos+1
      79      else:
      80          return s,pos
      81
      82 -def _transform_result(typ, result):
      83      """Convert the result back into the input type.
      84      """
      85      if issubclass(typ, bytes):
      86          return tostring(result, encoding='utf-8')
      87      elif issubclass(typ, unicode):
      88          return tostring(result, encoding=unicode)
      89      else:
      90          return result
      91
      92 -def _nons(tag):
      93      if isinstance(tag, basestring):
      94          if tag[0] == '{' and tag[1:len(XHTML_NAMESPACE)+1] == XHTML_NAMESPACE:
      95              return tag.split('}')[-1]
      96      return tag
      97
      98 -class HtmlMixin(object):
      99
     100 -    def base_url(self):
     101          """
     102          Returns the base URL, given when the page was parsed.
     103
     104          Use with ``urlparse.urljoin(el.base_url, href)`` to get
     105          absolute URLs.
     106          """
     107          return self.getroottree().docinfo.URL
     108      base_url = property(base_url, doc=base_url.__doc__)
     109
     110 -    def forms(self):
     111          """
     112          Return a list of all the forms
     113          """
     114          return _forms_xpath(self)
     115      forms = property(forms, doc=forms.__doc__)
     116
     117 -    def body(self):
     118          """
     119          Return the <body> element.  Can be called from a child element
     120          to get the document's head.
     121          """
     122          return self.xpath('//body|//x:body', namespaces={'x':XHTML_NAMESPACE})[0]
     123      body = property(body, doc=body.__doc__)
     124
     125 -    def head(self):
     126          """
     127          Returns the <head> element.  Can be called from a child
     128          element to get the document's head.
     129          """
     130          return self.xpath('//head|//x:head', namespaces={'x':XHTML_NAMESPACE})[0]
     131      head = property(head, doc=head.__doc__)
     132
     133 -    def _label__get(self):
     134          """
     135          Get or set any <label> element associated with this element.
     136          """
     137          id = self.get('id')
     138          if not id:
     139              return None
     140          result = _label_xpath(self, id=id)
     141          if not result:
     142              return None
     143          else:
     144              return result[0]
     145 -    def _label__set(self, label):
     146          id = self.get('id')
     147          if not id:
     148              raise TypeError(
     149                  "You cannot set a label for an element (%r) that has no id"
     150                  % self)
     151          if _nons(label.tag) != 'label':
     152              raise TypeError(
     153                  "You can only assign label to a label element (not %r)"
     154                  % label)
     155          label.set('for', id)
     156 -    def _label__del(self):
     157          label = self.label
     158          if label is not None:
     159              del label.attrib['for']
     160      label = property(_label__get, _label__set, _label__del, doc=_label__get.__doc__)
     161
     162 -    def drop_tree(self):
     163          """
     164          Removes this element from the tree, including its children and
     165          text.  The tail text is joined to the previous element or
     166          parent.
     167          """
     168          parent = self.getparent()
     169          assert parent is not None
     170          if self.tail:
     171              previous = self.getprevious()
     172              if previous is None:
     173                  parent.text = (parent.text or '') + self.tail
     174              else:
     175                  previous.tail = (previous.tail or '') + self.tail
     176          parent.remove(self)
     177
     178 -    def drop_tag(self):
     179          """
     180          Remove the tag, but not its children or text.  The children and text
     181          are merged into the parent.
     182
     183          Example::
     184
     185              >>> h = fragment_fromstring('<div>Hello <b>World!</b></div>')
     186              >>> h.find('.//b').drop_tag()
     187              >>> print(tostring(h, encoding=unicode))
     188              <div>Hello World!</div>
     189          """
     190          parent = self.getparent()
     191          assert parent is not None
     192          previous = self.getprevious()
     193          if self.text and isinstance(self.tag, basestring):
     194              # not a Comment, etc.
     195              if previous is None:
     196                  parent.text = (parent.text or '') + self.text
     197              else:
     198                  previous.tail = (previous.tail or '') + self.text
     199          if self.tail:
     200              if len(self):
     201                  last = self[-1]
     202                  last.tail = (last.tail or '') + self.tail
     203              elif previous is None:
     204                  parent.text = (parent.text or '') + self.tail
     205              else:
     206                  previous.tail = (previous.tail or '') + self.tail
     207          index = parent.index(self)
     208          parent[index:index+1] = self[:]
     209
     210 -    def find_rel_links(self, rel):
     211          """
     212          Find any links like ``<a rel="{rel}">...</a>``; returns a list of elements.
     213          """
     214          rel = rel.lower()
     215          return [el for el in _rel_links_xpath(self)
     216                  if el.get('rel').lower() == rel]
     217
     218 -    def find_class(self, class_name):
     219          """
     220          Find any elements with the given class name.
     221          """
     222          return _class_xpath(self, class_name=class_name)
     223
     224 -    def get_element_by_id(self, id, *default):
     225          """
     226          Get the first element in a document with the given id.  If none is
     227          found, return the default argument if provided or raise KeyError
     228          otherwise.
     229
     230          Note that there can be more than one element with the same id,
     231          and this isn't uncommon in HTML documents found in the wild.
     232          Browsers return only the first match, and this function does
     233          the same.
     234          """
     235          try:
     236              # FIXME: should this check for multiple matches?
     237              # browsers just return the first one
     238              return _id_xpath(self, id=id)[0]
     239          except IndexError:
     240              if default:
     241                  return default[0]
     242              else:
     243                  raise KeyError(id)
     244
     245 -    def text_content(self):
     246          """
     247          Return the text content of the tag (and the text in any children).
     248          """
     249          return _collect_string_content(self)
     250
     251 -    def cssselect(self, expr):
     252          """
     253          Run the CSS expression on this element and its children,
     254          returning a list of the results.
     255
     256          Equivalent to lxml.cssselect.CSSSelect(expr)(self) -- note
     257          that pre-compiling the expression can provide a substantial
     258          speedup.
     259          """
     260          return cssselect.CSSSelector(expr)(self)
     261
     262      ########################################
     263      ## Link functions
     264      ########################################
     265
     266 -    def make_links_absolute(self, base_url=None, resolve_base_href=True):
     267          """
     268          Make all links in the document absolute, given the
     269          ``base_url`` for the document (the full URL where the document
     270          came from), or if no ``base_url`` is given, then the ``.base_url`` of the document.
     271
     272          If ``resolve_base_href`` is true, then any ``<base href>``
     273          tags in the document are used *and* removed from the document.
     274          If it is false then any such tag is ignored.
     275          """
     276          if base_url is None:
     277              base_url = self.base_url
     278              if base_url is None:
     279                  raise TypeError(
     280                      "No base_url given, and the document has no base_url")
     281          if resolve_base_href:
     282              self.resolve_base_href()
     283          def link_repl(href):
     284              return urljoin(base_url, href)
     285          self.rewrite_links(link_repl)
     286
     287 -    def resolve_base_href(self):
     288          """
     289          Find any ``<base href>`` tag in the document, and apply its
     290          values to all links found in the document.  Also remove the
     291          tag once it has been applied.
     292          """
     293          base_href = None
     294          basetags = self.xpath('//base[@href]|//x:base[@href]', namespaces={'x':XHTML_NAMESPACE})
     295          for b in basetags:
     296              base_href = b.get('href')
     297              b.drop_tree()
     298          if not base_href:
     299              return
     300          self.make_links_absolute(base_href, resolve_base_href=False)
     301
     302 -    def iterlinks(self):
     303          """
     304          Yield (element, attribute, link, pos), where attribute may be None
     305          (indicating the link is in the text).  ``pos`` is the position
     306          where the link occurs; often 0, but sometimes something else in
     307          the case of links in stylesheets or style tags.
     308
     309          Note: <base href> is *not* taken into account in any way.  The
     310          link you get is exactly the link in the document.
     311          """
     312          link_attrs = defs.link_attrs
     313          for el in self.iter():
     314              attribs = el.attrib
     315              tag = _nons(el.tag)
     316              if tag != 'object':
     317                  for attrib in link_attrs:
     318                      if attrib in attribs:
     319                          yield (el, attrib, attribs[attrib], 0)
     320              elif tag == 'object':
     321                  codebase = None
     322                  ## <object> tags have attributes that are relative to
     323                  ## codebase
     324                  if 'codebase' in attribs:
     325                      codebase = el.get('codebase')
     326                      yield (el, 'codebase', codebase, 0)
     327                  for attrib in 'classid', 'data':
     328                      if attrib in attribs:
     329                          value = el.get(attrib)
     330                          if codebase is not None:
     331                              value = urljoin(codebase, value)
     332                          yield (el, attrib, value, 0)
     333                  if 'archive' in attribs:
     334                      for match in _archive_re.finditer(el.get('archive')):
     335                          value = match.group(0)
     336                          if codebase is not None:
     337                              value = urljoin(codebase, value)
     338                          yield (el, 'archive', value, match.start())
     339              if tag == 'param':
     340                  valuetype = el.get('valuetype') or ''
     341                  if valuetype.lower() == 'ref':
     342                      ## FIXME: while it's fine we *find* this link,
     343                      ## according to the spec we aren't supposed to
     344                      ## actually change the value, including resolving
     345                      ## it.  It can also still be a link, even if it
     346                      ## doesn't have a valuetype="ref" (which seems to be the norm)
     347                      ## http://www.w3.org/TR/html401/struct/objects.html#adef-valuetype
     348                      yield (el, 'value', el.get('value'), 0)
     349              if tag == 'style' and el.text:
     350                  for match in _css_url_re.finditer(el.text):
     351                      url, start = _unquote_match(match.group(1), match.start(1))
     352                      yield (el, None, url, start)
     353                  for match in _css_import_re.finditer(el.text):
     354                      yield (el, None, match.group(1), match.start(1))
     355              if 'style' in attribs:
     356                  for match in _css_url_re.finditer(attribs['style']):
     357                      url, start = _unquote_match(match.group(1), match.start(1))
     358                      yield (el, 'style', url, start)
     359
     360 -    def rewrite_links(self, link_repl_func, resolve_base_href=True,
     361                        base_href=None):
     362          """
     363          Rewrite all the links in the document.  For each link
     364          ``link_repl_func(link)`` will be called, and the return value
     365          will replace the old link.
     366
     367          Note that links may not be absolute (unless you first called
     368          ``make_links_absolute()``), and may be internal (e.g.,
     369          ``'#anchor'``).  They can also be values like
     370          ``'mailto:email'`` or ``'javascript:expr'``.
     371
     372          If you give ``base_href`` then all links passed to
     373          ``link_repl_func()`` will take that into account.
     374
     375          If the ``link_repl_func`` returns None, the attribute or
     376          tag text will be removed completely.
     377          """
     378          if base_href is not None:
     379              # FIXME: this can be done in one pass with a wrapper
     380              # around link_repl_func
     381              self.make_links_absolute(base_href, resolve_base_href=resolve_base_href)
     382          elif resolve_base_href:
     383              self.resolve_base_href()
     384          for el, attrib, link, pos in self.iterlinks():
     385              new_link = link_repl_func(link.strip())
     386              if new_link == link:
     387                  continue
     388              if new_link is None:
     389                  # Remove the attribute or element content
     390                  if attrib is None:
     391                      el.text = ''
     392                  else:
     393                      del el.attrib[attrib]
     394                  continue
     395              if attrib is None:
     396                  new = el.text[:pos] + new_link + el.text[pos+len(link):]
     397                  el.text = new
     398              else:
     399                  cur = el.attrib[attrib]
     400                  if not pos and len(cur) == len(link):
     401                      # Most common case
     402                      el.attrib[attrib] = new_link
     403                  else:
     404                      new = cur[:pos] + new_link + cur[pos+len(link):]
     405                      el.attrib[attrib] = new
     406
     407
     408 -class _MethodFunc(object):
     409      """
     410      An object that represents a method on an element as a function;
     411      the function takes either an element or an HTML string.  It
     412      returns whatever the function normally returns, or if the function
     413      works in-place (and so returns None) it returns a serialized form
     414      of the resulting document.
     415      """
     416 -    def __init__(self, name, copy=False, source_class=HtmlMixin):
     417          self.name = name
     418          self.copy = copy
     419          self.__doc__ = getattr(source_class, self.name).__doc__
     420 -    def __call__(self, doc, *args, **kw):
     421          result_type = type(doc)
     422          if isinstance(doc, basestring):
     423              if 'copy' in kw:
     424                  raise TypeError(
     425                      "The keyword 'copy' can only be used with element inputs to %s, not a string input" % self.name)
     426              doc = fromstring(doc, **kw)
     427          else:
     428              if 'copy' in kw:
     429                  copy = kw.pop('copy')
     430              else:
     431                  copy = self.copy
     432              if copy:
     433                  doc = copy.deepcopy(doc)
     434          meth = getattr(doc, self.name)
     435          result = meth(*args, **kw)
     436          # FIXME: this None test is a bit sloppy
     437          if result is None:
     438              # Then return what we got in
     439              return _transform_result(result_type, doc)
     440          else:
     441              return result
     442
     443  find_rel_links = _MethodFunc('find_rel_links', copy=False)
     444  find_class = _MethodFunc('find_class', copy=False)
     445  make_links_absolute = _MethodFunc('make_links_absolute', copy=True)
     446  resolve_base_href = _MethodFunc('resolve_base_href', copy=True)
     447  iterlinks = _MethodFunc('iterlinks', copy=False)
     448  rewrite_links = _MethodFunc('rewrite_links', copy=True)
     449
     450 -class HtmlComment(etree.CommentBase, HtmlMixin):
     451      pass
     452
     453 -class HtmlElement(etree.ElementBase, HtmlMixin):
     454      pass
     455
     456 -class HtmlProcessingInstruction(etree.PIBase, HtmlMixin):
     457      pass
     458
     459 -class HtmlEntity(etree.EntityBase, HtmlMixin):
     460      pass
     461
     462
     463 -class HtmlElementClassLookup(etree.CustomElementClassLookup):
     464      """A lookup scheme for HTML Element classes.
     465
     466      To create a lookup instance with different Element classes, pass a tag
     467      name mapping of Element classes in the ``classes`` keyword argument and/or
     468      a tag name mapping of Mixin classes in the ``mixins`` keyword argument.
     469      The special key '*' denotes a Mixin class that should be mixed into all
     470      Element classes.
     471      """
     472      _default_element_classes = {}
     473
     474 -    def __init__(self, classes=None, mixins=None):
     475          etree.CustomElementClassLookup.__init__(self)
     476          if classes is None:
     477              classes = self._default_element_classes.copy()
     478          if mixins:
     479              mixers = {}
     480              for name, value in mixins:
     481                  if name == '*':
     482                      for n in classes.keys():
     483                          mixers.setdefault(n, []).append(value)
     484                  else:
     485                      mixers.setdefault(name, []).append(value)
     486              for name, mix_bases in mixers.items():
     487                  cur = classes.get(name, HtmlElement)
     488                  bases = tuple(mix_bases + [cur])
     489                  classes[name] = type(cur.__name__, bases, {})
     490          self._element_classes = classes
     491
     492 -    def lookup(self, node_type, document, namespace, name):
     493          if node_type == 'element':
     494              return self._element_classes.get(name.lower(), HtmlElement)
     495          elif node_type == 'comment':
     496              return HtmlComment
     497          elif node_type == 'PI':
     498              return HtmlProcessingInstruction
     499          elif node_type == 'entity':
     500              return HtmlEntity
     501          # Otherwise normal lookup
     502          return None
     503
     504  ################################################################################
     505  # parsing
     506  ################################################################################
     507
     508 -def document_fromstring(html, parser=None, **kw):
     509      if parser is None:
     510          parser = html_parser
     511      value = etree.fromstring(html, parser, **kw)
     512      if value is None:
     513          raise etree.ParserError(
     514              "Document is empty")
     515      return value
     516
     517 -def fragments_fromstring(html, no_leading_text=False, base_url=None,
     518                           parser=None, **kw):
     519      """
     520      Parses several HTML elements, returning a list of elements.
     521
     522      The first item in the list may be a string (though leading
     523      whitespace is removed).  If no_leading_text is true, then it will
     524      be an error if there is leading text, and it will always be a list
     525      of only elements.
     526
     527      base_url will set the document's base_url attribute (and the tree's docinfo.URL)
     528      """
     529      if parser is None:
     530          parser = html_parser
     531      # FIXME: check what happens when you give html with a body, head, etc.
     532      start = html[:20].lstrip().lower()
     533      if not start.startswith('<html') and not start.startswith('<!doctype'):
     534          html = '<html><body>%s</body></html>' % html
     535      doc = document_fromstring(html, parser=parser, base_url=base_url, **kw)
     536      assert _nons(doc.tag) == 'html'
     537      bodies = [e for e in doc if _nons(e.tag) == 'body']
     538      assert len(bodies) == 1, ("too many bodies: %r in %r" % (bodies, html))
     539      body = bodies[0]
     540      elements = []
     541      if no_leading_text and body.text and body.text.strip():
     542          raise etree.ParserError(
     543              "There is leading text: %r" % body.text)
     544      if body.text and body.text.strip():
     545          elements.append(body.text)
     546      elements.extend(body)
     547      # FIXME: removing the reference to the parent artificial document
     548      # would be nice
     549      return elements
     550
     551 -def fragment_fromstring(html, create_parent=False, base_url=None,
     552                          parser=None, **kw):
     553      """
     554      Parses a single HTML element; it is an error if there is more than
     555      one element, or if anything but whitespace precedes or follows the
     556      element.
     557
     558      If create_parent is true (or is a tag name) then a parent node
     559      will be created to encapsulate the HTML in a single element.
     560
     561      base_url will set the document's base_url attribute (and the tree's docinfo.URL)
     562      """
     563      if parser is None:
     564          parser = html_parser
     565      if create_parent:
     566          if not isinstance(create_parent, basestring):
     567              create_parent = 'div'
     568          return fragment_fromstring('<%s>%s</%s>' % (
     569              create_parent, html, create_parent),
     570                                     parser=parser, base_url=base_url, **kw)
     571      elements = fragments_fromstring(html, parser=parser, no_leading_text=True,
     572                                      base_url=base_url, **kw)
     573      if not elements:
     574          raise etree.ParserError(
     575              "No elements found")
     576      if len(elements) > 1:
     577          raise etree.ParserError(
     578              "Multiple elements found (%s)"
     579              % ', '.join([_element_name(e) for e in elements]))
     580      el = elements[0]
     581      if el.tail and el.tail.strip():
     582          raise etree.ParserError(
     583              "Element followed by text: %r" % el.tail)
     584      el.tail = None
     585      return el
     586
     587 -def fromstring(html, base_url=None, parser=None, **kw):
     588      """
     589      Parse the html, returning a single element/document.
     590
     591      This tries to minimally parse the chunk of text, without knowing if it
     592      is a fragment or a document.
     593
     594      base_url will set the document's base_url attribute (and the tree's docinfo.URL)
     595      """
     596      if parser is None:
     597          parser = html_parser
     598      start = html[:10].lstrip().lower()
     599      if start.startswith('<html') or start.startswith('<!doctype'):
     600          # Looks like a full HTML document
     601          return document_fromstring(html, parser=parser, base_url=base_url, **kw)
     602      # otherwise, lets parse it out...
     603      doc = document_fromstring(html, parser=parser, base_url=base_url, **kw)
     604      bodies = doc.findall('body')
     605      if not bodies:
     606          bodies = doc.findall('{%s}body' % XHTML_NAMESPACE)
     607      if bodies:
     608          body = bodies[0]
     609          if len(bodies) > 1:
     610              # Somehow there are multiple bodies, which is bad, but just
     611              # smash them into one body
     612              for other_body in bodies[1:]:
     613                  if other_body.text:
     614                      if len(body):
     615                          body[-1].tail = (body[-1].tail or '') + other_body.text
     616                      else:
     617                          body.text = (body.text or '') + other_body.text
     618                  body.extend(other_body)
     619                  # We'll ignore tail
     620                  # I guess we are ignoring attributes too
     621                  other_body.drop_tree()
     622      else:
     623          body = None
     624      heads = doc.findall('head')
     625      if not heads:
     626          heads = doc.findall('{%s}head' % XHTML_NAMESPACE)
     627      if heads:
     628          # Well, we have some sort of structure, so lets keep it all
     629          head = heads[0]
     630          if len(heads) > 1:
     631              for other_head in heads[1:]:
     632                  head.extend(other_head)
     633                  # We don't care about text or tail in a head
     634                  other_head.drop_tree()
     635          return doc
     636      if (len(body) == 1 and (not body.text or not body.text.strip())
     637          and (not body[-1].tail or not body[-1].tail.strip())):
     638          # The body has just one element, so it was probably a single
     639          # element passed in
     640          return body[0]
     641      # Now we have a body which represents a bunch of tags which have the
     642      # content that was passed in.  We will create a fake container, which
     643      # is the body tag, except <body> implies too much structure.
     644      if _contains_block_level_tag(body):
     645          body.tag = 'div'
     646      else:
     647          body.tag = 'span'
     648      return body
     649
     650 -def parse(filename_or_url, parser=None, base_url=None, **kw):
     651      """
     652      Parse a filename, URL, or file-like object into an HTML document
     653      tree.  Note: this returns a tree, not an element.  Use
     654      ``parse(...).getroot()`` to get the document root.
     655
     656      You can override the base URL with the ``base_url`` keyword.  This
     657      is most useful when parsing from a file-like object.
     658      """
     659      if parser is None:
     660          parser = html_parser
     661      return etree.parse(filename_or_url, parser, base_url=base_url, **kw)
     662
     663 -def _contains_block_level_tag(el):
     664      # FIXME: I could do this with XPath, but would that just be
     665      # unnecessarily slow?
     666      for el in el.iter():
     667          if _nons(el.tag) in defs.block_tags:
     668              return True
     669      return False
     670
     671 -def _element_name(el):
     672      if isinstance(el, etree.CommentBase):
     673          return 'comment'
     674      elif isinstance(el, basestring):
     675          return 'string'
     676      else:
     677          return _nons(el.tag)
     678
     679  ################################################################################
     680  # form handling
     681  ################################################################################
     682
     683 -class FormElement(HtmlElement):
     684      """
     685      Represents a <form> element.
     686      """
     687
     688 -    def inputs(self):
     689          """
     690          Returns an accessor for all the input elements in the form.
     691
     692          See `InputGetter` for more information about the object.
     693          """
     694          return InputGetter(self)
     695      inputs = property(inputs, doc=inputs.__doc__)
     696
     697 -    def _fields__get(self):
     698          """
     699          Dictionary-like object that represents all the fields in this
     700          form.  You can set values in this dictionary to effect the
     701          form.
     702          """
     703          return FieldsDict(self.inputs)
     704 -    def _fields__set(self, value):
     705          prev_keys = self.fields.keys()
     706          for key, value in value.iteritems():
     707              if key in prev_keys:
     708                  prev_keys.remove(key)
     709              self.fields[key] = value
     710          for key in prev_keys:
     711              if key is None:
     712                  # Case of an unnamed input; these aren't really
     713                  # expressed in form_values() anyway.
     714                  continue
     715              self.fields[key] = None
     716
     717      fields = property(_fields__get, _fields__set, doc=_fields__get.__doc__)
     718
     719 -    def _name(self):
     720          if self.get('name'):
     721              return self.get('name')
     722          elif self.get('id'):
     723              return '#' + self.get('id')
     724          forms = list(self.body.iter('form'))
     725          if not forms:
     726              forms = list(self.body.iter('{%s}form' % XHTML_NAMESPACE))
     727          return str(forms.index(self))
     728
     729 -    def form_values(self):
     730          """
     731          Return a list of tuples of the field values for the form.
     732          This is suitable to be passed to ``urllib.urlencode()``.
     733          """
     734          results = []
     735          for el in self.inputs:
     736              name = el.name
     737              if not name:
     738                  continue
     739              tag = _nons(el.tag)
     740              if tag == 'textarea':
     741                  results.append((name, el.value))
     742              elif tag == 'select':
     743                  value = el.value
     744                  if el.multiple:
     745                      for v in value:
     746                          results.append((name, v))
     747                  elif value is not None:
     748                      results.append((name, el.value))
     749              else:
     750                  assert tag == 'input', (
     751                      "Unexpected tag: %r" % el)
     752                  if el.checkable and not el.checked:
     753                      continue
     754                  if el.type in ('submit', 'image', 'reset'):
     755                      continue
     756                  value = el.value
     757                  if value is not None:
     758                      results.append((name, el.value))
     759          return results
     760
     761 -    def _action__get(self):
     762          """
     763          Get/set the form's ``action`` attribute.
     764          """
     765          base_url = self.base_url
     766          action = self.get('action')
     767          if base_url and action is not None:
     768              return urljoin(base_url, action)
     769          else:
     770              return action
     771 -    def _action__set(self, value):
     772          self.set('action', value)
     773 -    def _action__del(self):
     774          if 'action' in self.attrib:
     775              del self.attrib['action']
     776      action = property(_action__get, _action__set, _action__del, doc=_action__get.__doc__)
     777
     778 -    def _method__get(self):
     779          """
     780          Get/set the form's method.  Always returns a capitalized
     781          string, and defaults to ``'GET'``
     782          """
     783          return self.get('method', 'GET').upper()
     784 -    def _method__set(self, value):
     785          self.set('method', value.upper())
     786      method = property(_method__get, _method__set, doc=_method__get.__doc__)
     787
     788  HtmlElementClassLookup._default_element_classes['form'] = FormElement
     789
     790 -def submit_form(form, extra_values=None, open_http=None):
     791      """
     792      Helper function to submit a form.  Returns a file-like object, as from
     793      ``urllib.urlopen()``.  This object also has a ``.geturl()`` function,
     794      which shows the URL if there were any redirects.
     795
     796      You can use this like::
     797
     798          form = doc.forms[0]
     799          form.inputs['foo'].value = 'bar' # etc
     800          response = form.submit()
     801          doc = parse(response)
     802          doc.make_links_absolute(response.geturl())
     803
     804      To change the HTTP requester, pass a function as ``open_http`` keyword
     805      argument that opens the URL for you.  The function must have the following
     806      signature::
     807
     808          open_http(method, URL, values)
     809
     810      The action is one of 'GET' or 'POST', the URL is the target URL as a
     811      string, and the values are a sequence of ``(name, value)`` tuples with the
     812      form data.
     813      """
     814      values = form.form_values()
     815      if extra_values:
     816          if hasattr(extra_values, 'items'):
     817              extra_values = extra_values.items()
     818          values.extend(extra_values)
     819      if open_http is None:
     820          open_http = open_http_urllib
     821      return open_http(form.method, form.action, values)
     822
     823 -def open_http_urllib(method, url, values):
     824      import urllib
     825      ## FIXME: should test that it's not a relative URL or something
     826      if method == 'GET':
     827          if '?' in url:
     828              url += '&'
     829          else:
     830              url += '?'
     831          url += urllib.urlencode(values)
     832          data = None
     833      else:
     834          data = urllib.urlencode(values)
     835      return urllib.urlopen(url, data)
     836
     837 -class FieldsDict(DictMixin):
     838
     839 -    def __init__(self, inputs):
     840          self.inputs = inputs
     841 -    def __getitem__(self, item):
     842          return self.inputs[item].value
     843 -    def __setitem__(self, item, value):
     844          self.inputs[item].value = value
     845 -    def __delitem__(self, item):
     846          raise KeyError(
     847              "You cannot remove keys from ElementDict")
     848 -    def keys(self):
     849          return self.inputs.keys()
     850 -    def __contains__(self, item):
     851          return item in self.inputs
     852
     853 -    def __repr__(self):
     854          return '<%s for form %s>' % (
     855              self.__class__.__name__,
     856              self.inputs.form._name())
     857
     858 -class InputGetter(object):
     859
     860      """
     861      An accessor that represents all the input fields in a form.
     862
     863      You can get fields by name from this, with
     864      ``form.inputs['field_name']``.  If there are a set of checkboxes
     865      with the same name, they are returned as a list (a `CheckboxGroup`
     866      which also allows value setting).  Radio inputs are handled
     867      similarly.
     868
     869      You can also iterate over this to get all input elements.  This
     870      won't return the same thing as if you get all the names, as
     871      checkboxes and radio elements are returned individually.
     872      """
     873
     874      _name_xpath = etree.XPath(".//*[@name = $name and (local-name(.) = 'select' or local-name(.) = 'input' or local-name(.) = 'textarea')]")
     875      _all_xpath = etree.XPath(".//*[local-name() = 'select' or local-name() = 'input' or local-name() = 'textarea']")
     876
     877 -    def __init__(self, form):
     878          self.form = form
     879
     880 -    def __repr__(self):
     881          return '<%s for form %s>' % (
     882              self.__class__.__name__,
     883              self.form._name())
     884
     885      ## FIXME: there should be more methods, and it's unclear if this is
     886      ## a dictionary-like object or list-like object
     887
     888 -    def __getitem__(self, name):
     889          results = self._name_xpath(self.form, name=name)
     890          if results:
     891              type = results[0].get('type')
     892              if type == 'radio' and len(results) > 1:
     893                  group = RadioGroup(results)
     894                  group.name = name
     895                  return group
     896              elif type == 'checkbox' and len(results) > 1:
     897                  group = CheckboxGroup(results)
     898                  group.name = name
     899                  return group
     900              else:
     901                  # I don't like throwing away elements like this
     902                  return results[0]
     903          else:
     904              raise KeyError(
     905                  "No input element with the name %r" % name)
     906
     907 -    def __contains__(self, name):
     908          results = self._name_xpath(self.form, name=name)
     909          return bool(results)
     910
     911 -    def keys(self):
     912          names = set()
     913          for el in self:
     914              names.add(el.name)
     915          if None in names:
     916              names.remove(None)
     917          return list(names)
     918
     919 -    def __iter__(self):
     920          ## FIXME: kind of dumb to turn a list into an iterator, only
     921          ## to have it likely turned back into a list again :(
     922          return iter(self._all_xpath(self.form))
     923
     924 -class InputMixin(object):
     925
     926      """
     927      Mix-in for all input elements (input, select, and textarea)
     928      """
     929
     930
     931 -    def _name__get(self):
     932          """
     933          Get/set the name of the element
     934          """
     935          return self.get('name')
     936 -    def _name__set(self, value):
     937          self.set('name', value)
     938 -    def _name__del(self):
     939          if 'name' in self.attrib:
     940              del self.attrib['name']
     941      name = property(_name__get, _name__set, _name__del, doc=_name__get.__doc__)
     942
     943 -    def __repr__(self):
     944          type = getattr(self, 'type', None)
     945          if type:
     946              type = ' type=%r' % type
     947          else:
     948              type = ''
     949          return '<%s %x name=%r%s>' % (
     950              self.__class__.__name__, id(self), self.name, type)
     951
     952 -class TextareaElement(InputMixin, HtmlElement):
     953      """
     954      ``<textarea>`` element.  You can get the name with ``.name`` and
     955      get/set the value with ``.value``
     956      """
     957
     958 -    def _value__get(self):
     959          """
     960          Get/set the value (which is the contents of this element)
     961          """
     962          return self.text or ''
     963 -    def _value__set(self, value):
     964          self.text = value
     965 -    def _value__del(self):
     966          self.text = ''
     967      value = property(_value__get, _value__set, _value__del, doc=_value__get.__doc__)
     968
     969  HtmlElementClassLookup._default_element_classes['textarea'] = TextareaElement
     970
     971 -class SelectElement(InputMixin, HtmlElement):
     972      """
     973      ``<select>`` element.  You can get the name with ``.name``.
     974
     975      ``.value`` will be the value of the selected option, unless this
     976      is a multi-select element (``<select multiple>``), in which case
     977      it will be a set-like object.  In either case ``.value_options``
     978      gives the possible values.
     979
     980      The boolean attribute ``.multiple`` shows if this is a
     981      multi-select.
     982      """
     983
     984 -    def _value__get(self):
     985          """
     986          Get/set the value of this select (the selected option).
     987
     988          If this is a multi-select, this is a set-like object that
     989          represents all the selected options.
     990          """
     991          if self.multiple:
     992              return MultipleSelectOptions(self)
     993          for el in _options_xpath(self):
     994              if 'selected' in el.attrib:
     995                  value = el.get('value')
     996                  # FIXME: If value is None, what to return?, get_text()?
     997                  return value
     998          return None
     999
    1000 -    def _value__set(self, value):
    1001          if self.multiple:
    1002              if isinstance(value, basestring):
    1003                  raise TypeError(
    1004                      "You must pass in a sequence")
    1005              self.value.clear()
    1006              self.value.update(value)
    1007              return
    1008          if value is not None:
    1009              for el in _options_xpath(self):
    1010                  # FIXME: also if el.get('value') is None?
    1011                  if el.get('value') == value:
    1012                      checked_option = el
    1013                      break
    1014              else:
    1015                  raise ValueError(
    1016                      "There is no option with the value of %r" % value)
    1017          for el in _options_xpath(self):
    1018              if 'selected' in el.attrib:
    1019                  del el.attrib['selected']
    1020          if value is not None:
    1021              checked_option.set('selected', '')
    1022
    1023 -    def _value__del(self):
    1024          # FIXME: should del be allowed at all?
    1025          if self.multiple:
    1026              self.value.clear()
    1027          else:
    1028              self.value = None
    1029
    1030      value = property(_value__get, _value__set, _value__del, doc=_value__get.__doc__)
    1031
    1032 -    def value_options(self):
    1033          """
    1034          All the possible values this select can have (the ``value``
    1035          attribute of all the ``<option>`` elements.
    1036          """
    1037          return [el.get('value') for el in _options_xpath(self)]
    1038      value_options = property(value_options, doc=value_options.__doc__)
    1039
    1040 -    def _multiple__get(self):
    1041          """
    1042          Boolean attribute: is there a ``multiple`` attribute on this element.
    1043          """
    1044          return 'multiple' in self.attrib
    1045 -    def _multiple__set(self, value):
    1046          if value:
    1047              self.set('multiple', '')
    1048          elif 'multiple' in self.attrib:
    1049              del self.attrib['multiple']
    1050      multiple = property(_multiple__get, _multiple__set, doc=_multiple__get.__doc__)
    1051
    1052  HtmlElementClassLookup._default_element_classes['select'] = SelectElement
    1053
    1054 -class MultipleSelectOptions(SetMixin):
    1055      """
    1056      Represents all the selected options in a ``<select multiple>`` element.
    1057
    1058      You can add to this set-like option to select an option, or remove
    1059      to unselect the option.
    1060      """
    1061
    1062 -    def __init__(self, select):
    1063          self.select = select
    1064
    1065 -    def options(self):
    1066          """
    1067          Iterator of all the ``<option>`` elements.
    1068          """
    1069          return iter(_options_xpath(self.select))
    1070      options = property(options)
    1071
    1072 -    def __iter__(self):
    1073          for option in self.options:
    1074              yield option.get('value')
    1075
    1076 -    def add(self, item):
    1077          for option in self.options:
    1078              if option.get('value') == item:
    1079                  option.set('selected', '')
    1080                  break
    1081          else:
    1082              raise ValueError(
    1083                  "There is no option with the value %r" % item)
    1084
    1085 -    def remove(self, item):
    1086          for option in self.options:
    1087              if option.get('value') == item:
    1088                  if 'selected' in option.attrib:
    1089                      del option.attrib['selected']
    1090                  else:
    1091                      raise ValueError(
    1092                          "The option %r is not currently selected" % item)
    1093                  break
    1094          else:
    1095              raise ValueError(
    1096                  "There is not option with the value %r" % item)
    1097
    1098 -    def __repr__(self):
    1099          return '<%s {%s} for select name=%r>' % (
    1100              self.__class__.__name__,
    1101              ', '.join([repr(v) for v in self]),
    1102              self.select.name)
    1103
    1104 -class RadioGroup(list):
    1105      """
    1106      This object represents several ``<input type=radio>`` elements
    1107      that have the same name.
    1108
    1109      You can use this like a list, but also use the property
    1110      ``.value`` to check/uncheck inputs.  Also you can use
    1111      ``.value_options`` to get the possible values.
    1112      """
    1113
    1114 -    def _value__get(self):
    1115          """
    1116          Get/set the value, which checks the radio with that value (and
    1117          unchecks any other value).
    1118          """
    1119          for el in self:
    1120              if 'checked' in el.attrib:
    1121                  return el.get('value')
    1122          return None
    1123
    1124 -    def _value__set(self, value):
    1125          if value is not None:
    1126              for el in self:
    1127                  if el.get('value') == value:
    1128                      checked_option = el
    1129                      break
    1130              else:
    1131                  raise ValueError(
    1132                      "There is no radio input with the value %r" % value)
    1133          for el in self:
    1134              if 'checked' in el.attrib:
    1135                  del el.attrib['checked']
    1136          if value is not None:
    1137              checked_option.set('checked', '')
    1138
    1139 -    def _value__del(self):
    1140          self.value = None
    1141
    1142      value = property(_value__get, _value__set, _value__del, doc=_value__get.__doc__)
    1143
    1144 -    def value_options(self):
    1145          """
    1146          Returns a list of all the possible values.
    1147          """
    1148          return [el.get('value') for el in self]
    1149      value_options = property(value_options, doc=value_options.__doc__)
    1150
    1151 -    def __repr__(self):
    1152          return '%s(%s)' % (
    1153              self.__class__.__name__,
    1154              list.__repr__(self))
    1155
    1156 -class CheckboxGroup(list):
    1157      """
    1158      Represents a group of checkboxes (``<input type=checkbox>``) that
    1159      have the same name.
    1160
    1161      In addition to using this like a list, the ``.value`` attribute
    1162      returns a set-like object that you can add to or remove from to
    1163      check and uncheck checkboxes.  You can also use ``.value_options``
    1164      to get the possible values.
    1165      """
    1166
    1167 -    def _value__get(self):
    1168          """
    1169          Return a set-like object that can be modified to check or
    1170          uncheck individual checkboxes according to their value.
    1171          """
    1172          return CheckboxValues(self)
    1173 -    def _value__set(self, value):
    1174          self.value.clear()
    1175          if not hasattr(value, '__iter__'):
    1176              raise ValueError(
    1177                  "A CheckboxGroup (name=%r) must be set to a sequence (not %r)"
    1178                  % (self[0].name, value))
    1179          self.value.update(value)
    1180 -    def _value__del(self):
    1181          self.value.clear()
    1182      value = property(_value__get, _value__set, _value__del, doc=_value__get.__doc__)
    1183
    1184 -    def __repr__(self):
    1185          return '%s(%s)' % (
    1186              self.__class__.__name__, list.__repr__(self))
    1187
    1188 -class CheckboxValues(SetMixin):
    1189
    1190      """
    1191      Represents the values of the checked checkboxes in a group of
    1192      checkboxes with the same name.
    1193      """
    1194
    1195 -    def __init__(self, group):
    1196          self.group = group
    1197
    1198 -    def __iter__(self):
    1199          return iter([
    1200              el.get('value')
    1201              for el in self.group
    1202              if 'checked' in el.attrib])
    1203
    1204 -    def add(self, value):
    1205          for el in self.group:
    1206              if el.get('value') == value:
    1207                  el.set('checked', '')
    1208                  break
    1209          else:
    1210              raise KeyError("No checkbox with value %r" % value)
    1211
    1212 -    def remove(self, value):
    1213          for el in self.group:
    1214              if el.get('value') == value:
    1215                  if 'checked' in el.attrib:
    1216                      del el.attrib['checked']
    1217                  else:
    1218                      raise KeyError(
    1219                          "The checkbox with value %r was already unchecked" % value)
    1220                  break
    1221          else:
    1222              raise KeyError(
    1223                  "No checkbox with value %r" % value)
    1224
    1225 -    def __repr__(self):
    1226          return '<%s {%s} for checkboxes name=%r>' % (
    1227              self.__class__.__name__,
    1228              ', '.join([repr(v) for v in self]),
    1229              self.group.name)
    1230
    1231 -class InputElement(InputMixin, HtmlElement):
    1232      """
    1233      Represents an ``<input>`` element.
    1234
    1235      You can get the type with ``.type`` (which is lower-cased and
    1236      defaults to ``'text'``).
    1237
    1238      Also you can get and set the value with ``.value``
    1239
    1240      Checkboxes and radios have the attribute ``input.checkable ==
    1241      True`` (for all others it is false) and a boolean attribute
    1242      ``.checked``.
    1243
    1244      """
    1245
    1246      ## FIXME: I'm a little uncomfortable with the use of .checked
    1247 -    def _value__get(self):
    1248          """
    1249          Get/set the value of this element, using the ``value`` attribute.
    1250
    1251          Also, if this is a checkbox and it has no value, this defaults
    1252          to ``'on'``.  If it is a checkbox or radio that is not
    1253          checked, this returns None.
    1254          """
    1255          if self.checkable:
    1256              if self.checked:
    1257                  return self.get('value') or 'on'
    1258              else:
    1259                  return None
    1260          return self.get('value')
    1261 -    def _value__set(self, value):
    1262          if self.checkable:
    1263              if not value:
    1264                  self.checked = False
    1265              else:
    1266                  self.checked = True
    1267                  if isinstance(value, basestring):
    1268                      self.set('value', value)
    1269          else:
    1270              self.set('value', value)
    1271 -    def _value__del(self):
    1272          if self.checkable:
    1273              self.checked = False
    1274          else:
    1275              if 'value' in self.attrib:
    1276                  del self.attrib['value']
    1277      value = property(_value__get, _value__set, _value__del, doc=_value__get.__doc__)
    1278
    1279 -    def _type__get(self):
    1280          """
    1281          Return the type of this element (using the type attribute).
    1282          """
    1283          return self.get('type', 'text').lower()
    1284 -    def _type__set(self, value):
    1285          self.set('type', value)
    1286      type = property(_type__get, _type__set, doc=_type__get.__doc__)
    1287
    1288 -    def checkable(self):
    1289          """
    1290          Boolean: can this element be checked?
    1291          """
    1292          return self.type in ['checkbox', 'radio']
    1293      checkable = property(checkable, doc=checkable.__doc__)
    1294
    1295 -    def _checked__get(self):
    1296          """
    1297          Boolean attribute to get/set the presence of the ``checked``
    1298          attribute.
    1299
    1300          You can only use this on checkable input types.
    1301          """
    1302          if not self.checkable:
    1303              raise AttributeError('Not a checkable input type')
    1304          return 'checked' in self.attrib
    1305 -    def _checked__set(self, value):
    1306          if not self.checkable:
    1307              raise AttributeError('Not a checkable input type')
    1308          if value:
    1309              self.set('checked', '')
    1310          else:
    1311              if 'checked' in self.attrib:
    1312                  del self.attrib['checked']
    1313      checked = property(_checked__get, _checked__set, doc=_checked__get.__doc__)
    1314
    1315  HtmlElementClassLookup._default_element_classes['input'] = InputElement
    1316
    1317 -class LabelElement(HtmlElement):
    1318      """
    1319      Represents a ``<label>`` element.
    1320
    1321      Label elements are linked to other elements with their ``for``
    1322      attribute.  You can access this element with ``label.for_element``.
    1323      """
    1324
    1325 -    def _for_element__get(self):
    1326          """
    1327          Get/set the element this label points to.  Return None if it
    1328          can't be found.
    1329          """
    1330          id = self.get('for')
    1331          if not id:
    1332              return None
    1333          return self.body.get_element_by_id(id)
    1334 -    def _for_element__set(self, other):
    1335          id = other.get('id')
    1336          if not id:
    1337              raise TypeError(
    1338                  "Element %r has no id attribute" % other)
    1339          self.set('for', id)
    1340 -    def _for_element__del(self):
    1341          if 'id' in self.attrib:
    1342              del self.attrib['id']
    1343      for_element = property(_for_element__get, _for_element__set, _for_element__del,
    1344                             doc=_for_element__get.__doc__)
    1345
    1346  HtmlElementClassLookup._default_element_classes['label'] = LabelElement
    1347
    1348  ############################################################
    1349  ## Serialization
    1350  ############################################################
    1351
    1352 -def html_to_xhtml(html):
    1353      """Convert all tags in an HTML tree to XHTML by moving them to the
    1354      XHTML namespace.
    1355      """
    1356      try:
    1357          html = html.getroot()
    1358      except AttributeError:
    1359          pass
    1360      prefix = "{%s}" % XHTML_NAMESPACE
    1361      for el in html.iter():
    1362          tag = el.tag
    1363          if isinstance(tag, basestring):
    1364              if tag[0] != '{':
    1365                  el.tag = prefix + tag
    1366
    1367 -def xhtml_to_html(xhtml):
    1368      """Convert all tags in an XHTML tree to HTML by removing their
    1369      XHTML namespace.
    1370      """
    1371      try:
    1372          xhtml = xhtml.getroot()
    1373      except AttributeError:
    1374          pass
    1375      prefix = "{%s}" % XHTML_NAMESPACE
    1376      prefix_len = len(prefix)
    1377      for el in xhtml.iter(prefix + "*"):
    1378          el.tag = el.tag[prefix_len:]
    1379
    1380  # This isn't a general match, but it's a match for what libxml2
    1381  # specifically serialises:
    1382  __str_replace_meta_content_type = re.compile(
    1383      r'<meta http-equiv="Content-Type"[^>]*>').sub
    1384  __bytes_replace_meta_content_type = re.compile(
    1385      r'<meta http-equiv="Content-Type"[^>]*>'.encode('ASCII')).sub
    1386
    1387 -def tostring(doc, pretty_print=False, include_meta_content_type=False,
    1388               encoding=None, method="html"):
    1389      """Return an HTML string representation of the document.
    1390
    1391      Note: if include_meta_content_type is true this will create a
    1392      ``<meta http-equiv="Content-Type" ...>`` tag in the head;
    1393      regardless of the value of include_meta_content_type any existing
    1394      ``<meta http-equiv="Content-Type" ...>`` tag will be removed
    1395
    1396      The ``encoding`` argument controls the output encoding (defauts to
    1397      ASCII, with &#...; character references for any characters outside
    1398      of ASCII).
    1399
    1400      The ``method`` argument defines the output method.  It defaults to
    1401      'html', but can also be 'xml' for xhtml output, or 'text' to
    1402      serialise to plain text without markup.  Note that you can pass
    1403      the builtin ``unicode`` type as ``encoding`` argument to serialise
    1404      to a unicode string.
    1405
    1406      Example::
    1407
    1408          >>> from lxml import html
    1409          >>> root = html.fragment_fromstring('<p>Hello<br>world!</p>')
    1410
    1411          >>> html.tostring(root)
    1412          b'<p>Hello<br>world!</p>'
    1413          >>> html.tostring(root, method='html')
    1414          b'<p>Hello<br>world!</p>'
    1415
    1416          >>> html.tostring(root, method='xml')
    1417          b'<p>Hello<br/>world!</p>'
    1418
    1419          >>> html.tostring(root, method='text')
    1420          b'Helloworld!'
    1421
    1422          >>> html.tostring(root, method='text', encoding=unicode)
    1423          u'Helloworld!'
    1424      """
    1425      html = etree.tostring(doc, method=method, pretty_print=pretty_print,
    1426                            encoding=encoding)
    1427      if not include_meta_content_type:
    1428          if isinstance(html, str):
    1429              html = __str_replace_meta_content_type('', html)
    1430          else:
    1431              html = __bytes_replace_meta_content_type(bytes(), html)
    1432      return html
    1433
    1434  tostring.__doc__ = __fix_docstring(tostring.__doc__)
    1435
    1436 -def open_in_browser(doc):
    1437      """
    1438      Open the HTML document in a web browser (saving it to a temporary
    1439      file to open it).
    1440      """
    1441      import os
    1442      import webbrowser
    1443      try:
    1444          write_doc = doc.write
    1445      except AttributeError:
    1446          write_doc = etree.ElementTree(element=doc).write
    1447      fn = os.tempnam() + '.html'
    1448      write_doc(fn, method="html")
    1449      url = 'file://' + fn.replace(os.path.sep, '/')
    1450      print(url)
    1451      webbrowser.open(url)
    1452
    1453  ################################################################################
    1454  # configure Element class lookup
    1455  ################################################################################
    1456
    1457 -class HTMLParser(etree.HTMLParser):
    1458 -    def __init__(self, **kwargs):
    1459          super(HTMLParser, self).__init__(**kwargs)
    1460          self.set_element_class_lookup(HtmlElementClassLookup())
    1461
    1462 -class XHTMLParser(etree.XMLParser):
    1463 -    def __init__(self, **kwargs):
    1464          super(XHTMLParser, self).__init__(**kwargs)
    1465          self.set_element_class_lookup(HtmlElementClassLookup())
    1466
    1467 -def Element(*args, **kw):
    1468      """Create a new HTML Element.
    1469
    1470      This can also be used for XHTML documents.
    1471      """
    1472      v = html_parser.makeelement(*args, **kw)
    1473      return v
    1474
    1475  html_parser = HTMLParser()
    1476  xhtml_parser = XHTMLParser()
    1477