From 0e97999467e768cf9cddf89706459e488253056a Mon Sep 17 00:00:00 2001
From: David Robertson <david.m.robertson1@gmail.com>
Date: Tue, 26 Jul 2022 07:49:44 +0100
Subject: [PATCH] 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.
---
 lxml-stubs/etree.pyi     | 19 ++++++++++++++++---
 test-data/test-etree.yml |  8 ++++++++
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/lxml-stubs/etree.pyi b/lxml-stubs/etree.pyi
index c140cb5..a1653dd 100644
--- a/lxml-stubs/etree.pyi
+++ b/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"]],
diff --git a/test-data/test-etree.yml b/test-data/test-etree.yml
index f0e68ac..6c9bb2a 100644
--- a/test-data/test-etree.yml
+++ b/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: |