docvortex 0.4.2__tar.gz → 0.4.3__tar.gz

{docvortex-0.4.2/src/docvortex.egg-info → docvortex-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.2
+Version: 0.4.3
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex
@@ -106,6 +106,8 @@ docvortex convert report.pdf --format markdown --output output/report.md
 
 Replace `report.pdf` with a local file in any supported input format.
 Use `--format` to choose the output; run `docvortex convert --help` for options.
+The root-level `--log-level` option controls loguru output and defaults to `info`.
+It must precede the command; `DOCVORTEX_LOG_LEVEL=warning` can also configure it.
 
 ### Python
 

{docvortex-0.4.2 → docvortex-0.4.3}/README.md

@@ -53,6 +53,8 @@ docvortex convert report.pdf --format markdown --output output/report.md
 
 Replace `report.pdf` with a local file in any supported input format.
 Use `--format` to choose the output; run `docvortex convert --help` for options.
+The root-level `--log-level` option controls loguru output and defaults to `info`.
+It must precede the command; `DOCVORTEX_LOG_LEVEL=warning` can also configure it.
 
 ### Python
 

{docvortex-0.4.2 → docvortex-0.4.3}/docs/USAGE.md

@@ -7,6 +7,20 @@ you need access to intermediate results. All examples use the public Python SDK.
 Install with `pip install docvortex` and replace `report.pdf` with a local text PDF.
 Each example can be run independently in a fresh output directory.
 
+## Global CLI log level
+
+The root-level `--log-level` option controls loguru output for CLI commands.
+It defaults to `info`, supports `trace`, `debug`, `info`, `warning`, `error` and
+`critical`, and must be placed before the subcommand:
+
+```bash
+docvortex --log-level debug convert report.pdf --format markdown --output output/report.md
+```
+
+`DOCVORTEX_LOG_LEVEL` provides the same setting through an environment variable.
+An explicit `--log-level` value takes precedence. SDK imports do not change the
+host application's existing loguru sinks.
+
 ## Stage APIs
 
 The pipeline has three stages:

{docvortex-0.4.2 → docvortex-0.4.3}/docs/sdk-0.4.md

@@ -18,6 +18,12 @@ MinerU 使用 `docvortex>=0.4.0,<0.5.0`。本轮调整 Python 模块边界，保
 
 `docvortex.public_api.PUBLIC_API` 是静态模块及符号清单。新增跨库依赖必须同时更新清单、文档和契约测试；不能通过基础实现、私有模块或动态别名绕过边界。
 
+## 结果包素材导出（0.4.3）
+
+跨库调用方可通过 `docvortex.export.materialize_middle(middle_json, assets=None)` 获取图片外置后的文档副本与 `AssetStore`，再通过 `validate_materialized_assets(document, assets)` 验证所有图片引用。直接图片和视觉 HTML 内嵌图片使用安全相对路径，原始图片字节及布局方向扩展保持不变；代码字面量不作为 HTML 素材处理。
+
+调用方负责将该副本及素材写入自己的结果包，不应先省略图片再从源 PDF 重裁。缺失引用、未物化网络图片或同名素材冲突会显式失败。物化不修改输入对象、不读取源 PDF、不下载网络资源；已有外部素材须通过 `AssetStore` 显式提供。
+
 ## 行为与资源所有权
 
 `prepare_text_evidence` 返回具名的 `PDFTextEvidence`，`apply_text_evidence` 统一完成链接、样式、脚本与 InlineSpan 物化。MinerU 仍决定调用时机、公式排除区域、超大字符页和 OCR 回退。

{docvortex-0.4.2 → docvortex-0.4.3}/src/docvortex/cli.py

@@ -3,16 +3,36 @@
 from __future__ import annotations
 
 from pathlib import Path
+import sys
 
 import click
+from loguru import logger
 
 from .version import __version__
 
 
+_LOG_LEVELS = ("trace", "debug", "info", "warning", "error", "critical")
+
+
+def _configure_log_level(level: str) -> None:
+    """按全局参数重建 loguru 标准错误输出，并过滤低于该等级的日志。"""
+    logger.remove()
+    logger.add(sys.stderr, level=level.upper())
+
+
 @click.group(help="DocVortex: native multi-format document parsing and conversion.")
 @click.version_option(__version__)
-def main() -> None:
-    """提供独立文档引擎的命令行入口。"""
+@click.option(
+    "--log-level",
+    type=click.Choice(_LOG_LEVELS, case_sensitive=False),
+    default="info",
+    show_default=True,
+    envvar="DOCVORTEX_LOG_LEVEL",
+    help="Global loguru log level; place this root option before the command.",
+)
+def main(log_level: str) -> None:
+    """提供独立文档引擎的命令行入口，并应用全局日志等级。"""
+    _configure_log_level(log_level)
 
 
 @main.command("convert")

docvortex-0.4.3/src/docvortex/export/__init__.py

@@ -0,0 +1,5 @@
+"""文档副本与素材字节的公开导出边界。"""
+
+from .files import materialize_middle, validate_materialized_assets
+
+__all__ = ["materialize_middle", "validate_materialized_assets"]

{docvortex-0.4.2 → docvortex-0.4.3}/src/docvortex/export/middle.py

@@ -58,7 +58,11 @@ def _prepare_export_copy(middle_json: MiddleJson) -> tuple[MiddleJson, dict[str,
                 block.image_base64 = None  # type: ignore[attr-defined]
 
             content = getattr(block, "content", None)
-            if not isinstance(content, str) or "data:image/" not in content:
+            if (
+                str(block.type) not in {"table_body", "chart_body", "image_body"}
+                or not isinstance(content, str)
+                or "data:image/" not in content
+            ):
                 continue
             if block.index is None:
                 raise ValueError(f"HTML image carrier requires index: page_idx={page.page_idx}, type={block.type}")

{docvortex-0.4.2 → docvortex-0.4.3}/src/docvortex/public_api.py

@@ -165,6 +165,7 @@ PUBLIC_API: dict[str, tuple[str, ...]] = {
         "attach_visual_block_images",
         "attach_visual_block_images_from_pdf",
     ),
+    "docvortex.export": ("materialize_middle", "validate_materialized_assets"),
     "docvortex.errors": (
         "DocumentError",
         "InvalidRequestError",

{docvortex-0.4.2 → docvortex-0.4.3}/src/docvortex/render/_internal/pdf/diagnostics.py

@@ -12,6 +12,7 @@ from ....result import Diagnostic
 
 
 _diagnostics: ContextVar[list[Diagnostic] | None] = ContextVar("pdf_diagnostics", default=None)
+_DEBUG_DIAGNOSTIC_CODES = frozenset({"pdf_title_layout_expanded", "pdf_layout_scaled"})
 
 
 @contextmanager
@@ -26,8 +27,9 @@ def collect_pdf_diagnostics() -> Iterator[list[Diagnostic]]:
 
 
 def report_pdf_diagnostic(code: str, message: str, page_index: int | None = None) -> None:
-    """将同一条定位信息写入日志与当前高层产物的诊断列表。"""
-    logger.warning("{}: {}", code, message)
+    """正常布局适配使用 DEBUG，其余使用 WARNING；结构化诊断保持完整。"""
+    level = "DEBUG" if code in _DEBUG_DIAGNOSTIC_CODES else "WARNING"
+    logger.log(level, "{}: {}", code, message)
     items = _diagnostics.get()
     if items is not None:
         diagnostic = Diagnostic(code, message, page_index)

{docvortex-0.4.2 → docvortex-0.4.3}/src/docvortex/version.py

@@ -1,3 +1,3 @@
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
 __all__ = ["__version__"]

{docvortex-0.4.2 → docvortex-0.4.3/src/docvortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.2
+Version: 0.4.3
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex
@@ -106,6 +106,8 @@ docvortex convert report.pdf --format markdown --output output/report.md
 
 Replace `report.pdf` with a local file in any supported input format.
 Use `--format` to choose the output; run `docvortex convert --help` for options.
+The root-level `--log-level` option controls loguru output and defaults to `info`.
+It must precede the command; `DOCVORTEX_LOG_LEVEL=warning` can also configure it.
 
 ### Python
 

{docvortex-0.4.2 → docvortex-0.4.3}/src/docvortex.egg-info/SOURCES.txt

@@ -422,6 +422,7 @@ src/docvortex/resources/html/docvortex.min.css
 tests/test_architecture.py
 tests/test_benchmark_entrypoint.py
 tests/test_brand_protocol.py
+tests/test_cli_logging.py
 tests/test_complete_pipeline.py
 tests/test_converter_lifecycle.py
 tests/test_document_envelope.py
@@ -438,6 +439,7 @@ tests/test_pdf_output_text.py
 tests/test_pdf_render_pool.py
 tests/test_pdf_source_row_merging.py
 tests/test_pdf_symbol_normalization.py
+tests/test_public_export_api.py
 tests/test_public_image_api.py
 tests/test_public_pipeline.py
 tests/test_refactor_raster.py
@@ -557,6 +559,7 @@ tests/unittest/test_office_parser_regressions.py
 tests/unittest/test_pdf_cjk_wrapping.py
 tests/unittest/test_pdf_classify.py
 tests/unittest/test_pdf_demo_links.py
+tests/unittest/test_pdf_diagnostic_levels.py
 tests/unittest/test_pdf_document.py
 tests/unittest/test_pdf_original_layout.py
 tests/unittest/test_pdf_pagination.py

docvortex-0.4.3/tests/test_cli_logging.py

@@ -0,0 +1,127 @@
+"""验证 CLI 全局 loguru 日志等级参数的解析与过滤行为。"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Iterator
+
+from click.testing import CliRunner
+from loguru import logger
+import pytest
+
+from docvortex import cli
+
+
+@pytest.fixture
+def isolated_logger() -> Iterator[None]:
+    """隔离 loguru 全局 sink，避免 CLI 日志测试影响其他用例。"""
+    logger.remove()
+    yield
+    logger.remove()
+    logger.add(sys.stderr)
+
+
+class _DummyPDFDocument:
+    """替身 PDF 文档，避免日志参数测试依赖真实 PDF 解析。"""
+
+    def __enter__(self) -> "_DummyPDFDocument":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> bool:
+        return False
+
+    def classify(self) -> str:
+        return "txt"
+
+
+def _invoke_classify(runner: CliRunner, source: Path, *arguments: str):
+    """调用 classify 子命令并返回执行结果，供日志参数断言复用。"""
+    return runner.invoke(cli.main, [*arguments, "classify", str(source)])
+
+
+def test_cli_log_level_defaults_to_info(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """未显式配置时，根命令默认传入 info 日志等级。"""
+    source = tmp_path / "source.pdf"
+    source.write_bytes(b"dummy")
+    levels = []
+    monkeypatch.setattr(cli, "_configure_log_level", levels.append)
+    monkeypatch.setattr("docvortex.document.pdf.PDFDocument", lambda _: _DummyPDFDocument())
+
+    result = _invoke_classify(CliRunner(), source)
+
+    assert result.exit_code == 0, result.output
+    assert levels == ["info"]
+
+
+def test_cli_log_level_accepts_root_option_and_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """根命令参数生效，且显式参数优先于环境变量。"""
+    source = tmp_path / "source.pdf"
+    source.write_bytes(b"dummy")
+    levels = []
+    monkeypatch.setattr(cli, "_configure_log_level", levels.append)
+    monkeypatch.setattr("docvortex.document.pdf.PDFDocument", lambda _: _DummyPDFDocument())
+    monkeypatch.setenv("DOCVORTEX_LOG_LEVEL", "warning")
+    runner = CliRunner()
+
+    environment_result = _invoke_classify(runner, source)
+    explicit_result = _invoke_classify(runner, source, "--log-level", "debug")
+
+    assert environment_result.exit_code == 0, environment_result.output
+    assert explicit_result.exit_code == 0, explicit_result.output
+    assert levels == ["warning", "debug"]
+
+
+def test_cli_rejects_invalid_log_level(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """非法日志等级在进入业务命令前被 Click 拒绝。"""
+    source = tmp_path / "source.pdf"
+    source.write_bytes(b"dummy")
+    levels = []
+    monkeypatch.setattr(cli, "_configure_log_level", levels.append)
+    monkeypatch.setenv("DOCVORTEX_LOG_LEVEL", "verbose")
+
+    result = _invoke_classify(CliRunner(), source)
+
+    assert result.exit_code != 0
+    assert "Invalid value" in result.output
+    assert levels == []
+
+
+@pytest.mark.parametrize(
+    ("level", "expected"),
+    [
+        ("info", ("debug hidden", False, "warning shown", True)),
+        ("debug", ("debug shown", True, "warning shown", True)),
+        ("error", ("warning hidden", False, "error shown", True)),
+    ],
+)
+def test_configure_log_level_filters_loguru_output(
+    isolated_logger, capsys: pytest.CaptureFixture[str], level: str, expected: tuple[str, bool, str, bool]
+) -> None:
+    """全局日志等级按 loguru 阈值过滤标准错误输出。"""
+    cli._configure_log_level(level)
+    logger.debug("debug hidden" if level == "info" else "debug shown")
+    logger.warning("warning hidden" if level == "error" else "warning shown")
+    logger.error("error shown")
+
+    stderr = capsys.readouterr().err
+    debug_message, debug_expected, warning_message, warning_expected = expected
+    assert (debug_message in stderr) is debug_expected
+    assert (warning_message in stderr) is warning_expected
+    assert "error shown" in stderr
+
+
+def test_importing_cli_preserves_host_loguru_sink() -> None:
+    """导入 CLI 模块不重建宿主应用已配置的 loguru sink。"""
+    messages: list[str] = []
+    handler_id = logger.add(messages.append, level="DEBUG", format="{message}")
+    try:
+        importlib.reload(cli)
+        logger.debug("host sink remains")
+    finally:
+        logger.remove(handler_id)
+
+    assert "host sink remains\n" in messages

docvortex-0.4.3/tests/test_public_export_api.py

@@ -0,0 +1,71 @@
+"""验证跨库素材导出接口的字节所有权及字面量边界。"""
+
+from __future__ import annotations
+
+import base64
+from typing import get_type_hints
+
+import pytest
+
+from docvortex.assets import AssetStore
+from docvortex.export import materialize_middle, validate_materialized_assets
+from docvortex.public_api import PUBLIC_API
+from docvortex.schema import MiddleJson
+
+
+def test_public_export_preserves_payloads_geometry_and_code() -> None:
+    """直接图与表内图外置后字节不变，代码中的同名字面量不被当作素材。"""
+    image = b"\xff\xd8\xffexample\xff\xd9"
+    uri = "data:image/jpeg;base64," + base64.b64encode(image).decode()
+    markup = f'<img src="{uri}" width="10">'
+    middle = MiddleJson.from_dict(
+        {
+            "schema": "docvortex.middle",
+            "schema_version": "2.0",
+            "is_full_document": False,
+            "metadata": {"file_suffix": "pdf", "producer": {"name": "test", "version": "1"}},
+            "extensions": {
+                "docvortex_layout": {
+                    "version": 1,
+                    "pages": [{"page_idx": 4, "width_pt": 400, "height_pt": 600, "image_rotations": {"2": 270}}],
+                }
+            },
+            "pages": [
+                {
+                    "page_idx": 4,
+                    "blocks": [
+                        {
+                            "type": "table",
+                            "index": 2,
+                            "bbox": [0.1, 0.1, 0.4, 0.5],
+                            "content": [{"type": "table_body", "index": 2, "content": markup, "image_base64": uri}],
+                        },
+                        {
+                            "type": "code",
+                            "sub_type": "code",
+                            "guess_lang": "html",
+                            "index": 3,
+                            "bbox": [0.1, 0.6, 0.9, 0.8],
+                            "content": [{"type": "code_body", "index": 3, "content": markup}],
+                        },
+                    ],
+                }
+            ],
+        }
+    )
+    before = middle.to_json()
+    exported, assets = materialize_middle(middle)
+    validate_materialized_assets(exported, assets)
+    assert set(assets) == {"images/page_4_table_body_2.jpg", "images/page_4_table_body_2_1.jpg"}
+    assert all(payload == image for payload in assets.values())
+    assert exported.extensions == middle.extensions
+    assert exported.pages[0].blocks[1].content[0].content == markup
+    assert middle.to_json() == before
+    repeated, copied_assets = materialize_middle(exported, assets)
+    assert repeated == exported and dict(copied_assets) == dict(assets)
+    assert copied_assets is not assets
+    with pytest.raises(ValueError, match="Missing materialized asset"):
+        validate_materialized_assets(exported, AssetStore())
+    assert set(PUBLIC_API["docvortex.export"]) == {"materialize_middle", "validate_materialized_assets"}
+    assert get_type_hints(materialize_middle)["return"] == tuple[MiddleJson, AssetStore]
+    assert get_type_hints(validate_materialized_assets)["return"] is type(None)

docvortex-0.4.3/tests/unittest/test_pdf_diagnostic_levels.py

@@ -0,0 +1,39 @@
+"""验证 PDF 日志分级不改变结构化诊断及其去重行为。"""
+
+from __future__ import annotations
+
+import pytest
+from loguru import logger
+
+from docvortex.render._internal.pdf.diagnostics import collect_pdf_diagnostics, report_pdf_diagnostic
+from docvortex.result import Diagnostic
+
+
+@pytest.mark.parametrize(
+    "code,level",
+    [
+        ("pdf_title_layout_expanded", "DEBUG"),
+        ("pdf_layout_scaled", "DEBUG"),
+        ("pdf_layout_small_text", "WARNING"),
+        ("pdf_title_geometry_conflict", "WARNING"),
+        ("pdf_image_unavailable", "WARNING"),
+        ("pdf_formula_fallback", "WARNING"),
+        ("unknown_diagnostic", "WARNING"),
+    ],
+)
+def test_log_level_preserves_structured_diagnostics(code: str, level: str) -> None:
+    """按真实日志级别捕获输出，重复诊断仍只在结构化列表保存一次。"""
+    records: list[str] = []
+    warnings: list[str] = []
+    debug_sink = logger.add(records.append, level="DEBUG", format="{level.name}|{message}")
+    warning_sink = logger.add(warnings.append, level="WARNING", format="{level.name}|{message}")
+    try:
+        with collect_pdf_diagnostics() as items:
+            report_pdf_diagnostic(code, "example", 4)
+            report_pdf_diagnostic(code, "example", 4)
+        assert items == [Diagnostic(code, "example", 4)]
+        assert [str(message).strip() for message in records] == [f"{level}|{code}: example"] * 2
+        assert len(warnings) == (2 if level == "WARNING" else 0)
+    finally:
+        logger.remove(debug_sink)
+        logger.remove(warning_sink)

docvortex-0.4.2/src/docvortex/foundation/__init__.py

@@ -1,3 +0,0 @@
-"""DocVortex 模块边界。"""
-
-__all__ = []