Package: types-lxml
Important noteCurrentlytypes-lxmlshouldn't be used withmypy≥ 1.6. The untested 1.6.0simply segfaults, while all later versions don't support@overloadwith@deprecation, which isscheduled for Python 3.13.IntroductionThis repository containsexternal type annotationsforlxml. It can be used by type-checking tools (currently supportingmypyandpyright) to check code that useslxml, or used within IDEs likeVSCodeorPyCharmto facilitate development.Goal ① : CompletionNow the coverage oflxmlsubmodules is complete (unless intentionally rejected, see further below), thus no moreconsidered aspartial:lxml.etreelxml.htmllxml.html.builderlxml.html.cleanlxml.html.difflxml.html.html5parserlxml.html.soupparserlxml.isoschematronlxml.objectifylxml.builderlxml.cssselectlxml.saxlxml.ElementIncludeFollowing submodules will not be implemented due to irrelevance to type checking or other reasons:lxml.etree.Schematron(obsolete and superseded bylxml.isoschematron)lxml.usedoctestlxml.html.usedoctestlxml.html.formfill(shouldn't have existed, this would belong to HTTP libraries likerequestsorhttpx)Check outproject pagefor future plans and progress.Goal ② : Support multiple type checkersCurrently the annotations are validated for bothmypyandpyrightstrict mode.In the future, there is plan to bring even more type checker support.Goal ③: Review and test suiteAll priorlxml-stubscontributions are reviewed thoroughly, bringing coherency of annotation across the whole packageMuch more extensive test casesMypy test suite already vastly expandedPerform 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 suiteProof of concept for incorporatingpyrightresult under progress, currently just comparingreveal_type()resultsMigrate staticmypytests to runtimepyrighttests in futureModernize package building infrastructureGoal ④ : Support for IDEsDespite having no official PEP, some IDEs support showing docstring from external annotations. This package tries to bring type annotation specific docstrings for somelxmlclasses 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'. Thedeviation of class inheritanceforHtmlCommentand friends is one prominent example.InstallationThe normal choice for most people is to fetch package from PyPI viapip:pip install -U types-lxmlThere are a few other alternatives though.From downloaded wheel fileHead over tolatest release in GitHuband download wheel file (with extension.whl), which can be installed in the same way as PyPI package:pip install -U types-lxml*.whlBleeding edge from GitHubpip install -U git+https://github.com/abelcheung/types-lxml.gitSpecial notesType checker supportActually,pyrightis the preferred type checker to use forlxmlcode.mypycan be either too restrictive or doesn't support some feature needed by lxml.Here is one example: normalisation of element attributes.It is employed by many other projects, so that users can supply common type of value while setting object attributes, and the code internally canonicalise/converts supplied argument to specific type. This is a convenience for library users, so they don't always need to do internal conversion by themselves. Consider the example below:fromtyping_extensionsimportreveal_typefromlxml.etreeimportfromstring,QNameperson=fromstring('<person><height>170</height></person>')reveal_type(person[0].tag)person[0].tag=QName('http://ns.prefix',person[0].tag)Lxml supports stringify QNames when setting element tags. Of course, during runtime, everything work as expected:>>>print(e.tostring(person,encoding=str))<person><ns0:height xmlns:ns0="http://ns.prefix">170</ns0:height></person>pyrightcorrectly reports element tag type, and don't complain about assignment:information: Type of "person[0].tag" is "str"Butmypybarks loudly about the feature:error: Incompatible types in assignment (expression has type "QName", variable has type "str")  [assignment]There are many, many more places in lxml that employs such normalisation.ParserTargetThere is now only one stub-only classes that do not exist as concrete class inlxml—lxml.etree.ParserTarget. However the support of custom parser target is shelved, so this virtual class is not very relevant for now.HistoryType annotations forlxmlwere initially included intypeshed, but as it was still incomplete at that time, the stubs areripped out as a separate project. The code was extracted by Jelle Zijlstra and moved tolxml-stubsrepository usinggit filter-branch.types-lxmlis a fork oflxml-stubsthat strives for the goals described above, so that most people would find it more useful.