undoc 0.9.0__tar.gz

undoc-0.9.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: undoc
+Version: 0.9.0
+Summary: High-performance Microsoft Office document extraction to Markdown
+Author-email: iyulab <tech@iyulab.com>
+License: MIT
+Project-URL: Homepage, https://github.com/iyulab/undoc
+Project-URL: Documentation, https://github.com/iyulab/undoc#readme
+Project-URL: Repository, https://github.com/iyulab/undoc
+Project-URL: Issues, https://github.com/iyulab/undoc/issues
+Keywords: office,docx,xlsx,pptx,markdown,extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+
+# undoc
+
+High-performance Microsoft Office document extraction to Markdown.
+
+## Installation
+
+```bash
+pip install undoc
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from undoc import parse_file
+
+# Parse a document
+doc = parse_file("document.docx")
+
+# Convert to Markdown
+markdown = doc.to_markdown()
+print(markdown)
+
+# Convert to plain text
+text = doc.to_text()
+
+# Convert to JSON
+json_data = doc.to_json()
+```
+
+### With Context Manager
+
+```python
+from undoc import parse_file
+
+with parse_file("document.xlsx") as doc:
+    print(doc.to_markdown(frontmatter=True))
+    print(f"Sections: {doc.section_count}")
+    print(f"Resources: {doc.resource_count}")
+```
+
+### Parse from Bytes
+
+```python
+from undoc import parse_bytes
+
+with open("document.pptx", "rb") as f:
+    data = f.read()
+
+doc = parse_bytes(data)
+markdown = doc.to_markdown()
+```
+
+### Extract Resources (Images)
+
+```python
+from undoc import parse_file
+
+doc = parse_file("document.docx")
+
+# Get all resource IDs
+resource_ids = doc.get_resource_ids()
+
+for rid in resource_ids:
+    # Get resource metadata
+    info = doc.get_resource_info(rid)
+    print(f"Resource: {info['filename']} ({info['mime_type']})")
+
+    # Get resource binary data
+    data = doc.get_resource_data(rid)
+
+    # Save to file
+    with open(info['filename'], 'wb') as f:
+        f.write(data)
+```
+
+### Document Metadata
+
+```python
+from undoc import parse_file
+
+doc = parse_file("document.docx")
+
+print(f"Title: {doc.title}")
+print(f"Author: {doc.author}")
+print(f"Sections: {doc.section_count}")
+print(f"Resources: {doc.resource_count}")
+```
+
+### Handling Failures
+
+`UndocError.kind` says *why* a call failed, so you can react to the reason instead of
+matching on message text:
+
+```python
+from undoc import ErrorKind, UndocError, parse_file
+
+try:
+    doc = parse_file(path)
+    print(doc.to_markdown())
+except UndocError as err:
+    if err.kind is ErrorKind.ZIP_ARCHIVE:
+        print("The file is damaged.")
+    elif err.kind in (ErrorKind.UNKNOWN_FORMAT, ErrorKind.UNSUPPORTED_FORMAT):
+        print("Not a supported Office document.")
+    elif err.kind is ErrorKind.ENCRYPTED:
+        print("The document is encrypted.")
+    else:
+        # Also the right branch for a reason this build has no name for.
+        print(f"Extraction failed ({err.kind}): {err}")
+```
+
+The numbers behind `ErrorKind` are a stable ABI contract: a new reason takes the next free
+number and existing ones are never renumbered. Always keep a final `else` — an
+unrecognised value arrives as a plain `int` rather than an `ErrorKind`, so that a newer
+native library stays usable. `kind` is `ErrorKind.OTHER` for failures raised by the wrapper
+itself, and never `ErrorKind.NONE` (which means success).
+
+## Supported Formats
+
+- **DOCX** - Microsoft Word documents
+- **XLSX** - Microsoft Excel spreadsheets
+- **PPTX** - Microsoft PowerPoint presentations
+
+## Features
+
+- **RAG-Ready Output**: Structured Markdown optimized for RAG/LLM applications
+- **High Performance**: Native Rust implementation via FFI
+- **Asset Extraction**: Images and embedded resources
+- **Metadata Preservation**: Document properties, styles, formatting
+- **Cross-Platform**: Windows, Linux, macOS (Intel & ARM)
+
+## API Reference
+
+### Functions
+
+- `parse_file(path)` - Parse document from file path
+- `parse_bytes(data)` - Parse document from bytes
+- `version()` - Get library version
+
+### Undoc Class
+
+#### Conversion Methods
+
+- `to_markdown(frontmatter=False, escape_special=False, paragraph_spacing=False)` - Convert to Markdown
+- `to_text()` - Convert to plain text
+- `to_json(compact=False)` - Convert to JSON
+- `plain_text()` - Get plain text (fast extraction)
+
+#### Properties
+
+- `title` - Document title
+- `author` - Document author
+- `section_count` - Number of sections
+- `resource_count` - Number of resources
+
+#### Resource Methods
+
+- `get_resource_ids()` - List of resource IDs
+- `get_resource_info(id)` - Resource metadata
+- `get_resource_data(id)` - Resource binary data
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.

undoc-0.9.0/README.md

@@ -0,0 +1,166 @@
+# undoc
+
+High-performance Microsoft Office document extraction to Markdown.
+
+## Installation
+
+```bash
+pip install undoc
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from undoc import parse_file
+
+# Parse a document
+doc = parse_file("document.docx")
+
+# Convert to Markdown
+markdown = doc.to_markdown()
+print(markdown)
+
+# Convert to plain text
+text = doc.to_text()
+
+# Convert to JSON
+json_data = doc.to_json()
+```
+
+### With Context Manager
+
+```python
+from undoc import parse_file
+
+with parse_file("document.xlsx") as doc:
+    print(doc.to_markdown(frontmatter=True))
+    print(f"Sections: {doc.section_count}")
+    print(f"Resources: {doc.resource_count}")
+```
+
+### Parse from Bytes
+
+```python
+from undoc import parse_bytes
+
+with open("document.pptx", "rb") as f:
+    data = f.read()
+
+doc = parse_bytes(data)
+markdown = doc.to_markdown()
+```
+
+### Extract Resources (Images)
+
+```python
+from undoc import parse_file
+
+doc = parse_file("document.docx")
+
+# Get all resource IDs
+resource_ids = doc.get_resource_ids()
+
+for rid in resource_ids:
+    # Get resource metadata
+    info = doc.get_resource_info(rid)
+    print(f"Resource: {info['filename']} ({info['mime_type']})")
+
+    # Get resource binary data
+    data = doc.get_resource_data(rid)
+
+    # Save to file
+    with open(info['filename'], 'wb') as f:
+        f.write(data)
+```
+
+### Document Metadata
+
+```python
+from undoc import parse_file
+
+doc = parse_file("document.docx")
+
+print(f"Title: {doc.title}")
+print(f"Author: {doc.author}")
+print(f"Sections: {doc.section_count}")
+print(f"Resources: {doc.resource_count}")
+```
+
+### Handling Failures
+
+`UndocError.kind` says *why* a call failed, so you can react to the reason instead of
+matching on message text:
+
+```python
+from undoc import ErrorKind, UndocError, parse_file
+
+try:
+    doc = parse_file(path)
+    print(doc.to_markdown())
+except UndocError as err:
+    if err.kind is ErrorKind.ZIP_ARCHIVE:
+        print("The file is damaged.")
+    elif err.kind in (ErrorKind.UNKNOWN_FORMAT, ErrorKind.UNSUPPORTED_FORMAT):
+        print("Not a supported Office document.")
+    elif err.kind is ErrorKind.ENCRYPTED:
+        print("The document is encrypted.")
+    else:
+        # Also the right branch for a reason this build has no name for.
+        print(f"Extraction failed ({err.kind}): {err}")
+```
+
+The numbers behind `ErrorKind` are a stable ABI contract: a new reason takes the next free
+number and existing ones are never renumbered. Always keep a final `else` — an
+unrecognised value arrives as a plain `int` rather than an `ErrorKind`, so that a newer
+native library stays usable. `kind` is `ErrorKind.OTHER` for failures raised by the wrapper
+itself, and never `ErrorKind.NONE` (which means success).
+
+## Supported Formats
+
+- **DOCX** - Microsoft Word documents
+- **XLSX** - Microsoft Excel spreadsheets
+- **PPTX** - Microsoft PowerPoint presentations
+
+## Features
+
+- **RAG-Ready Output**: Structured Markdown optimized for RAG/LLM applications
+- **High Performance**: Native Rust implementation via FFI
+- **Asset Extraction**: Images and embedded resources
+- **Metadata Preservation**: Document properties, styles, formatting
+- **Cross-Platform**: Windows, Linux, macOS (Intel & ARM)
+
+## API Reference
+
+### Functions
+
+- `parse_file(path)` - Parse document from file path
+- `parse_bytes(data)` - Parse document from bytes
+- `version()` - Get library version
+
+### Undoc Class
+
+#### Conversion Methods
+
+- `to_markdown(frontmatter=False, escape_special=False, paragraph_spacing=False)` - Convert to Markdown
+- `to_text()` - Convert to plain text
+- `to_json(compact=False)` - Convert to JSON
+- `plain_text()` - Get plain text (fast extraction)
+
+#### Properties
+
+- `title` - Document title
+- `author` - Document author
+- `section_count` - Number of sections
+- `resource_count` - Number of resources
+
+#### Resource Methods
+
+- `get_resource_ids()` - List of resource IDs
+- `get_resource_info(id)` - Resource metadata
+- `get_resource_data(id)` - Resource binary data
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.

undoc-0.9.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "undoc"
+version = "0.9.0"
+description = "High-performance Microsoft Office document extraction to Markdown"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "iyulab", email = "tech@iyulab.com" }]
+keywords = ["office", "docx", "xlsx", "pptx", "markdown", "extraction"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/iyulab/undoc"
+Documentation = "https://github.com/iyulab/undoc#readme"
+Repository = "https://github.com/iyulab/undoc"
+Issues = "https://github.com/iyulab/undoc/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov>=4.0", "black>=23.0", "mypy>=1.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+undoc = ["lib/**/*"]
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

undoc-0.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

undoc-0.9.0/src/undoc/__init__.py

@@ -0,0 +1,10 @@
+"""undoc - High-performance Microsoft Office document extraction.
+
+This package provides Python bindings for the undoc library, which extracts
+DOCX, XLSX, and PPTX documents into structured Markdown with assets.
+"""
+
+from .undoc import ErrorKind, Undoc, UndocError, parse_file, parse_bytes, version
+
+__all__ = ["ErrorKind", "Undoc", "UndocError", "parse_file", "parse_bytes", "version"]
+__version__ = "0.9.0"

undoc-0.9.0/src/undoc/_native.py

@@ -0,0 +1,195 @@
+"""Native library loading for undoc."""
+
+import ctypes
+import platform
+import os
+import subprocess
+from pathlib import Path
+
+# Library filename by platform
+_LIB_NAMES = {
+    "Windows": "undoc.dll",
+    "Linux": "libundoc.so",
+    "Darwin": "libundoc.dylib",
+}
+
+
+def _is_musl() -> bool:
+    """Detect if the current Linux system uses musl libc."""
+    # Check if /etc/os-release indicates Alpine
+    try:
+        osrelease = Path("/etc/os-release").read_text()
+        if "alpine" in osrelease.lower():
+            return True
+    except OSError:
+        pass
+    # Check ldd version output (musl ldd identifies itself)
+    try:
+        result = subprocess.run(
+            ["ldd", "--version"], capture_output=True, text=True, timeout=5
+        )
+        output = result.stdout + result.stderr
+        if "musl" in output.lower():
+            return True
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return False
+
+
+def _get_linux_runtime_id(machine: str) -> str:
+    """Get the runtime ID for Linux, detecting musl vs glibc."""
+    if machine == "x86_64":
+        return "linux-musl-x64" if _is_musl() else "linux-x64"
+    raise OSError(f"Unsupported Linux architecture: {machine}")
+
+
+# Runtime identifier
+_RUNTIME_IDS = {
+    ("Windows", "AMD64"): "win-x64",
+    ("Windows", "x86_64"): "win-x64",
+    ("Darwin", "x86_64"): "osx-x64",
+    ("Darwin", "arm64"): "osx-arm64",
+}
+
+
+def _get_lib_path() -> Path:
+    """Get the path to the native library."""
+    system = platform.system()
+    machine = platform.machine()
+
+    lib_name = _LIB_NAMES.get(system)
+    if not lib_name:
+        raise OSError(f"Unsupported platform: {system}")
+
+    # Check UNDOC_LIB_PATH environment variable first
+    env_path = os.environ.get("UNDOC_LIB_PATH")
+    if env_path:
+        p = Path(env_path)
+        if p.exists():
+            return p
+
+    if system == "Linux":
+        runtime_id = _get_linux_runtime_id(machine)
+    else:
+        runtime_id = _RUNTIME_IDS.get((system, machine))
+        if not runtime_id:
+            raise OSError(f"Unsupported architecture: {system}/{machine}")
+
+    # Look for the library in the package
+    package_dir = Path(__file__).parent
+    lib_path = package_dir / "lib" / runtime_id / lib_name
+
+    if lib_path.exists():
+        return lib_path
+
+    # Fallback: look in package root
+    lib_path = package_dir / "lib" / lib_name
+    if lib_path.exists():
+        return lib_path
+
+    # Fallback: look in current directory
+    lib_path = Path(lib_name)
+    if lib_path.exists():
+        return lib_path
+
+    # Fallback: system library path
+    return Path(lib_name)
+
+
+def _load_library() -> ctypes.CDLL:
+    """Load the native undoc library."""
+    lib_path = _get_lib_path()
+
+    try:
+        if platform.system() == "Windows":
+            # On Windows, use LoadLibraryEx with LOAD_WITH_ALTERED_SEARCH_PATH
+            return ctypes.CDLL(str(lib_path), winmode=0)
+        else:
+            return ctypes.CDLL(str(lib_path))
+    except OSError as e:
+        raise OSError(
+            f"Failed to load undoc native library from {lib_path}: {e}\n"
+            f"Make sure the library is installed for your platform ({platform.system()}/{platform.machine()})."
+        ) from e
+
+
+# Load the library
+_lib = _load_library()
+
+# Define function signatures
+_lib.undoc_version.argtypes = []
+_lib.undoc_version.restype = ctypes.c_void_p
+
+_lib.undoc_last_error.argtypes = []
+_lib.undoc_last_error.restype = ctypes.c_void_p
+
+# Returns a raw int, not an enum: a newer native library may report a number this
+# build does not know, and it has to survive the trip rather than fail to convert.
+_lib.undoc_last_error_kind.argtypes = []
+_lib.undoc_last_error_kind.restype = ctypes.c_int
+
+_lib.undoc_parse_file.argtypes = [ctypes.c_char_p]
+_lib.undoc_parse_file.restype = ctypes.c_void_p
+
+_lib.undoc_parse_bytes.argtypes = [ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t]
+_lib.undoc_parse_bytes.restype = ctypes.c_void_p
+
+_lib.undoc_free_document.argtypes = [ctypes.c_void_p]
+_lib.undoc_free_document.restype = None
+
+_lib.undoc_to_markdown.argtypes = [ctypes.c_void_p, ctypes.c_uint]
+_lib.undoc_to_markdown.restype = ctypes.c_void_p
+
+_lib.undoc_to_text.argtypes = [ctypes.c_void_p]
+_lib.undoc_to_text.restype = ctypes.c_void_p
+
+_lib.undoc_to_json.argtypes = [ctypes.c_void_p, ctypes.c_int]
+_lib.undoc_to_json.restype = ctypes.c_void_p
+
+_lib.undoc_plain_text.argtypes = [ctypes.c_void_p]
+_lib.undoc_plain_text.restype = ctypes.c_void_p
+
+_lib.undoc_section_count.argtypes = [ctypes.c_void_p]
+_lib.undoc_section_count.restype = ctypes.c_int
+
+_lib.undoc_resource_count.argtypes = [ctypes.c_void_p]
+_lib.undoc_resource_count.restype = ctypes.c_int
+
+_lib.undoc_get_title.argtypes = [ctypes.c_void_p]
+_lib.undoc_get_title.restype = ctypes.c_void_p
+
+_lib.undoc_get_author.argtypes = [ctypes.c_void_p]
+_lib.undoc_get_author.restype = ctypes.c_void_p
+
+_lib.undoc_free_string.argtypes = [ctypes.c_void_p]
+_lib.undoc_free_string.restype = None
+
+_lib.undoc_get_resource_ids.argtypes = [ctypes.c_void_p]
+_lib.undoc_get_resource_ids.restype = ctypes.c_void_p
+
+_lib.undoc_get_resource_info.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.undoc_get_resource_info.restype = ctypes.c_void_p
+
+_lib.undoc_get_resource_data.argtypes = [
+    ctypes.c_void_p,
+    ctypes.c_char_p,
+    ctypes.POINTER(ctypes.c_size_t),
+]
+_lib.undoc_get_resource_data.restype = ctypes.POINTER(ctypes.c_uint8)
+
+_lib.undoc_free_bytes.argtypes = [ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t]
+_lib.undoc_free_bytes.restype = None
+
+# Export constants
+UNDOC_FLAG_FRONTMATTER = 1
+UNDOC_FLAG_ESCAPE_SPECIAL = 2
+UNDOC_FLAG_PARAGRAPH_SPACING = 4
+UNDOC_FLAG_REFINE = 8
+
+UNDOC_JSON_PRETTY = 0
+UNDOC_JSON_COMPACT = 1
+
+
+def get_library():
+    """Get the loaded native library."""
+    return _lib