[![PyPI version](https://img.shields.io/pypi/v/types-lxml.svg)](https://pypi.org/project/types-lxml/)
![Supported Python](https://img.shields.io/pypi/pyversions/types-lxml.svg)
![Wheel](https://img.shields.io/pypi/wheel/types-lxml.svg)
## Important note
- `types-lxml 2024.03.27` release requires [cssselect package](https://pypi.org/project/cssselect/) to work, since `lxml.cssselect` submodule utilises inline annotation from `cssselect 1.2.0`.
- Next release (`2024.04.14`) requires `mypy 1.9`; `2024.03.27` is the last release supporting `mypy 1.5`.
## Introduction
This repository contains [external type annotations](https://peps.python.org/pep-0561/) for [`lxml`](http://lxml.de/). It can be used by type-checking tools (currently supporting [`mypy`](https://pypi.org/project/mypy/) and [`pyright`](https://github.com/Microsoft/pyright)) to check code that uses `lxml`, or used within IDEs like [VSCode](https://code.visualstudio.com/) or [PyCharm](https://www.jetbrains.com/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`](https://peps.python.org/pep-0561/#partial-stub-packages):
- [x] `lxml.etree`
- [x] `lxml.html`
- [x] `lxml.html.builder`
- [x] `lxml.html.clean` (already removed in lxml 5.2.0, this project will follow suite in future)
- [x] `lxml.html.diff`
- [x] `lxml.html.html5parser`
- [x] `lxml.html.soupparser`
- [x] `lxml.isoschematron`
- [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`)
Check out [project page](https://github.com/abelcheung/types-lxml/projects/1) 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
- [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
- [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 (under progress)
- [x] 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:
![Stub docstring in VSCode mouseover tooltip](https://user-images.githubusercontent.com/83110/277119481-debbd929-afbd-4f59-b9e6-52a1f7f23241.png)
Besides docstring, current annotations are geared towards convenience for code writers instead of absolute logical 'correctness'. The [deviation of class inheritance](https://github.com/abelcheung/types-lxml/wiki/Element-inheritance-change) 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](https://github.com/abelcheung/types-lxml/releases/latest) 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](https://www.github.com/python/typeshed), but as it was still incomplete at that time, the stubs are [ripped out as a separate project](https://github.com/python/typeshed/issues/525). 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "types-lxml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "lxml, typing, stubs, annotation",
"author": null,
"author_email": "Abel Cheung <abelcheung@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3e/9f/598ba40c0107eb4debe55ab52a7007996690e24c77ff779dee14054f6e27/types_lxml-2024.4.14.tar.gz",
"platform": null,
"description": "[![PyPI version](https://img.shields.io/pypi/v/types-lxml.svg)](https://pypi.org/project/types-lxml/)\n![Supported Python](https://img.shields.io/pypi/pyversions/types-lxml.svg)\n![Wheel](https://img.shields.io/pypi/wheel/types-lxml.svg)\n\n## Important note\n\n- `types-lxml 2024.03.27` release requires [cssselect package](https://pypi.org/project/cssselect/) to work, since `lxml.cssselect` submodule utilises inline annotation from `cssselect 1.2.0`.\n- Next release (`2024.04.14`) requires `mypy 1.9`; `2024.03.27` is the last release supporting `mypy 1.5`.\n\n## Introduction\n\nThis repository contains [external type annotations](https://peps.python.org/pep-0561/) for [`lxml`](http://lxml.de/). It can be used by type-checking tools (currently supporting [`mypy`](https://pypi.org/project/mypy/) and [`pyright`](https://github.com/Microsoft/pyright)) to check code that uses `lxml`, or used within IDEs like [VSCode](https://code.visualstudio.com/) or [PyCharm](https://www.jetbrains.com/pycharm/) to facilitate development.\n\n## Goal \u2460 : Completion\n\nNow 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):\n - [x] `lxml.etree`\n - [x] `lxml.html`\n - [x] `lxml.html.builder`\n - [x] `lxml.html.clean` (already removed in lxml 5.2.0, this project will follow suite in future)\n - [x] `lxml.html.diff`\n - [x] `lxml.html.html5parser`\n - [x] `lxml.html.soupparser`\n - [x] `lxml.isoschematron`\n - [x] `lxml.objectify`\n - [x] `lxml.builder`\n - [x] `lxml.cssselect`\n - [x] `lxml.sax`\n - [x] `lxml.ElementInclude`\n\nFollowing submodules will not be implemented due to irrelevance to type checking or other reasons:\n\n - `lxml.etree.Schematron` (obsolete and superseded by `lxml.isoschematron`)\n - `lxml.usedoctest`\n - `lxml.html.usedoctest`\n - `lxml.html.formfill` (shouldn't have existed, this would belong to HTTP libraries like `requests` or `httpx`)\n\nCheck out [project page](https://github.com/abelcheung/types-lxml/projects/1) for future plans and progress.\n\n## Goal \u2461 : Support multiple type checkers\n\nCurrently the annotations are validated for both `mypy` and `pyright`.\n\nIn the future, there is plan to bring even more type checker support.\n\n## Goal \u2462: Review and test suite\n\n- [x] All prior `lxml-stubs` contributions are reviewed thoroughly, bringing coherency of annotation across the whole package\n- [x] Much more extensive test cases\n - [x] Mypy test suite already vastly expanded\n - [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\n - [x] Proof of concept for incorporating `pyright` result under progress, currently just comparing `reveal_type()` results\n - [ ] Migrate static `mypy` tests to runtime `pyright` tests in future (under progress)\n- [x] Modernize package building infrastructure\n\n## Goal \u2463 : Support for IDEs\n\nDespite 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:\n\n![Stub docstring in VSCode mouseover tooltip](https://user-images.githubusercontent.com/83110/277119481-debbd929-afbd-4f59-b9e6-52a1f7f23241.png)\n\nBesides docstring, current annotations are geared towards convenience for code writers instead of absolute logical 'correctness'. The [deviation of class inheritance](https://github.com/abelcheung/types-lxml/wiki/Element-inheritance-change) for `HtmlComment` and friends is one prominent example.\n\n\n## Installation\n\nThe normal choice for most people is to fetch package from PyPI via `pip`:\n\n pip install -U types-lxml\n\nThere are a few other alternatives though.\n\n### From downloaded wheel file\n\nHead over to [latest release in GitHub](https://github.com/abelcheung/types-lxml/releases/latest) and download wheel file (with extension `.whl`), which can be installed in the same way as PyPI package:\n\n pip install -U types-lxml*.whl\n\n### Bleeding edge from GitHub\n\n pip install -U git+https://github.com/abelcheung/types-lxml.git\n\n\n## History\n\nType annotations for `lxml` were initially included in [typeshed](https://www.github.com/python/typeshed), but as it was still incomplete at that time, the stubs are [ripped out as a separate project](https://github.com/python/typeshed/issues/525). 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.\n\n`types-lxml` is a fork of `lxml-stubs` that strives for the goals described above, so that most people would find it more useful.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Complete lxml external type annotation",
"version": "2024.4.14",
"project_urls": {
"homepage": "https://github.com/abelcheung/types-lxml"
},
"split_keywords": [
"lxml",
" typing",
" stubs",
" annotation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "957e0a746c8ae33846c6240af166979e23a0f7ac70c8a6fbb2277d71389ae191",
"md5": "ed2146d5432f304799f363e0e8ff43c9",
"sha256": "7e5f836067cde4fddce3cdbf2bac7192c764bf5ee6d3eb86c732ad1b84f265c5"
},
"downloads": -1,
"filename": "types_lxml-2024.4.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed2146d5432f304799f363e0e8ff43c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 75588,
"upload_time": "2024-04-14T04:26:12",
"upload_time_iso_8601": "2024-04-14T04:26:12.798615Z",
"url": "https://files.pythonhosted.org/packages/95/7e/0a746c8ae33846c6240af166979e23a0f7ac70c8a6fbb2277d71389ae191/types_lxml-2024.4.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3e9f598ba40c0107eb4debe55ab52a7007996690e24c77ff779dee14054f6e27",
"md5": "981eb6572db443899c36d906e185bd68",
"sha256": "dd8105b579925af1b6ae77469f4fc835be3872b15e86cb46ad4fcc33b20c781d"
},
"downloads": -1,
"filename": "types_lxml-2024.4.14.tar.gz",
"has_sig": false,
"md5_digest": "981eb6572db443899c36d906e185bd68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 114715,
"upload_time": "2024-04-14T04:26:14",
"upload_time_iso_8601": "2024-04-14T04:26:14.519405Z",
"url": "https://files.pythonhosted.org/packages/3e/9f/598ba40c0107eb4debe55ab52a7007996690e24c77ff779dee14054f6e27/types_lxml-2024.4.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 04:26:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abelcheung",
"github_project": "types-lxml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "types-beautifulsoup4",
"specs": []
},
{
"name": "typing_extensions",
"specs": [
[
"~=",
"4.5"
]
]
},
{
"name": "cssselect",
"specs": [
[
"~=",
"1.2"
]
]
}
],
"tox": true,
"lcname": "types-lxml"
}