feat(stub): fromstring(), parse() and _ElementTree.parse() support custom target parser

Author: abelcheung

src/lxml-stubs/etree/_element.pyi

@@ -11,6 +11,12 @@ from typing import (
     overload,
 )
 
+from .. import _types as _t
+from ..cssselect import _CSSTransArg
+from ._module_misc import CDATA, DocInfo, QName
+from ._parser import CustomTargetParser
+from ._xslt import XSLTAccessControl, XSLTExtension, _Stylesheet_Param, _XSLTResultTree
+
 if sys.version_info >= (3, 11):
     from typing import Never, Self
 else:
@@ -21,11 +27,6 @@ if sys.version_info >= (3, 13):
 else:
     from typing_extensions import deprecated
 
-from .. import _types as _t
-from ..cssselect import _CSSTransArg
-from ._module_misc import CDATA, DocInfo, QName
-from ._xslt import XSLTAccessControl, XSLTExtension, _Stylesheet_Param, _XSLTResultTree
-
 _T = TypeVar("_T")
 
 # The base of _Element is *almost* an amalgam of MutableSequence[_Element]
@@ -661,6 +662,8 @@ class _Element:
         self, tag: _t._TagSelector | None = None, *tags: _t._TagSelector
     ) -> Iterator[Self]: ...
 
+_ET2_co = TypeVar("_ET2_co", bound=_Element, default=_Element, covariant=True)
+
 # ET class notation is specialized, indicating the type of element
 # it is holding (e.g. XML element, HTML element or Objectified
 # Element).
@@ -673,13 +676,63 @@ class _ElementTree(Generic[_t._ET_co]):
     def parser(self) -> _t._DefEtreeParsers[_t._ET_co] | None: ...
     @property
     def docinfo(self) -> DocInfo: ...
+    @overload  # common parser
     def parse(
         self,
         source: _t._FileReadSource,
-        parser: _t._DefEtreeParsers[_t._ET_co] | None = None,
+        parser: _t._DefEtreeParsers[_ET2_co],
         *,
-        base_url: _t._AnyStr | None = None,
-    ) -> None: ...
+        base_url: str | bytes | None = None,
+    ) -> _ET2_co:
+        """Updates self with the content of source and returns its root.
+
+        Annotation
+        ----------
+        This overload handles the case where a common parser is supplied.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree._ElementTree.parse)
+        """
+    @overload  # custom target parser
+    def parse(
+        self,
+        source: _t._FileReadSource,
+        parser: CustomTargetParser[_ET2_co],
+        *,
+        base_url: str | bytes | None = None,
+    ) -> _ET2_co:
+        """Updates self with the content of source and returns its root.
+
+        Annotation
+        ----------
+        This overload handles the case where a custom target parser is supplied.
+        Note that target object must return an element, i.e. compatible with
+        `etree.TreeBuilder`.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree._ElementTree.parse)
+        """
+    @overload  # parser not supplied
+    def parse(
+        self,
+        source: _t._FileReadSource,
+        parser: None = None,
+        *,
+        base_url: str | bytes | None = None,
+    ) -> _Element:
+        """Updates self with the content of source and returns its root.
+
+        Annotation
+        ----------
+        This overload handles the case where no parser is supplied (thus
+        default parser is utilised).
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree._ElementTree.parse)
+        """
     # Changes root node; in terms of typing, this means changing
     # specialization of ElementTree. This is not expressible in
     # current typing system.

src/lxml-stubs/etree/_module_func.pyi

@@ -171,7 +171,7 @@ def XML(
     [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.XML)
     """
 
-@overload
+@overload  # common parser
 def parse(
     source: _FileReadSource,
     parser: _DefEtreeParsers[_ET_co],
@@ -189,15 +189,35 @@ def parse(
     Please [refer to wiki](https://github.com/abelcheung/types-lxml/wiki/Using-specialised-class-directly#no-automatic-change-of-subscript)
     on how to create such annotation-only specialized parsers.
 
-    Returning result of custom parser target is unsupported in stubs.
-    Please use `typing.cast()` directly in such case.
+    See Also
+    --------
+    [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.parse)
+    """
+
+@overload  # custom target parser
+def parse(
+    source: _FileReadSource,
+    parser: CustomTargetParser[_T],
+    *,
+    base_url: str | bytes | None = None,
+) -> _T:
+    """Return an ElementTree object loaded with source elements.
+
+    Annotation
+    ----------
+    When specially constructed parser with custom parser target is supplied,
+    `parse()` returns that value dictated in parser target definition,
+    that is the parser target `.close()` method return value.
+
+    Please [refer to wiki](https://github.com/abelcheung/types-lxml/wiki/Custom-target-parser)
+    on how to create fully annotated parser with custom target object.
 
     See Also
     --------
     [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.parse)
     """
 
-@overload
+@overload  # parser not supplied
 def parse(
     source: _FileReadSource,
     parser: None = None,
@@ -206,12 +226,16 @@ def parse(
 ) -> _ElementTree:
     """Return an ElementTree object loaded with source elements.
 
+    Annotation
+    ----------
+    This overload handles usage of `parse()` with default parser.
+
     See Also
     --------
     [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.parse)
     """
 
-@overload
+@overload  # common parser
 def fromstring(
     text: str | Buffer,
     parser: _DefEtreeParsers[_ET_co],
@@ -230,15 +254,36 @@ def fromstring(
     Please [refer to wiki](https://github.com/abelcheung/types-lxml/wiki/Using-specialised-class-directly#no-automatic-change-of-subscript)
     on how to create such annotation-only specialized parsers.
 
-    Returning result of custom parser target is unsupported in stubs.
-    Please use `typing.cast()` directly in such case.
+    See Also
+    --------
+    [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.fromstring)
+    """
+
+@overload  # custom target parser
+def fromstring(
+    text: str | Buffer,
+    parser: CustomTargetParser[_T],
+    *,
+    base_url: str | bytes | None = None,
+) -> _T:
+    """Parses an XML document or fragment from a string.
+    Returns the root node (or the result returned by a parser target).
+
+    Annotation
+    ----------
+    When specially constructed parser with custom parser target is supplied,
+    `fromstring()` returns that value dictated in parser target definition,
+    that is the parser target `.close()` method return value.
+
+    Please [refer to wiki](https://github.com/abelcheung/types-lxml/wiki/Custom-target-parser)
+    on how to create fully annotated parser with custom target object.
 
     See Also
     --------
     [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.fromstring)
     """
 
-@overload
+@overload  # parser not supplied
 def fromstring(
     text: str | Buffer,
     parser: None = None,
@@ -248,6 +293,10 @@ def fromstring(
     """Parses an XML document or fragment from a string.
     Returns the root node (or the result returned by a parser target).
 
+    Annotation
+    ----------
+    This overload handles usage of `fromstring()` with default parser.
+
     See Also
     --------
     [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.fromstring)