{"id":2108,"library":"lxml-stubs","title":"lxml-stubs: Type Annotations for lxml","description":"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.","status":"active","version":"0.5.1","language":"en","source_language":"en","source_url":"https://github.com/lxml/lxml-stubs","tags":["type-hints","stubs","lxml","xml","html","static-analysis"],"install":[{"cmd":"pip install lxml lxml-stubs","lang":"bash","label":"Install both lxml and lxml-stubs"}],"dependencies":[{"reason":"lxml-stubs provides type annotations FOR the lxml library. It is functionally useless without lxml being installed alongside it.","package":"lxml","optional":false}],"imports":[{"note":"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.","symbol":"Element","correct":"from lxml import etree; root: etree._Element = etree.fromstring(...)"}],"quickstart":{"code":"from lxml import etree\nfrom typing import List\n\n# lxml-stubs provides the type hints for lxml objects\ndef parse_and_find(xml_string: str, xpath_expr: str) -> List[etree.Element]:\n    # root will be correctly typed as etree._Element\n    root: etree._Element = etree.fromstring(xml_string.encode('utf-8'))\n    # elements will be correctly typed as List[etree.Element]\n    elements: List[etree.Element] = root.xpath(xpath_expr)\n    return elements\n\nxml_data = \"<root><item id='1'/><item id='2'/></root>\"\nfound_items = parse_and_find(xml_data, \"//item\")\n\nfor item in found_items:\n    print(f\"Found item with ID: {item.get('id')}\")\n\n# To verify type checking:\n# 1. Save the above code as 'example.py'\n# 2. Ensure 'lxml' and 'lxml-stubs' are installed:\n#    pip install lxml lxml-stubs\n# 3. Run a type checker: mypy example.py\n#    Expected output: Success (no errors)","lang":"python","description":"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."},"warnings":[{"fix":"Always install `pip install lxml lxml-stubs`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"lxml-stubs is for static type checking purposes only. It does not alter the runtime behavior or functionality of the lxml library.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}