zenfmt 0.1.0__py3-none-win_amd64.whl

zenfmt/__init__.py

@@ -0,0 +1,72 @@
+"""zenfmt: universal document conversion for Python (ZDS 0014).
+
+The common operation is one call::
+
+    import zenfmt
+
+    conversion = zenfmt.convert("report.docx")
+    print(conversion.text)
+    for report in conversion.reports:
+        print(report.code, report.problem)
+
+Importing this package defines Python objects only; the bundled native
+engine loads and verifies itself on the first capability query or
+conversion. There is no global configuration, no environment lookup, and
+no network access.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata as _metadata
+
+from ._convert import Converter, convert, formats
+from ._errors import (
+    ConversionError,
+    DestinationExistsError,
+    Direction,
+    InputReadError,
+    LimitExceededError,
+    NativeLibraryError,
+    UnknownFormatError,
+    UnsupportedPlatformError,
+    ZenfmtError,
+)
+from ._limits import Limits
+from ._models import (
+    Context,
+    Conversion,
+    Format,
+    Manifest,
+    Report,
+    Resource,
+    Strictness,
+)
+
+try:
+    __version__ = _metadata.version("zenfmt")
+except _metadata.PackageNotFoundError:  # not installed; source tree use
+    __version__ = "0.0.0"
+
+__all__ = (
+    "Context",
+    "Conversion",
+    "ConversionError",
+    "Converter",
+    "DestinationExistsError",
+    "Direction",
+    "Format",
+    "InputReadError",
+    "LimitExceededError",
+    "Limits",
+    "Manifest",
+    "NativeLibraryError",
+    "Report",
+    "Resource",
+    "Strictness",
+    "UnknownFormatError",
+    "UnsupportedPlatformError",
+    "ZenfmtError",
+    "__version__",
+    "convert",
+    "formats",
+)

zenfmt/_capabilities.py

@@ -0,0 +1,102 @@
+"""Capability discovery from native metadata (ZDS 0014).
+
+The bridge's compile-time capability JSON is the only format table: it
+drives :func:`zenfmt.formats`, alias resolution, artifact naming, and the
+``Conversion.text`` decision. No hard-coded Python format list exists
+anywhere in this package.
+"""
+
+from __future__ import annotations
+
+import json
+
+from . import _diagnostics
+from ._loader import Bridge
+from ._models import Format
+
+_cache: dict[bytes, Capabilities] = {}
+
+
+class Capabilities:
+    __slots__ = ("_aliases", "default_output_format", "formats", "limits")
+
+    def __init__(
+        self,
+        formats: tuple[Format, ...],
+        default_output_format: str,
+        limits: dict[str, int],
+    ) -> None:
+        self.formats = formats
+        self.default_output_format = default_output_format
+        self.limits = limits
+        aliases: dict[str, str] = {}
+        for entry in formats:
+            aliases[entry.name] = entry.name
+            for extension in entry.extensions:
+                aliases.setdefault(extension, entry.name)
+        self._aliases = aliases
+
+    def resolve(self, alias: str) -> str:
+        """Canonical format id for a name or extension-like alias.
+
+        ASCII case-insensitive; one leading dot is ignored. Unknown
+        aliases pass through unchanged so the engine produces the
+        canonical unknown-format failure with its suggestions — the
+        wrapper never maintains a second table of judgments.
+        """
+        normalized = alias.strip().lower().removeprefix(".")
+        return self._aliases.get(normalized, normalized)
+
+    def by_name(self, name: str) -> Format | None:
+        for entry in self.formats:
+            if entry.name == name:
+                return entry
+        return None
+
+    def writer_emits_text(self, name: str) -> bool:
+        entry = self.by_name(name)
+        return bool(entry and entry.text_writer)
+
+    def primary_extension(self, name: str) -> str | None:
+        entry = self.by_name(name)
+        return entry.primary_extension if entry else None
+
+
+def capabilities(bridge: Bridge) -> Capabilities:
+    """The parsed capability view for a verified bridge, cached by the
+    exact capability bytes (identical metadata parses identically)."""
+    key = bridge.capability_json
+    cached = _cache.get(key)
+    if cached is not None:
+        return cached
+    parsed = _parse(key)
+    _cache.clear()
+    _cache[key] = parsed
+    return parsed
+
+
+def _parse(raw: bytes) -> Capabilities:
+    try:
+        document = json.loads(raw)
+        formats = tuple(
+            Format(
+                name=str(entry["format"]),
+                plugin_id=str(entry["plugin_id"]),
+                extensions=tuple(str(e) for e in entry["extensions"]),
+                can_read=bool(entry["read"]),
+                can_write=bool(entry["write"]),
+                primary_extension=entry["primary_extension"],
+                seekable_input=bool(entry["seekable_input"]),
+                text_writer=entry["text_writer"],
+            )
+            for entry in document["formats"]
+        )
+        default_output = str(document["default_output_format"])
+        limits = {str(name): int(value) for name, value in document["limits"].items()}
+    except (KeyError, TypeError, ValueError) as error:
+        raise _diagnostics.capabilities_invalid(
+            f"{type(error).__name__}: {error}"
+        ) from error
+    if not formats:
+        raise _diagnostics.capabilities_invalid("no formats are declared")
+    return Capabilities(formats, default_output, limits)

zenfmt/_convert.py

@@ -0,0 +1,374 @@
+"""Argument validation, reusable policy, and the public conversion call
+(ZDS 0014). Contains no document-format logic: format identity comes from
+native capability metadata only."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path, PurePath
+from typing import Any
+
+from . import _capabilities, _diagnostics, _ffi, _loader, _marshal
+from ._limits import LIMIT_TABLE, Limits
+from ._models import Conversion, Format, Strictness
+
+_UNSET: Any = object()
+
+
+def _normalize_strict(value: Any) -> Strictness:
+    if value is False or value is None:
+        return Strictness.OFF
+    if value is True:
+        # Bare `--strict` means content, and so does `strict=True`.
+        return Strictness.CONTENT
+    if isinstance(value, Strictness):
+        return value
+    if isinstance(value, str):
+        try:
+            return Strictness(value.lower())
+        except ValueError:
+            raise _diagnostics.invalid_strict(value) from None
+    raise _diagnostics.invalid_strict(value)
+
+
+def _normalize_limits(value: Any) -> Limits | None:
+    if value is None:
+        return None
+    if isinstance(value, Limits):
+        return value
+    raise _diagnostics.invalid_limits_argument(value)
+
+
+def _normalize_bool(argument: str, value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    raise _diagnostics.invalid_bool_argument(argument, value)
+
+
+def _normalize_format(argument: str, value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, Format):
+        return value.name
+    if isinstance(value, str):
+        return value
+    raise _diagnostics.invalid_format_argument(argument, value)
+
+
+def _validate_name(name: str) -> str:
+    if not isinstance(name, str):
+        raise _diagnostics.invalid_name(repr(name), "must be a str display basename")
+    if not name:
+        raise _diagnostics.invalid_name(name, "must not be empty")
+    if any(ch in name for ch in ("/", "\\")):
+        raise _diagnostics.invalid_name(name, "must not contain a directory separator")
+    if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in name):
+        raise _diagnostics.invalid_name(name, "must not contain control characters")
+    return name
+
+
+def _sanitize_stream_name(value: Any) -> str | None:
+    """The optional display-only ``.name`` attribute of a reader: used
+    only when it is already a str, reduced to a basename, never opened."""
+    if not isinstance(value, str) or not value:
+        return None
+    base = PurePath(value).name
+    if not base:
+        return None
+    try:
+        return _validate_name(base)
+    except ValueError:
+        return None
+
+
+class _Source:
+    """One classified conversion source."""
+
+    __slots__ = ("data", "display_name", "kind", "path")
+
+    def __init__(
+        self,
+        kind: str,
+        *,
+        path: str | bytes | None = None,
+        data: bytes | None = None,
+        display_name: str | None = None,
+    ) -> None:
+        self.kind = kind
+        self.path = path
+        self.data = data
+        self.display_name = display_name
+
+
+def _classify_source(source: Any, name: str | None, max_input_bytes: int) -> _Source:
+    if isinstance(source, (str, PurePath, os.PathLike)):
+        # A Python str is always a filesystem path, never inline text.
+        if name is not None:
+            raise _diagnostics.name_with_path_source()
+        try:
+            path = os.fspath(source)
+        except (KeyboardInterrupt, SystemExit, GeneratorExit):
+            raise
+        except BaseException as error:
+            raise _diagnostics.path_protocol_failed("source", error) from error
+        display = os.path.basename(path) if isinstance(path, str) else None
+        if display is None:
+            display = os.path.basename(os.fsdecode(path))
+        return _Source("path", path=path, display_name=display)
+
+    display = _validate_name(name) if name is not None else None
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        # Mutable or non-contiguous buffers are copied before the GIL is
+        # released; immutable bytes pass through.
+        data = source if isinstance(source, bytes) else bytes(source)
+        return _Source("bytes", data=data, display_name=display or "<memory>")
+
+    try:
+        read = getattr(source, "read", None)
+    except (KeyboardInterrupt, SystemExit, GeneratorExit):
+        raise
+    except BaseException as error:
+        raise _diagnostics.reader_failed(error) from error
+    if callable(read):
+        data = _marshal.read_bounded(source, max_input_bytes)
+        try:
+            stream_name = getattr(source, "name", None)
+        except (KeyboardInterrupt, SystemExit, GeneratorExit):
+            raise
+        except BaseException:
+            stream_name = None
+        fallback = _sanitize_stream_name(stream_name)
+        return _Source(
+            "bytes",
+            data=data,
+            display_name=display or fallback or "<stream>",
+        )
+
+    raise _diagnostics.invalid_source_type(source)
+
+
+def _artifact_name(display_name: str, extension: str) -> str:
+    """The memory-mode artifact basename: source stem plus the writer's
+    primary extension, or ``artifact.<extension>`` when no usable stem
+    exists."""
+    stem = display_name
+    dot = stem.rfind(".")
+    if dot > 0:
+        stem = stem[:dot]
+    if not stem or stem.startswith("<"):
+        stem = "artifact"
+    return f"{stem}.{extension}"
+
+
+class Converter:
+    """Immutable, reusable conversion policy over the shared native
+    bridge. Thread-safe: independent calls may run concurrently on one
+    instance, and the GIL is released while native conversion runs."""
+
+    __slots__ = ("_limits", "_preserve_facets", "_strict")
+
+    def __init__(
+        self,
+        *,
+        strict: Any = False,
+        limits: Limits | None = None,
+        preserve_facets: bool = False,
+    ) -> None:
+        object.__setattr__(self, "_strict", _normalize_strict(strict))
+        object.__setattr__(self, "_limits", _normalize_limits(limits))
+        object.__setattr__(
+            self,
+            "_preserve_facets",
+            _normalize_bool("preserve_facets", preserve_facets),
+        )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError("Converter is immutable")
+
+    @property
+    def strict(self) -> Strictness:
+        return self._strict
+
+    @property
+    def limits(self) -> Limits | None:
+        return self._limits
+
+    @property
+    def preserve_facets(self) -> bool:
+        return self._preserve_facets
+
+    @property
+    def formats(self) -> tuple[Format, ...]:
+        """The native reader and writer capabilities of this release."""
+        return _capabilities.capabilities(_loader.bridge()).formats
+
+    def convert(
+        self,
+        source: Any,
+        *,
+        to: Any = None,
+        from_: Any = None,
+        output: Any = None,
+        name: str | None = None,
+        strict: Any = _UNSET,
+        limits: Any = _UNSET,
+        overwrite: bool = False,
+        preserve_facets: Any = _UNSET,
+    ) -> Conversion:
+        """One conversion using this converter's policy; each keyword
+        explicitly supplied here overrides the stored policy for this
+        call only."""
+        effective_strict = (
+            self._strict if strict is _UNSET else _normalize_strict(strict)
+        )
+        effective_limits = (
+            self._limits if limits is _UNSET else _normalize_limits(limits)
+        )
+        effective_facets = (
+            self._preserve_facets
+            if preserve_facets is _UNSET
+            else _normalize_bool("preserve_facets", preserve_facets)
+        )
+        effective_overwrite = _normalize_bool("overwrite", overwrite)
+        to_value = _normalize_format("to", to)
+        from_value = _normalize_format("from_", from_)
+        output_path = _normalize_output(output)
+
+        bridge = _loader.bridge()
+        caps = _capabilities.capabilities(bridge)
+
+        resolved_from = caps.resolve(from_value) if from_value is not None else None
+        resolved_to = caps.resolve(to_value) if to_value is not None else None
+        if resolved_to is None and output_path is not None:
+            # An output suffix may select the writer when `to` is absent.
+            suffix = output_path.suffix.removeprefix(".")
+            if suffix:
+                candidate = caps.resolve(suffix)
+                entry = caps.by_name(candidate)
+                if entry is not None and entry.can_write:
+                    resolved_to = candidate
+
+        max_input = (
+            effective_limits.max_input_bytes
+            if effective_limits is not None
+            else caps.limits.get("max_input_bytes", 512 * 1024 * 1024)
+        )
+        classified = _classify_source(source, name, max_input)
+
+        artifact_name = None
+        if output_path is None:
+            writer = resolved_to or caps.default_output_format
+            extension = caps.primary_extension(writer) or "out"
+            artifact_name = _artifact_name(
+                classified.display_name or "<memory>", extension
+            )
+
+        options = _marshal.options_json(
+            input_kind=classified.kind,
+            input_name=(
+                classified.display_name if classified.kind == "bytes" else None
+            ),
+            output_kind="path" if output_path is not None else "memory",
+            artifact_name=artifact_name,
+            from_=resolved_from,
+            to=resolved_to,
+            strict=effective_strict.value,
+            overwrite=effective_overwrite,
+            preserve_facets=effective_facets,
+            limits=(
+                effective_limits.to_dict() if effective_limits is not None else None
+            ),
+        )
+        raw = _marshal.perform(
+            bridge,
+            options=options,
+            input_bytes=classified.data,
+            input_path=(
+                _marshal.encode_native_path(classified.path)
+                if classified.kind == "path"
+                else None
+            ),
+            output_path=(
+                _marshal.encode_native_path(os.fspath(output_path))
+                if output_path is not None
+                else None
+            ),
+            copy_limits=(
+                effective_limits.to_dict()
+                if effective_limits is not None
+                else {
+                    name: caps.limits.get(name, default)
+                    for name, (default, _) in LIMIT_TABLE.items()
+                }
+            ),
+        )
+        if raw.status == _ffi.STATUS_INVALID_REQUEST:
+            raise _diagnostics.invalid_request()
+        if raw.status == _ffi.STATUS_FAILED:
+            raise _diagnostics.conversion_error(raw.reports)
+        return _marshal.build_conversion(raw, caps, output_path=output_path)
+
+
+def _normalize_output(output: Any) -> Path | None:
+    if output is None:
+        return None
+    if isinstance(output, (str, PurePath, os.PathLike)):
+        # The caller's spelling is preserved rather than silently
+        # resolved.
+        try:
+            return Path(os.fsdecode(os.fspath(output)))
+        except (KeyboardInterrupt, SystemExit, GeneratorExit):
+            raise
+        except BaseException as error:
+            raise _diagnostics.path_protocol_failed("output", error) from error
+    raise _diagnostics.invalid_output_argument(output)
+
+
+_default_converter: Converter | None = None
+
+
+def _default() -> Converter:
+    global _default_converter
+    if _default_converter is None:
+        _default_converter = Converter()
+    return _default_converter
+
+
+def convert(
+    source: Any,
+    *,
+    to: Any = None,
+    from_: Any = None,
+    output: Any = None,
+    name: str | None = None,
+    strict: Any = False,
+    limits: Limits | None = None,
+    overwrite: bool = False,
+    preserve_facets: bool = False,
+) -> Conversion:
+    """Converts one document with safe defaults (ZDS 0014).
+
+    ``source`` is a path, bytes-like object, or binary reader; a Python
+    str is always a filesystem path, never inline text. With no
+    ``output`` the complete artifact ensemble is returned in memory;
+    an ``output`` path selects transactional publication. Failures raise
+    :class:`zenfmt.ConversionError` (or a subclass) carrying every native
+    report.
+    """
+    return _default().convert(
+        source,
+        to=to,
+        from_=from_,
+        output=output,
+        name=name,
+        strict=strict,
+        limits=limits,
+        overwrite=overwrite,
+        preserve_facets=preserve_facets,
+    )
+
+
+def formats() -> tuple[Format, ...]:
+    """Every reader and writer compiled into this release, in native
+    registry order, from capability metadata only."""
+    return _capabilities.capabilities(_loader.bridge()).formats