fix(stub): Sort out QName construct arg combinations

- 1st arg can't be bytearray
- 2nd arg can be bytearray but not QName
- empty string causes exception

Author: abelcheung

src/lxml-stubs/etree/_module_misc.pyi

@@ -4,7 +4,7 @@
 
 import sys
 from abc import ABCMeta, abstractmethod
-from typing import Final, overload
+from typing import Any, Final, Literal, overload
 
 from .._types import (
     _ElementOrTree,
@@ -20,6 +20,11 @@ if sys.version_info >= (3, 11):
 else:
     from typing_extensions import LiteralString
 
+if sys.version_info >= (3, 13):
+    from warnings import deprecated
+else:
+    from typing_extensions import deprecated
+
 DEBUG: int
 ICONV_COMPILED_VERSION: Final[tuple[int, int]]
 LIBXML_COMPILED_VERSION: Final[tuple[int, int, int]]
@@ -91,40 +96,36 @@ class DocInfo:
 class QName:
     """QName wrapper for qualified XML names.
 
-    Pass a tag name by itself or a namespace URI and a tag name to
-    create a qualified name.  Alternatively, pass an Element to
-    extract its tag name.  ``None`` as first argument is ignored in
-    order to allow for generic 2-argument usage.
-
-    The ``text`` property holds the qualified name in
-    ``{namespace}tagname`` notation.  The ``.namespace`` and
-    ``.localname`` properties hold the respective parts of the tag
-    name.
-
-    You can pass QName objects wherever a tag name is expected.  Also,
-    setting Element text from a QName will resolve the namespace prefix
-    on assignment and set a qualified text value.  This is helpful in XML
-    languages like SOAP or XML-Schema that use prefixed tag names in
-    their text content.
+    See Also
+    --------
+    - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.QName)
     """
-    @overload
+    @overload  # empty string = exception
+    @deprecated("Use None instead, empty string would cause exception")
+    def __init__(
+        self,
+        text_or_uri_or_element: Literal[""],
+        tag: Any = None,
+    ) -> None: ...  # Switching to Never causes testsuite problem
+    @overload  # first arg non-empty
     def __init__(
         self,
-        text_or_uri_or_element: _TagName | _Element,
-        tag: _TagName | None = None,
+        text_or_uri_or_element: str | bytes | QName | _Element,
+        tag: _TextArg | None = None,
     ) -> None: ...
-    @overload
+    @overload  # first arg empty
     def __init__(
         self,
         text_or_uri_or_element: None,
-        tag: _TagName | _Element,
+        tag: str | bytes | QName | _Element,
     ) -> None: ...
     @property
     def localname(self) -> str: ...
     @property
     def namespace(self) -> str | None: ...
     @property
-    def text(self) -> str: ...
+    def text(self) -> str:
+        """Holds the qualified name in `{namespace}tagname` notation"""
     # Emulate __richcmp__()
     def __ge__(self, other: _TagName) -> bool: ...
     def __gt__(self, other: _TagName) -> bool: ...

tests/runtime/_testutils/strategy.py

@@ -173,7 +173,6 @@ def add_ns(ns: str, n: str) -> str:
     )
 
 
-# FIXME: For future test, _e.QName("", "foo") raise exception
 def xml_name_arg() -> st.SearchStrategy[str | bytes | bytearray | _e.QName]:
     s = xml_name()
     qn = s.map(_e.QName)