Improve "parser=" and return annotations of fromstring() and parse() (GH-64)

`parser` can also be an HTMLParser, not just XMLParser.

It's possible for these functions to return None, if the parser has
`recover=True` or a custom parser target was provided.
Otherwise, they always return an `_Element`.

Closes #63.

Author: DMRobertson

lxml-stubs/etree.pyi

@@ -499,12 +499,25 @@ def cleanup_namespaces(
     keep_ns_prefixes: Optional[Iterable[_AnyStr]] = ...,
 ) -> None: ...
 def parse(
-    source: _FileSource, parser: XMLParser = ..., base_url: _AnyStr = ...
-) -> _ElementTree: ...
+    source: _FileSource,
+    parser: Union[XMLParser, HTMLParser] = ...,
+    base_url: _AnyStr = ...,
+) -> Union[_ElementTree, Any]: ...
+@overload
 def fromstring(
-    text: _AnyStr, parser: XMLParser = ..., *, base_url: _AnyStr = ...
+    text: _AnyStr,
+    parser: None = ...,
+    *,
+    base_url: _AnyStr = ...,
 ) -> _Element: ...
 @overload
+def fromstring(
+    text: _AnyStr,
+    parser: Union[XMLParser, HTMLParser] = ...,
+    *,
+    base_url: _AnyStr = ...,
+) -> Union[_Element, Any]: ...
+@overload
 def tostring(
     element_or_tree: _ElementOrTree,
     encoding: Union[Type[str], Literal["unicode"]],

test-data/test-etree.yml

@@ -5,6 +5,14 @@
         document = etree.fromstring("<doc></doc>")
         reveal_type(document)  # N: Revealed type is "lxml.etree._Element"
 
+-   case: etree_from_empty_string_with_parser_recovery_returns_none
+    disable_cache: true
+    main: |
+        from lxml import etree
+        parser = etree.HTMLParser(recover=True)
+        document = etree.fromstring("", parser)
+        reveal_type(document)  # N: Revealed type is "Union[lxml.etree._Element, Any]"
+
 -   case: etree_element_find
     disable_cache: true
     main: |