lxml-stubs: Type Annotations for lxml

0.5.1 · active · verified Thu Apr 09

lxml-stubs provides high-quality type annotations (`.pyi` files) for the popular `lxml` library, enabling robust static type checking with tools like MyPy. It is currently at version 0.5.1 and is released irregularly, typically in response to updates in `lxml` or bug fixes in the stubs themselves.

Warnings

gotcha lxml-stubs provides type information only and does NOT install the lxml library itself. You MUST install both `lxml` and `lxml-stubs` for the type annotations to be useful.
Fix: Always install `pip install lxml lxml-stubs`.
gotcha lxml-stubs is for static type checking purposes only. It does not alter the runtime behavior or functionality of the lxml library.
Fix: Understand that lxml-stubs is a developer tool to aid in writing type-safe code, not a runtime dependency that changes lxml's behavior.
gotcha While efforts are made to keep lxml-stubs in sync with lxml, breaking changes in lxml or new features might not immediately have corresponding type annotations in lxml-stubs, leading to type checker errors or incomplete type coverage.
Fix: Check the lxml-stubs GitHub repository for release notes and issues if you encounter unexpected type errors with recent lxml versions. Consider pinning both lxml and lxml-stubs versions in production to ensure compatibility.

Install

pip install lxml lxml-stubs Install both lxml and lxml-stubs

Imports

Element
```
from lxml import etree; root: etree._Element = etree.fromstring(...)
```
lxml-stubs does not expose symbols for direct import. Instead, it provides type information for symbols imported from the 'lxml' package (e.g., 'lxml.etree.Element'), allowing type checkers like MyPy to validate your lxml code.

Quickstart

This quickstart demonstrates how to use `lxml` with type annotations. By installing `lxml-stubs` alongside `lxml`, type checkers like MyPy can correctly infer and validate the types of `lxml` objects and methods.

from lxml import etree
from typing import List

# lxml-stubs provides the type hints for lxml objects
def parse_and_find(xml_string: str, xpath_expr: str) -> List[etree.Element]:
    # root will be correctly typed as etree._Element
    root: etree._Element = etree.fromstring(xml_string.encode('utf-8'))
    # elements will be correctly typed as List[etree.Element]
    elements: List[etree.Element] = root.xpath(xpath_expr)
    return elements

xml_data = "<root><item id='1'/><item id='2'/></root>"
found_items = parse_and_find(xml_data, "//item")

for item in found_items:
    print(f"Found item with ID: {item.get('id')}")

# To verify type checking:
# 1. Save the above code as 'example.py'
# 2. Ensure 'lxml' and 'lxml-stubs' are installed:
#    pip install lxml lxml-stubs
# 3. Run a type checker: mypy example.py
#    Expected output: Success (no errors)

view raw JSON →