From ff2fde800414b528e020a65c2eb94cd291652fce Mon Sep 17 00:00:00 2001
From: Abel Cheung <abelcheung@gmail.com>
Date: Fri, 13 Dec 2024 08:03:26 +0000
Subject: [PATCH] fix(stub): Guard against str usage in XPath Extension
 function

Closes #64
---
 src/lxml-stubs/etree/_xpath.pyi | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/lxml-stubs/etree/_xpath.pyi b/src/lxml-stubs/etree/_xpath.pyi
index 0cdacea..b18bdf0 100644
--- a/src/lxml-stubs/etree/_xpath.pyi
+++ b/src/lxml-stubs/etree/_xpath.pyi
@@ -6,7 +6,20 @@
 import sys
 from abc import abstractmethod
 from types import ModuleType
-from typing import Any, Callable, Collection, Generic, Protocol, final, overload
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    Protocol,
+    final,
+    overload,
+)
+
+if sys.version_info >= (3, 11):
+    from typing import Never
+else:
+    from typing_extensions import Never
 
 if sys.version_info >= (3, 13):
     from warnings import deprecated
@@ -142,17 +155,26 @@ class _ElementUnicodeResult(str, Generic[_ET]):
     def attrname(self) -> str | None: ...
     def getparent(self: _ElementUnicodeResult[_ET]) -> _ET | None: ...
 
+@overload  # guard against str
+@deprecated(
+    "Use Iterable even when only one function is specified in function_mapping argument"
+)
+def Extension(
+    module: object | ModuleType,
+    function_mapping: str,
+    **kw: Any,
+) -> Never: ...
 @overload  # no namespace
 def Extension(
     module: object | ModuleType,
-    function_mapping: dict[str, str] | Collection[str] | None = None,
+    function_mapping: dict[str, str] | Iterable[str] | None = None,
     *,
     ns: None = None,
 ) -> dict[tuple[None, str], Callable[..., Any]]: ...
 @overload  # namespace present
 def Extension(
     module: object | ModuleType,
-    function_mapping: dict[str, str] | Collection[str] | None = None,
+    function_mapping: dict[str, str] | Iterable[str] | None = None,
     *,
     ns: str,
 ) -> dict[tuple[str, str], Callable[..., Any]]: