{"record":{"id":"fb34531ce17827bb","repo":"docling-project/docling","slug":"the-beautifulsoup4-and-defusedxml-packages-are","errorCode":null,"errorMessage":"The 'beautifulsoup4' and 'defusedxml' packages are required to process USPTO patent files. Install them with `pip install 'docling-slim[format-xml-uspto]'`.","messagePattern":"The 'beautifulsoup4' and 'defusedxml' packages are required to process USPTO patent files\\. Install them with `pip install 'docling-slim\\[format-xml-uspto\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/uspto_backend.py","lineNumber":114,"sourceCode":"    ABSTRACT = \"ABSTRACT\", 2\n    CLAIMS = \"CLAIMS\", 2\n\n    @override\n    def __new__(cls, value: str, _) -> Self:\n        obj = object.__new__(cls)\n        obj._value_ = value\n        return obj\n\n    @override\n    def __init__(self, _, level: LevelNumber) -> None:\n        self.level: LevelNumber = level\n\n\nclass PatentUsptoDocumentBackend(DeclarativeDocumentBackend):\n    @override\n    def __init__(self, in_doc: InputDocument, path_or_stream: BytesIO | Path) -> None:\n        if not _BS4_AVAILABLE:\n            raise ImportError(_INSTALL_HINT) from _BS4_IMPORT_ERROR\n        super().__init__(in_doc, path_or_stream)\n\n        self.patent_content: str = \"\"\n        self.parser: PatentUspto | None = None\n\n        try:\n            if isinstance(self.path_or_stream, BytesIO):\n                while line := self.path_or_stream.readline().decode(\"utf-8\"):\n                    if line.startswith(\"<!DOCTYPE\") or line == \"PATN\\n\":\n                        self._set_parser(line)\n                    self.patent_content += line\n            elif isinstance(self.path_or_stream, Path):\n                with open(self.path_or_stream, encoding=\"utf-8\") as file_obj:\n                    while line := file_obj.readline():\n                        if line.startswith(\"<!DOCTYPE\") or line == \"PATN\\n\":\n                            self._set_parser(line)\n                        self.patent_content += line\n        except Exception as exc:","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/uspto_backend.py#L96-L132","documentation":"The USPTO patent backend needs beautifulsoup4 and defusedxml, which are optional extras in docling-slim. Its __init__ checks _BS4_AVAILABLE and raises ImportError with the exact pip extra to install, chained to the original import error.","triggerScenarios":"Converting a USPTO patent XML (or the legacy aps/plain 'PATN' format) with docling-slim installed without the format-xml-uspto extra; PatentUsptoDocumentBackend.__init__ raises before any parsing.","commonSituations":"Slim container images for size; processing patent corpora after originally only needing PDF; CI env pinning docling-slim without extras.","solutions":["pip install 'docling-slim[format-xml-uspto]'.","Or install the full docling package which bundles the XML backends.","Verify with python -c 'import bs4, defusedxml' after installing.","Add the extra to your requirements/uv config so rebuilds keep it."],"exampleFix":"# before\npip install docling-slim\nDocumentConverter().convert(Path(\"patent.xml\"))  # ImportError\n\n# after\npip install 'docling-slim[format-xml-uspto]'\nDocumentConverter().convert(Path(\"patent.xml\"))","handlingStrategy":"validation","validationCode":"from importlib.util import find_spec\n\ndef uspto_dependencies_available() -> bool:\n    return find_spec(\"bs4\") is not None and find_spec(\"defusedxml\") is not None","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(patent_path)\nexcept ImportError as e:\n    if \"format-xml-uspto\" in str(e):\n        raise SystemExit(\"Install first: pip install 'docling-slim[format-xml-uspto]'\") from e\n    raise","preventionTips":["Install format extras for every InputFormat you will feed the converter.","Smoke-test backend imports in CI for the formats in your test corpus.","Track dependency changes when adding new document formats to a pipeline."],"tags":["uspto","xml","import-error","dependencies","docling-slim","patents"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}