beautifulsoup4 stub improvements (#5907)

stubs/beautifulsoup4/bs4/element.pyi

@@ -1,5 +1,5 @@
 from _typeshed import Self
-from typing import Any, Callable, Iterable, List, Mapping, Pattern, Set, Tuple, Type, TypeVar, Union, overload
+from typing import Any, Callable, Generic, Iterable, List, Mapping, Pattern, Set, Tuple, Type, TypeVar, Union, overload
 
 from . import BeautifulSoup
 from .builder import TreeBuilder
@@ -33,14 +33,14 @@ _SimpleNormalizedStrainable = Union[str, bool, None, Pattern[str], Callable[[str
 _NormalizedStrainable = Union[_SimpleNormalizedStrainable, Iterable[_SimpleNormalizedStrainable]]
 
 class PageElement:
-    parent: PageElement | None
+    parent: Tag | None
     previous_element: PageElement | None
     next_element: PageElement | None
     next_sibling: PageElement | None
     previous_sibling: PageElement | None
     def setup(
         self,
-        parent: PageElement | None = ...,
+        parent: Tag | None = ...,
         previous_element: PageElement | None = ...,
         next_element: PageElement | None = ...,
         previous_sibling: PageElement | None = ...,
@@ -59,7 +59,7 @@ class PageElement:
     def extract(self: Self, _self_index: int | None = ...) -> Self: ...
     def insert(self, position: int, new_child: PageElement) -> None: ...
     def append(self, tag: PageElement) -> None: ...
-    def extend(self, tags: Tag | Iterable[PageElement]) -> None: ...
+    def extend(self, tags: Iterable[PageElement]) -> None: ...
     def insert_before(self, *args: PageElement) -> None: ...
     def insert_after(self, *args: PageElement) -> None: ...
     def find_next(
@@ -77,7 +77,7 @@ class PageElement:
         text: _Strainable | None = ...,
         limit: int | None = ...,
         **kwargs: _Strainable,
-    ) -> ResultSet: ...
+    ) -> ResultSet[PageElement]: ...
     findAllNext = find_all_next
     def find_next_sibling(
         self,
@@ -94,7 +94,7 @@ class PageElement:
         text: _Strainable | None = ...,
         limit: int | None = ...,
         **kwargs: _Strainable,
-    ) -> ResultSet: ...
+    ) -> ResultSet[PageElement]: ...
     findNextSiblings = find_next_siblings
     fetchNextSiblings = find_next_siblings
     def find_previous(
@@ -112,7 +112,7 @@ class PageElement:
         text: _Strainable | None = ...,
         limit: int | None = ...,
         **kwargs: _Strainable,
-    ) -> ResultSet: ...
+    ) -> ResultSet[PageElement]: ...
     findAllPrevious = find_all_previous
     fetchPrevious = find_all_previous
     def find_previous_sibling(
@@ -130,7 +130,7 @@ class PageElement:
         text: _Strainable | None = ...,
         limit: int | None = ...,
         **kwargs: _Strainable,
-    ) -> ResultSet: ...
+    ) -> ResultSet[PageElement]: ...
     findPreviousSiblings = find_previous_siblings
     fetchPreviousSiblings = find_previous_siblings
     def find_parent(
@@ -138,7 +138,7 @@ class PageElement:
         name: _Strainable | SoupStrainer | None = ...,
         attrs: dict[str, _Strainable] | _Strainable = ...,
         **kwargs: _Strainable,
-    ) -> Tag | NavigableString | None: ...
+    ) -> Tag | None: ...
     findParent = find_parent
     def find_parents(
         self,
@@ -146,7 +146,7 @@ class PageElement:
         attrs: dict[str, _Strainable] | _Strainable = ...,
         limit: int | None = ...,
         **kwargs: _Strainable,
-    ) -> ResultSet: ...
+    ) -> ResultSet[Tag]: ...
     findParents = find_parents
     fetchParents = find_parents
     @property
@@ -162,14 +162,14 @@ class PageElement:
     @property
     def previous_siblings(self) -> Iterable[PageElement]: ...
     @property
-    def parents(self) -> Iterable[PageElement]: ...
+    def parents(self) -> Iterable[Tag]: ...
     @property
     def decomposed(self) -> bool: ...
     def nextGenerator(self) -> Iterable[PageElement]: ...
     def nextSiblingGenerator(self) -> Iterable[PageElement]: ...
     def previousGenerator(self) -> Iterable[PageElement]: ...
     def previousSiblingGenerator(self) -> Iterable[PageElement]: ...
-    def parentGenerator(self) -> Iterable[PageElement]: ...
+    def parentGenerator(self) -> Iterable[Tag]: ...
 
 class NavigableString(str, PageElement):
     PREFIX: str
@@ -227,8 +227,8 @@ class Tag(PageElement):
     sourceline: int | None
     sourcepos: int | None
     known_xml: bool | None
-    attrs: Mapping[str, Any]
-    contents: Any
+    attrs: Mapping[str, str]
+    contents: List[PageElement]
     hidden: bool
     can_be_empty_element: bool | None
     cdata_list_attributes: list[str] | None
@@ -240,8 +240,8 @@ class Tag(PageElement):
         name: str | None = ...,
         namespace: str | None = ...,
         prefix: str | None = ...,
-        attrs: Mapping[str, Any] | None = ...,
-        parent: PageElement | None = ...,
+        attrs: Mapping[str, str] | None = ...,
+        parent: Tag | None = ...,
         previous: PageElement | None = ...,
         is_xml: bool | None = ...,
         sourceline: int | None = ...,
@@ -282,7 +282,7 @@ class Tag(PageElement):
     def __bool__(self) -> bool: ...
     def __setitem__(self, key: str, value: str | list[str]) -> None: ...
     def __delitem__(self, key: str) -> None: ...
-    def __getattr__(self, tag: str) -> Tag | NavigableString | None: ...
+    def __getattr__(self, tag: str) -> Tag | None: ...
     def __eq__(self, other: object) -> bool: ...
     def __ne__(self, other: object) -> bool: ...
     def __unicode__(self) -> str: ...
@@ -316,7 +316,7 @@ class Tag(PageElement):
         text: _Strainable | None = ...,
         limit: int | None = ...,
         **kwargs: _Strainable,
-    ) -> ResultSet: ...
+    ) -> ResultSet[PageElement]: ...
     __call__ = find_all
     findAll = find_all
     findChildren = find_all
@@ -325,7 +325,7 @@ class Tag(PageElement):
     @property
     def descendants(self) -> Iterable[PageElement]: ...
     def select_one(self, selector: str, namespaces: Any | None = ..., **kwargs) -> Tag | None: ...
-    def select(self, selector: str, namespaces: Any | None = ..., limit: int | None = ..., **kwargs) -> ResultSet: ...
+    def select(self, selector: str, namespaces: Any | None = ..., limit: int | None = ..., **kwargs) -> ResultSet[Tag]: ...
     def childGenerator(self) -> Iterable[PageElement]: ...
     def recursiveChildGenerator(self) -> Iterable[PageElement]: ...
     def has_key(self, key: str) -> bool: ...
@@ -345,6 +345,6 @@ class SoupStrainer:
     searchTag = search_tag
     def search(self, markup: PageElement | Iterable[PageElement]): ...
 
-class ResultSet(List[PageElement]):
+class ResultSet(Generic[_PageElementT], List[_PageElementT]):
     source: SoupStrainer
-    def __init__(self, source: SoupStrainer, result: Iterable[PageElement] = ...) -> None: ...
+    def __init__(self, source: SoupStrainer, result: Iterable[_PageElementT] = ...) -> None: ...