zenfmt 0.1.0__tar.gz

zenfmt-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+.zig-cache/
+zig-out/
+docs/build/
+benchmarks/corpus/
+benchmarks/.anydoc/
+benchmarks/.venv-wheel/
+.venv/
+dist/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+python/src/zenfmt/_native/*.so
+python/src/zenfmt/_native/*.dylib
+python/src/zenfmt/_native/*.dll

zenfmt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vikrant Rathore and Ronak Rathore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zenfmt-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: zenfmt
+Version: 0.1.0
+Summary: Universal document conversion: typed Python API over the zenfmt native engine
+Project-URL: Homepage, https://github.com/insanai/zenfmt
+Project-URL: Documentation, https://insanai.github.io/zenfmt/
+Project-URL: Repository, https://github.com/insanai/zenfmt
+Project-URL: Issues, https://github.com/insanai/zenfmt/issues
+Author: Vikrant Rathore
+License-Expression: MIT
+License-File: LICENSE
+Keywords: conversion,document,docx,epub,markdown,office,pdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Zig
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# zenfmt
+
+Universal document conversion as a typed, dependency-free Python library.
+zenfmt reads 19 formats—DOCX, DOC, ODT, RTF, XLSX, XLS, XLSB, ODS, CSV, PPTX,
+PPT, ODP, EPUB, PDF, HTML, Markdown, AsciiDoc, reStructuredText, and plain
+text—and writes clean Markdown through a native engine written in Zig. The
+wheel bundles the engine: no runtime dependencies, subprocesses, or network
+downloads are required, and the GIL is released during conversion.
+
+```sh
+pip install zenfmt
+```
+
+```python
+import zenfmt
+
+# A str is always a path; the result is the whole in-memory ensemble:
+# artifact bytes, embedded resources, the canonical manifest, and reports.
+conversion = zenfmt.convert("report.docx")
+print(conversion.text)
+for report in conversion.reports:
+    print(report.code, report.problem)
+
+# Bytes are explicit; the source format is named or sniffed.
+conversion = zenfmt.convert(uploaded_bytes, name="upload.docx", to="markdown")
+
+# An output path selects transactional publication: the artifact, its media,
+# and a manifest land together or not at all. Graded strictness refuses
+# priced fidelity loss before anything is written.
+conversion = zenfmt.convert(
+    "report.docx", output="build/report.md", strict="structure"
+)
+```
+
+Failures raise a compact exception tree (`ConversionError`,
+`LimitExceededError`, `UnknownFormatError`, …) whose messages answer the same
+four questions as the engine's CLI diagnostics — what happened, where, what it
+costs, and what you can do. Reusable policy lives in immutable
+`zenfmt.Converter` values; there is no global configuration or environment
+lookup. `zenfmt.formats()` enumerates the compiled-in format capabilities.
+
+Every library error includes structured facts and an actionable hint. Handle
+stable codes in application logic and render the message for people:
+
+```python
+try:
+    zenfmt.convert(uploaded_bytes, name="upload.docx")
+except zenfmt.ConversionError as error:
+    log.info("conversion failed", extra={"code": error.code})
+    print(error.hint)
+```
+
+## Security and authority
+
+A string is always a path. Passing a path explicitly authorizes zenfmt to read
+that file and, when present, its adjacent digest-bound `.zenfmt.json` manifest.
+Passing bytes or a binary reader grants no filesystem authority: `name` is
+display-only, is never opened, and no adjacent file is inspected. External
+resource references are reported in `conversion.resources` but are never
+fetched. The runtime does not read configuration from the environment, follow
+includes, resolve external entities, discover plugins, or use the network.
+
+Conversion is bounded by `zenfmt.Limits`; the defaults cap input, decoded
+text, archive expansion, document structure, reports, embedded resources, and
+artifact output. Services handling large or untrusted documents should lower
+those limits and publish path output inside a per-job directory with suitable
+permissions and quotas. Path publication is transactional and refuses to
+replace an existing artifact ensemble unless `overwrite=True`.
+
+The native engine runs inside the Python process with that process's
+authority. A wheel is not a sandbox. Workloads that need a stronger isolation
+boundary should perform conversion in a restricted worker process or
+container. Independent calls are thread-safe; create worker processes before
+starting conversion threads, or use the multiprocessing `spawn` start method.
+
+Wheels are published for Linux (manylinux and musl, x86_64 and aarch64),
+macOS 12+ (x86_64 and arm64), and Windows x86_64, for CPython 3.10–3.14.
+Building from the source distribution requires only a
+[Zig](https://ziglang.org/) toolchain — the sdist carries the complete engine
+source under `engine/`.
+
+CLI archives and Python wheels are attached to each
+[GitHub release](https://github.com/insanai/zenfmt/releases). This package is
+the Python surface of the [zenfmt monorepo](https://github.com/insanai/zenfmt);
+the engine, design records (ZDS 0014 covers this library), and development
+workflow live there.
+
+zenfmt is authored by Vikrant Rathore with assistance from Ronak Rathore.

zenfmt-0.1.0/README.md

@@ -0,0 +1,88 @@
+# zenfmt
+
+Universal document conversion as a typed, dependency-free Python library.
+zenfmt reads 19 formats—DOCX, DOC, ODT, RTF, XLSX, XLS, XLSB, ODS, CSV, PPTX,
+PPT, ODP, EPUB, PDF, HTML, Markdown, AsciiDoc, reStructuredText, and plain
+text—and writes clean Markdown through a native engine written in Zig. The
+wheel bundles the engine: no runtime dependencies, subprocesses, or network
+downloads are required, and the GIL is released during conversion.
+
+```sh
+pip install zenfmt
+```
+
+```python
+import zenfmt
+
+# A str is always a path; the result is the whole in-memory ensemble:
+# artifact bytes, embedded resources, the canonical manifest, and reports.
+conversion = zenfmt.convert("report.docx")
+print(conversion.text)
+for report in conversion.reports:
+    print(report.code, report.problem)
+
+# Bytes are explicit; the source format is named or sniffed.
+conversion = zenfmt.convert(uploaded_bytes, name="upload.docx", to="markdown")
+
+# An output path selects transactional publication: the artifact, its media,
+# and a manifest land together or not at all. Graded strictness refuses
+# priced fidelity loss before anything is written.
+conversion = zenfmt.convert(
+    "report.docx", output="build/report.md", strict="structure"
+)
+```
+
+Failures raise a compact exception tree (`ConversionError`,
+`LimitExceededError`, `UnknownFormatError`, …) whose messages answer the same
+four questions as the engine's CLI diagnostics — what happened, where, what it
+costs, and what you can do. Reusable policy lives in immutable
+`zenfmt.Converter` values; there is no global configuration or environment
+lookup. `zenfmt.formats()` enumerates the compiled-in format capabilities.
+
+Every library error includes structured facts and an actionable hint. Handle
+stable codes in application logic and render the message for people:
+
+```python
+try:
+    zenfmt.convert(uploaded_bytes, name="upload.docx")
+except zenfmt.ConversionError as error:
+    log.info("conversion failed", extra={"code": error.code})
+    print(error.hint)
+```
+
+## Security and authority
+
+A string is always a path. Passing a path explicitly authorizes zenfmt to read
+that file and, when present, its adjacent digest-bound `.zenfmt.json` manifest.
+Passing bytes or a binary reader grants no filesystem authority: `name` is
+display-only, is never opened, and no adjacent file is inspected. External
+resource references are reported in `conversion.resources` but are never
+fetched. The runtime does not read configuration from the environment, follow
+includes, resolve external entities, discover plugins, or use the network.
+
+Conversion is bounded by `zenfmt.Limits`; the defaults cap input, decoded
+text, archive expansion, document structure, reports, embedded resources, and
+artifact output. Services handling large or untrusted documents should lower
+those limits and publish path output inside a per-job directory with suitable
+permissions and quotas. Path publication is transactional and refuses to
+replace an existing artifact ensemble unless `overwrite=True`.
+
+The native engine runs inside the Python process with that process's
+authority. A wheel is not a sandbox. Workloads that need a stronger isolation
+boundary should perform conversion in a restricted worker process or
+container. Independent calls are thread-safe; create worker processes before
+starting conversion threads, or use the multiprocessing `spawn` start method.
+
+Wheels are published for Linux (manylinux and musl, x86_64 and aarch64),
+macOS 12+ (x86_64 and arm64), and Windows x86_64, for CPython 3.10–3.14.
+Building from the source distribution requires only a
+[Zig](https://ziglang.org/) toolchain — the sdist carries the complete engine
+source under `engine/`.
+
+CLI archives and Python wheels are attached to each
+[GitHub release](https://github.com/insanai/zenfmt/releases). This package is
+the Python surface of the [zenfmt monorepo](https://github.com/insanai/zenfmt);
+the engine, design records (ZDS 0014 covers this library), and development
+workflow live there.
+
+zenfmt is authored by Vikrant Rathore with assistance from Ronak Rathore.

zenfmt-0.1.0/engine/bindings/python/abi.zig

@@ -0,0 +1,217 @@
+//! The zenfmt Python bridge: a private, versioned C ABI over the default
+//! bundle (ZDS 0014).
+//!
+//! The installed `zenfmt` Python package is the only supported consumer.
+//! Symbols use the `zenfmt_py_` prefix, fixed-width integers, and
+//! pointer-length slices; options cross as one versioned JSON object; the
+//! result is an opaque handle whose accessor slices stay valid until the
+//! single `zenfmt_py_result_free`. No callback ever enters the embedding
+//! language, and no pointer into caller memory survives a call.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const build_info = @import("zenfmt_build");
+const capabilities = @import("capabilities.zig");
+const result_mod = @import("result.zig");
+
+pub const abi_major: u32 = 1;
+pub const abi_minor: u32 = 0;
+
+/// `path_encoding` values in `RuntimeInfo`.
+pub const path_encoding_posix_bytes: u32 = 1;
+pub const path_encoding_utf16le: u32 = 2;
+
+pub const Slice = extern struct {
+    ptr: ?[*]const u8,
+    len: u64,
+};
+
+/// A native path: raw bytes on POSIX, UTF-16LE code units on Windows.
+/// `len` counts code units, not bytes.
+pub const PathSlice = extern struct {
+    ptr: ?*const anyopaque,
+    len: u64,
+};
+
+pub const RuntimeInfo = extern struct {
+    abi_major: u32,
+    abi_minor: u32,
+    pointer_bits: u32,
+    path_encoding: u32,
+};
+
+pub const Request = extern struct {
+    options_json: Slice,
+    input_bytes: Slice,
+    input_path: PathSlice,
+    output_path: PathSlice,
+};
+
+pub const ResourceView = extern struct {
+    rel_path: Slice,
+    bytes: Slice,
+    digest_hex: Slice,
+};
+
+pub const Result = result_mod.Result;
+
+fn slice(bytes: []const u8) Slice {
+    return .{ .ptr = bytes.ptr, .len = bytes.len };
+}
+
+export fn zenfmt_py_abi_version() u32 {
+    return (abi_major << 16) | abi_minor;
+}
+
+export fn zenfmt_py_runtime_info(out: ?*RuntimeInfo) void {
+    const info = out orelse return;
+    info.* = .{
+        .abi_major = abi_major,
+        .abi_minor = abi_minor,
+        .pointer_bits = @bitSizeOf(usize),
+        .path_encoding = if (builtin.os.tag == .windows)
+            path_encoding_utf16le
+        else
+            path_encoding_posix_bytes,
+    };
+}
+
+export fn zenfmt_py_zenfmt_version(out_len: ?*u64) ?[*]const u8 {
+    const len = out_len orelse return null;
+    len.* = build_info.version.len;
+    return build_info.version.ptr;
+}
+
+export fn zenfmt_py_capabilities(out_len: ?*u64) ?[*]const u8 {
+    const len = out_len orelse return null;
+    len.* = capabilities.json.len;
+    return capabilities.json.ptr;
+}
+
+export fn zenfmt_py_convert(request: ?*const Request) ?*Result {
+    const value = request orelse return null;
+    return result_mod.convertThreaded(std.heap.smp_allocator, value);
+}
+
+export fn zenfmt_py_result_status(result: ?*const Result) u32 {
+    const value = result orelse return result_mod.status_invalid_request;
+    return value.status;
+}
+
+export fn zenfmt_py_result_exit_class(result: ?*const Result) u32 {
+    const value = result orelse return 0;
+    return value.exit_class;
+}
+
+export fn zenfmt_py_result_reports_json(
+    result: ?*const Result,
+    out_len: ?*u64,
+) ?[*]const u8 {
+    const value = result orelse return null;
+    const len = out_len orelse return null;
+    len.* = value.reports_json.len;
+    return value.reports_json.ptr;
+}
+
+export fn zenfmt_py_result_manifest_json(
+    result: ?*const Result,
+    out_len: ?*u64,
+) ?[*]const u8 {
+    const value = result orelse return null;
+    const len = out_len orelse return null;
+    if (value.conversion) |*conversion| {
+        const manifest_json = conversion.manifest_json orelse return null;
+        len.* = manifest_json.len;
+        return manifest_json.ptr;
+    }
+    return null;
+}
+
+export fn zenfmt_py_result_source_format(
+    result: ?*const Result,
+    out_len: ?*u64,
+) ?[*]const u8 {
+    const value = result orelse return null;
+    const len = out_len orelse return null;
+    if (value.conversion) |*conversion| {
+        const format = conversion.source_format orelse return null;
+        len.* = format.len;
+        return format.ptr;
+    }
+    return null;
+}
+
+export fn zenfmt_py_result_output_format(
+    result: ?*const Result,
+    out_len: ?*u64,
+) ?[*]const u8 {
+    const value = result orelse return null;
+    const len = out_len orelse return null;
+    if (value.conversion) |*conversion| {
+        const format = conversion.output_format orelse return null;
+        len.* = format.len;
+        return format.ptr;
+    }
+    return null;
+}
+
+export fn zenfmt_py_result_artifact(
+    result: ?*const Result,
+    out_len: ?*u64,
+) ?[*]const u8 {
+    const value = result orelse return null;
+    const len = out_len orelse return null;
+    const ensemble = value.ensemble() orelse return null;
+    len.* = ensemble.artifact.len;
+    return ensemble.artifact.ptr;
+}
+
+export fn zenfmt_py_result_artifact_name(
+    result: ?*const Result,
+    out_len: ?*u64,
+) ?[*]const u8 {
+    const value = result orelse return null;
+    const len = out_len orelse return null;
+    const ensemble = value.ensemble() orelse return null;
+    len.* = ensemble.artifact_name.len;
+    return ensemble.artifact_name.ptr;
+}
+
+export fn zenfmt_py_result_resource_count(result: ?*const Result) u64 {
+    const value = result orelse return 0;
+    const ensemble = value.ensemble() orelse return 0;
+    return ensemble.resources.len;
+}
+
+export fn zenfmt_py_result_resource(
+    result: ?*const Result,
+    index: u64,
+    out: ?*ResourceView,
+) u32 {
+    const value = result orelse return 1;
+    const view = out orelse return 1;
+    const ensemble = value.ensemble() orelse return 1;
+    const i = std.math.cast(usize, index) orelse return 1;
+    if (i >= ensemble.resources.len) return 1;
+    const resource = &ensemble.resources[i];
+    view.* = .{
+        .rel_path = slice(resource.rel_path),
+        .bytes = slice(resource.bytes),
+        .digest_hex = slice(&resource.digest_hex),
+    };
+    return 0;
+}
+
+export fn zenfmt_py_result_free(result: ?*Result) void {
+    const value = result orelse return;
+    value.destroy();
+}
+
+test {
+    _ = @import("capabilities.zig");
+    _ = @import("request.zig");
+    _ = @import("result.zig");
+    _ = @import("abi_test.zig");
+    _ = @import("fuzz_test.zig");
+    _ = @import("oom_test.zig");
+}