Formatting, doc and cosmetics

README.md

@@ -6,27 +6,24 @@ This repository contains [external type annotations](https://peps.python.org/pep
 
 ## Goal ①: Completion
 
-Now the coverage of major `lxml` submodules is complete, thus no more [considered as `partial`](https://peps.python.org/pep-0561/#partial-stub-packages):
-  - [x] `lxml.etree`: 100%
-    - `etree.Schematron` is obsolete and superseded by `lxml.isoschematron`, so won't implement
-  - [x] `lxml.html` proper: 100%
-  - [x] `lxml.objectify`: 100%
-  - [x] `lxml.builder`: 100%
-  - [x] `lxml.cssselect`: 100%
-  - [x] `lxml.sax`: 100%
-
-Following list reflects current situation for less used `lxml` / `html` submodules:
-
-  - [x] `lxml.ElementInclude`
+Now the coverage of `lxml` submodules is complete (unless intentionally rejected, see further below), thus no more [considered as `partial`](https://peps.python.org/pep-0561/#partial-stub-packages):
+  - [x] `lxml.etree`
+  - [x] `lxml.html`
+    - [x] `lxml.html.builder`
+    - [x] `lxml.html.clean`
+    - [x] `lxml.html.diff`
+    - [x] `lxml.html.html5parser`
+    - [x] `lxml.html.soupparser`
   - [x] `lxml.isoschematron`
-  - [x] `lxml.html.builder`
-  - [x] `lxml.html.clean`
-  - [x] `lxml.html.diff`
-  - [x] `lxml.html.html5parser`
-  - [x] `lxml.html.soupparser`
+  - [x] `lxml.objectify`
+  - [x] `lxml.builder`
+  - [x] `lxml.cssselect`
+  - [x] `lxml.sax`
+  - [x] `lxml.ElementInclude`
 
 Following submodules will not be implemented due to irrelevance to type checking or other reasons:
 
+  - `lxml.etree.Schematron` (obsolete and superseded by `lxml.isoschematron`)
   - `lxml.usedoctest`
   - `lxml.html.usedoctest`
   - `lxml.html.formfill` (shouldn't have existed, this would belong to HTTP libraries like `requests` or `httpx`)
@@ -44,11 +41,9 @@ In the future, there is plan to bring even more type checker support.
 - [x] All prior `lxml-stubs` contributions are reviewed thoroughly, bringing coherency of annotation across the whole package
 - [x] Much more extensive test cases
   - [x] Mypy test suite already vastly expanded
-    - But still, only managed to cover about half of the whole package
-  - [x] Perform runtime check, and compare against static type checker result
-    - This guarantees annotations are indeed valid
-    - [x] Proof of concept for incorporating `pyright` result under progress
-    - [ ] `mypy` support under consideration later
+  - [x] Perform runtime check, and compare against static type checker result; this guarantees annotations are indeed working in real code, not just in some cooked up test suite
+    - [x] Proof of concept for incorporating `pyright` result under progress, currently just comparing `reveal_type()` results
+    - [ ] Migrate static `mypy` tests to runtime `pyright` tests in future
 - [x] Modernize package building infrastructure
 
 ## Goal ④: Support for IDEs

lxml-stubs/ElementInclude.pyi

@@ -1,8 +1,9 @@
 from typing import Any, Callable, Literal, overload
 
-from ._types import _ET, _FilePath
 from lxml.etree import LxmlSyntaxError, _Element, _ElementTree
 
+from ._types import _ET, _FilePath
+
 class FatalIncludeError(LxmlSyntaxError): ...
 class LimitedRecursiveIncludeError(FatalIncludeError): ...
 

lxml-stubs/etree/_iterparse.pyi

@@ -139,7 +139,7 @@ class iterparse(Iterator[_T_co]):
     def __new__(
         cls,
         source: _FilePath | IO[bytes] | SupportsReadClose[bytes],
-        events: Iterable[Literal['start-ns', 'end-ns']],
+        events: Iterable[Literal["start-ns", "end-ns"]],
         *,
         tag: _TagSelector | Iterable[_TagSelector] | None = ...,
         attribute_defaults: bool = ...,
@@ -159,8 +159,8 @@ class iterparse(Iterator[_T_co]):
         collect_ids: bool = ...,
         schema: XMLSchema | None = ...,
     ) -> iterparse[
-            tuple[Literal['start-ns'], tuple[str, str]]
-            | tuple[Literal['end-ns'], None]]: ...
+        tuple[Literal["start-ns"], tuple[str, str]] | tuple[Literal["end-ns"], None]
+    ]: ...
     @overload  # xml mode, catch all
     def __new__(
         cls,
@@ -186,8 +186,8 @@ class iterparse(Iterator[_T_co]):
         schema: XMLSchema | None = ...,
     ) -> iterparse[
         tuple[_NoNSEventNames, _Element]
-        | tuple[Literal['start-ns'], tuple[str, str]]
-        | tuple[Literal['end-ns'], None]
+        | tuple[Literal["start-ns"], tuple[str, str]]
+        | tuple[Literal["end-ns"], None]
     ]: ...
     def __next__(self) -> _T_co: ...
     # root property only present after parsing is done
@@ -257,11 +257,10 @@ class iterwalk(Iterator[_T_co]):
     def __new__(
         cls,
         element_or_tree: _ET_co | _ElementTree[_ET_co],
-        events: Iterable[Literal['start-ns', 'end-ns']],
+        events: Iterable[Literal["start-ns", "end-ns"]],
         tag: _TagSelector | Iterable[_TagSelector] | None = ...,
     ) -> iterwalk[
-        tuple[Literal['start-ns'], tuple[str, str]]
-        | tuple[Literal['end-ns'], None]
+        tuple[Literal["start-ns"], tuple[str, str]] | tuple[Literal["end-ns"], None]
     ]: ...
     @overload  # catch-all
     def __new__(
@@ -271,8 +270,8 @@ class iterwalk(Iterator[_T_co]):
         tag: _TagSelector | Iterable[_TagSelector] | None = ...,
     ) -> iterwalk[
         tuple[_NoNSEventNames, _ET_co]
-        | tuple[Literal['start-ns'], tuple[str, str]]
-        | tuple[Literal['end-ns'], None]
+        | tuple[Literal["start-ns"], tuple[str, str]]
+        | tuple[Literal["end-ns"], None]
     ]: ...
     def __next__(self) -> _T_co: ...
     def skip_subtree(self) -> None: ...

lxml-stubs/etree/_parser.pyi

@@ -85,7 +85,9 @@ class _FeedParser(Generic[_ET_co]):
         ```
         """
         ...
-    @deprecated("Removed since 5.0; deprecated since v2.0 (2008); renamed to set_element_class_lookup()")
+    @deprecated(
+        "Removed since 5.0; deprecated since v2.0 (2008); renamed to set_element_class_lookup()"
+    )
     def setElementClassLookup(
         self, lookup: ElementClassLookup | None = ...
     ) -> None: ...

lxml-stubs/etree/_xpath.pyi

@@ -42,7 +42,9 @@ class _XPathEvaluatorBase(Protocol):
     def __call__(self, _arg: Any, /, **__var: _XPathVarArg) -> _XPathObject: ...
     # evaluate() should have been abstract like __call__(), but requiring all
     # subclasses to add deprecated method is idiocy
-    @deprecated("Removed since 5.0; deprecated since v2.0 (2008); call the object directly")
+    @deprecated(
+        "Removed since 5.0; deprecated since v2.0 (2008); call the object directly"
+    )
     def evaluate(self, _arg: Any, /, **__var: _XPathVarArg) -> _XPathObject: ...
 
 class XPath(_XPathEvaluatorBase):

lxml-stubs/etree/_xslt.pyi

@@ -152,7 +152,9 @@ class XSLT:
     def strparam(strval: _AnyStr) -> _XSLTQuotedStringParam: ...
     @staticmethod
     def set_global_max_depth(max_depth: int) -> None: ...
-    @deprecated("Removed since 5.0; deprecated since v2.0 (2008); call instance directly instead")
+    @deprecated(
+        "Removed since 5.0; deprecated since v2.0 (2008); call instance directly instead"
+    )
     def apply(
         self,
         _input: _ElementOrTree,

lxml-stubs/html/clean.pyi

@@ -10,7 +10,7 @@ from ._funcs import _HtmlDoc_T, _HtmlElemOrTree
 _HTagSelector: TypeAlias = Union[str, bytes, _ElemFactory[_Element]]
 
 # Similar to _funcs._HtmlDoc_T, but also supports ET; only used in Cleaner
-_DT = TypeVar('_DT', str, bytes, HtmlElement, _ElementTree[HtmlElement])
+_DT = TypeVar("_DT", str, bytes, HtmlElement, _ElementTree[HtmlElement])
 
 class Cleaner:
     # allow_tags and remove_unknown_tags can't coexist

pyproject.toml

@@ -18,7 +18,7 @@ authors = [
     { name = 'Abel Cheung', email = 'abelcheung@gmail.com' }
 ]
 classifiers = [
-    'Development Status :: 4 - Beta',
+    'Development Status :: 5 - Production/Stable',
     'Programming Language :: Python',
     'Intended Audience :: Developers',
     'Programming Language :: Python :: 3 :: Only',
@@ -40,7 +40,7 @@ dev = [
     'black',
     'isort >= 5',
     'mypy >= 1.1, < 1.4',
-    'pyright == 1.1.*, >= 1.1.289, < 1.1.332',
+    'pyright >= 1.1.289, < 1.1.332',
     'lxml == 4.9.*',
     'typeguard == 3.0.*'
 ]

tox.ini

@@ -49,7 +49,7 @@ commands = mypy {posargs:lxml-stubs}
 
 [testenv:pyright]
 deps =
-    pyright == 1.1.*, >= 1.1.289, < 1.1.332
+    pyright >= 1.1.289, < 1.1.332
     {[common_dep]deps}
 package = skip
 commands = pyright {posargs:lxml-stubs}