Complete lxml external type annotation
Project description
Important note
types-lxml 2024.03.27
release requires cssselect package to work, sincelxml.cssselect
submodule utilises inline annotation fromcssselect 1.2.0
.- Next release (
2024.04.14
) requiresmypy 1.9
;2024.03.27
is the last release supportingmypy 1.5
.
Introduction
This repository contains external type annotations for lxml
. It can be used by type-checking tools (currently supporting mypy
and pyright
) to check code that uses lxml
, or used within IDEs like VSCode or PyCharm to facilitate development.
Goal ① : Completion
Now the coverage of lxml
submodules is complete (unless intentionally rejected, see further below), thus no more considered as partial
:
-
lxml.etree
-
lxml.html
-
lxml.html.builder
-
lxml.html.clean
(already removed in lxml 5.2.0, this project will follow suite in future) -
lxml.html.diff
-
lxml.html.html5parser
-
lxml.html.soupparser
-
-
lxml.isoschematron
-
lxml.objectify
-
lxml.builder
-
lxml.cssselect
-
lxml.sax
-
lxml.ElementInclude
Following submodules will not be implemented due to irrelevance to type checking or other reasons:
lxml.etree.Schematron
(obsolete and superseded bylxml.isoschematron
)lxml.usedoctest
lxml.html.usedoctest
lxml.html.formfill
(shouldn't have existed, this would belong to HTTP libraries likerequests
orhttpx
)
Check out project page for future plans and progress.
Goal ② : Support multiple type checkers
Currently the annotations are validated for both mypy
and pyright
.
In the future, there is plan to bring even more type checker support.
Goal ③: Review and test suite
- All prior
lxml-stubs
contributions are reviewed thoroughly, bringing coherency of annotation across the whole package - Much more extensive test cases
- Mypy test suite already vastly expanded
- 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
- Proof of concept for incorporating
pyright
result under progress, currently just comparingreveal_type()
results - Migrate static
mypy
tests to runtimepyright
tests in future (under progress)
- Proof of concept for incorporating
- Modernize package building infrastructure
Goal ④ : Support for IDEs
Despite having no official PEP, some IDEs support showing docstring from external annotations. This package tries to bring type annotation specific docstrings for some lxml
classes and functions, explaining how they can be used. Following screenshots show what would look like in Visual Studio Code, behaving as if docstrings come from real python code:
Besides docstring, current annotations are geared towards convenience for code writers instead of absolute logical 'correctness'. The deviation of class inheritance for HtmlComment
and friends is one prominent example.
Installation
The normal choice for most people is to fetch package from PyPI via pip
:
pip install -U types-lxml
There are a few other alternatives though.
From downloaded wheel file
Head over to latest release in GitHub and download wheel file (with extension .whl
), which can be installed in the same way as PyPI package:
pip install -U types-lxml*.whl
Bleeding edge from GitHub
pip install -U git+https://github.com/abelcheung/types-lxml.git
History
Type annotations for lxml
were initially included in typeshed, but as it was still incomplete at that time, the stubs are ripped out as a separate project. The code was since then under governance of lxml, until 2022 when this fork intended to revamp lxml-stubs
completely and emerge into separate project.
types-lxml
is a fork of lxml-stubs
that strives for the goals described above, so that most people would find it more useful.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for types_lxml-2024.4.14-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7e5f836067cde4fddce3cdbf2bac7192c764bf5ee6d3eb86c732ad1b84f265c5 |
|
MD5 | ed2146d5432f304799f363e0e8ff43c9 |
|
BLAKE2b-256 | 957e0a746c8ae33846c6240af166979e23a0f7ac70c8a6fbb2277d71389ae191 |