chore: import upstream snapshot with attribution

lightrag/parser/plugins.py

@@ -0,0 +1,66 @@
+"""Third-party parser engine discovery (``lightrag.parsers`` entry points).
+
+A third-party package exposes parser engines by declaring an entry point in
+the ``lightrag.parsers`` group::
+
+    # pyproject.toml of the third-party package
+    [project.entry-points."lightrag.parsers"]
+    myengine = "my_pkg.lightrag_plugin:register"
+
+Each entry point must resolve to a **zero-argument callable** that performs
+its own :func:`lightrag.parser.registry.register_parser` call(s).  The
+callable should be import-cheap: defer the parser implementation import to
+the ``ParserSpec.impl`` string (the registry already loads it lazily).
+
+:func:`load_third_party_parsers` is invoked once per process by both
+entrypoints that drive parsers — the API server (``create_app``, before
+routing-rule validation so ``LIGHTRAG_PARSER`` may reference third-party
+engine names) and the debug CLI (``lightrag.parser.cli.main``, before
+``--engine`` choices are built).  Library users embedding LightRAG directly
+can call it themselves before constructing pipelines.
+
+See ``docs/ThirdPartyParser-zh.md`` for the full plugin authoring guide.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+
+ENTRY_POINT_GROUP = "lightrag.parsers"
+
+logger = logging.getLogger("lightrag")
+
+_loaded = False
+
+
+def load_third_party_parsers(*, force: bool = False) -> list[str]:
+    """Discover and run all ``lightrag.parsers`` entry points.
+
+    Idempotent per process (``force=True`` re-runs, for tests).  Returns the
+    names of the entry points that loaded successfully.  A failing plugin is
+    logged with its origin and skipped — one broken third-party package must
+    not take down server startup or the debug CLI; the built-in engines are
+    registered statically and are never affected.
+    """
+    global _loaded
+    if _loaded and not force:
+        return []
+    _loaded = True
+
+    loaded: list[str] = []
+    for ep in entry_points(group=ENTRY_POINT_GROUP):
+        try:
+            register = ep.load()
+            register()
+        except Exception as e:
+            logger.error(
+                "[parser-plugins] failed to load parser plugin %r (%s): %s",
+                ep.name,
+                ep.value,
+                e,
+            )
+            continue
+        loaded.append(ep.name)
+        logger.info("[parser-plugins] loaded parser plugin %r (%s)", ep.name, ep.value)
+    return loaded