anything2md 0.1.0__tar.gz

anything2md-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --extra test --frozen
+
+      - name: Run tests
+        run: uv run pytest -q
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Check metadata
+        run: uv run --with twine twine check dist/*

anything2md-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish package to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/anything2md
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

anything2md-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.dist/
+dist/
+build/
+*.egg-info/
+.venv/

anything2md-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: anything2md
+Version: 0.1.0
+Summary: Convert documents to Markdown using Cloudflare Workers AI toMarkdown.
+Project-URL: Homepage, https://github.com/herrkaefer/anything2md
+Project-URL: Repository, https://github.com/herrkaefer/anything2md
+Author: Anything2MD Contributors
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# anything2md
+[![CI](https://github.com/herrkaefer/anything2md/actions/workflows/ci.yml/badge.svg)](https://github.com/herrkaefer/anything2md/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/anything2md.svg)](https://pypi.org/project/anything2md/)
+[![Python](https://img.shields.io/pypi/pyversions/anything2md.svg)](https://pypi.org/project/anything2md/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Python package and CLI for converting URLs or local documents into Markdown using Cloudflare Workers AI `toMarkdown()`.
+
+## Install
+
+From GitHub:
+
+```bash
+pip install "git+https://github.com/herrkaefer/anything2md.git"
+```
+
+### Cloudflare Token Setup
+
+Create a Cloudflare API Token for the target account and include these permissions:
+
+- `Workers AI` 
+- `Browser Rendering - Edit`
+
+## Library Usage
+
+```python
+import anything2md
+
+mdconverter = anything2md(account_id="xxx", api_token="xxx")
+result = mdconverter.convert("https://example.com")
+print(result.markdown)
+```
+
+## Supported Formats
+
+Based on Cloudflare docs, current supported extensions include:
+
+`pdf`, `jpeg/jpg`, `png`, `webp`, `svg`, `html/htm`, `xml`, `csv`, `docx`, `xlsx`, `xlsm`, `xlsb`, `xls`, `et`, `ods`, `odt`, `numbers`
+
+Runtime check via API:
+
+```bash
+uv run python -c "from anything2md import MarkdownConverter; c=MarkdownConverter(account_id='<id>', api_token='<token>'); print([f.extension for f in c.supported_formats()])"
+```
+
+## Local Usage
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+```bash
+export CLOUDFLARE_ACCOUNT_ID="your_account_id"
+export CLOUDFLARE_API_TOKEN="your_api_token"
+
+uv run anything2md https://pub-979cb28270cc461d94bc8a169d8f389d.r2.dev/somatosensory.pdf
+uv run anything2md https://pub-979cb28270cc461d94bc8a169d8f389d.r2.dev/cat.jpeg -o output.md
+uv run anything2md https://example.com
+```
+
+## References
+
+Cloudflare docs:
+- Markdown Conversion overview: https://developers.cloudflare.com/workers-ai/features/markdown-conversion/
+- API reference (`toMarkdown`): https://developers.cloudflare.com/api/resources/ai/methods/run/#to-markdown-conversion-to-markdown
+- API reference (`supported formats`): https://developers.cloudflare.com/api/resources/ai/methods/run/#to-markdown-conversion-supported-formats
+- Browser Rendering Markdown endpoint (URL input): https://developers.cloudflare.com/browser-rendering/rest-api/markdown-endpoint/
+- Markdown for Agents (`Accept: text/markdown`): https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/
+
+## License
+
+MIT

anything2md-0.1.0/README.md

@@ -0,0 +1,74 @@
+# anything2md
+[![CI](https://github.com/herrkaefer/anything2md/actions/workflows/ci.yml/badge.svg)](https://github.com/herrkaefer/anything2md/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/anything2md.svg)](https://pypi.org/project/anything2md/)
+[![Python](https://img.shields.io/pypi/pyversions/anything2md.svg)](https://pypi.org/project/anything2md/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Python package and CLI for converting URLs or local documents into Markdown using Cloudflare Workers AI `toMarkdown()`.
+
+## Install
+
+From GitHub:
+
+```bash
+pip install "git+https://github.com/herrkaefer/anything2md.git"
+```
+
+### Cloudflare Token Setup
+
+Create a Cloudflare API Token for the target account and include these permissions:
+
+- `Workers AI` 
+- `Browser Rendering - Edit`
+
+## Library Usage
+
+```python
+import anything2md
+
+mdconverter = anything2md(account_id="xxx", api_token="xxx")
+result = mdconverter.convert("https://example.com")
+print(result.markdown)
+```
+
+## Supported Formats
+
+Based on Cloudflare docs, current supported extensions include:
+
+`pdf`, `jpeg/jpg`, `png`, `webp`, `svg`, `html/htm`, `xml`, `csv`, `docx`, `xlsx`, `xlsm`, `xlsb`, `xls`, `et`, `ods`, `odt`, `numbers`
+
+Runtime check via API:
+
+```bash
+uv run python -c "from anything2md import MarkdownConverter; c=MarkdownConverter(account_id='<id>', api_token='<token>'); print([f.extension for f in c.supported_formats()])"
+```
+
+## Local Usage
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+```bash
+export CLOUDFLARE_ACCOUNT_ID="your_account_id"
+export CLOUDFLARE_API_TOKEN="your_api_token"
+
+uv run anything2md https://pub-979cb28270cc461d94bc8a169d8f389d.r2.dev/somatosensory.pdf
+uv run anything2md https://pub-979cb28270cc461d94bc8a169d8f389d.r2.dev/cat.jpeg -o output.md
+uv run anything2md https://example.com
+```
+
+## References
+
+Cloudflare docs:
+- Markdown Conversion overview: https://developers.cloudflare.com/workers-ai/features/markdown-conversion/
+- API reference (`toMarkdown`): https://developers.cloudflare.com/api/resources/ai/methods/run/#to-markdown-conversion-to-markdown
+- API reference (`supported formats`): https://developers.cloudflare.com/api/resources/ai/methods/run/#to-markdown-conversion-supported-formats
+- Browser Rendering Markdown endpoint (URL input): https://developers.cloudflare.com/browser-rendering/rest-api/markdown-endpoint/
+- Markdown for Agents (`Accept: text/markdown`): https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/
+
+## License
+
+MIT

anything2md-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anything2md"
+version = "0.1.0"
+description = "Convert documents to Markdown using Cloudflare Workers AI toMarkdown."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "Anything2MD Contributors"}
+]
+dependencies = [
+  "httpx>=0.27,<1"
+]
+
+[project.urls]
+Homepage = "https://github.com/herrkaefer/anything2md"
+Repository = "https://github.com/herrkaefer/anything2md"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8,<9"
+]
+
+[project.scripts]
+anything2md = "anything2md.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

anything2md-0.1.0/src/anything2md/__init__.py

@@ -0,0 +1,50 @@
+"""anything2md package."""
+
+import sys
+from types import ModuleType
+from typing import Any
+
+from .config import CloudflareCredentials, ConvertOptions
+from .converter import MarkdownConverter
+from .errors import (
+    APIError,
+    Anything2MDError,
+    FileReadError,
+    HTTPError,
+    InvalidResponseError,
+    NetworkError,
+    UnsupportedFormatError,
+)
+from .models import ConversionResult, SupportedFormatInfo
+
+
+def anything2md(*args: Any, **kwargs: Any) -> MarkdownConverter:
+    """Factory shorthand for MarkdownConverter(...)."""
+    return MarkdownConverter(*args, **kwargs)
+
+
+class _Anything2MDModule(ModuleType):
+    def __call__(self, *args: Any, **kwargs: Any) -> MarkdownConverter:
+        return MarkdownConverter(*args, **kwargs)
+
+
+sys.modules[__name__].__class__ = _Anything2MDModule
+
+SwiftToMarkdownConverter = MarkdownConverter
+
+__all__ = [
+    "anything2md",
+    "Anything2MDError",
+    "UnsupportedFormatError",
+    "NetworkError",
+    "FileReadError",
+    "HTTPError",
+    "APIError",
+    "InvalidResponseError",
+    "CloudflareCredentials",
+    "ConvertOptions",
+    "ConversionResult",
+    "SupportedFormatInfo",
+    "MarkdownConverter",
+    "SwiftToMarkdownConverter",
+]

anything2md-0.1.0/src/anything2md/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

anything2md-0.1.0/src/anything2md/cli.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .config import ConvertOptions
+from .converter import MarkdownConverter
+from .errors import Anything2MDError
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="anything2md",
+        description="Convert a URL or local file into Markdown using Cloudflare Workers AI.",
+    )
+    parser.add_argument("input", help="Input URL (http/https) or local file path.")
+    parser.add_argument("--account-id", help="Cloudflare account ID. Falls back to CLOUDFLARE_ACCOUNT_ID.")
+    parser.add_argument("--api-token", help="Cloudflare API token. Falls back to CLOUDFLARE_API_TOKEN.")
+    parser.add_argument("--timeout", type=float, default=60.0, help="Request timeout in seconds. Default: 60.")
+    parser.add_argument(
+        "--max-retry-count",
+        type=int,
+        default=2,
+        help="Retry attempts for retryable API/network failures. Default: 2.",
+    )
+    parser.add_argument(
+        "--retry-base-delay",
+        type=float,
+        default=1.0,
+        help="Base retry delay in seconds (exponential backoff). Default: 1.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print progress messages to stderr.",
+    )
+    parser.add_argument(
+        "--url-strategy",
+        choices=["auto", "download", "browser"],
+        default="auto",
+        help="URL conversion strategy. Web URL path tries Accept:text/markdown first, then browser-rendering fallback.",
+    )
+    parser.add_argument("-o", "--output", help="Output markdown file path. Defaults to stdout.")
+    return parser.parse_args()
+
+
+def _resolve_credential(primary: str | None, env_name: str) -> str:
+    value = (primary or os.getenv(env_name, "")).strip()
+    if not value:
+        raise SystemExit(f"Missing credential: use flag or set {env_name}.")
+    return value
+
+
+def _is_remote_url(value: str) -> bool:
+    parsed = urlparse(value)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)
+
+
+def _emit_progress(message: str) -> None:
+    print(f"[anything2md] {message}", file=sys.stderr, flush=True)
+
+
+def main() -> None:
+    args = parse_args()
+    account_id = _resolve_credential(args.account_id, "CLOUDFLARE_ACCOUNT_ID")
+    api_token = _resolve_credential(args.api_token, "CLOUDFLARE_API_TOKEN")
+    options = ConvertOptions(
+        timeout=args.timeout,
+        max_retry_count=args.max_retry_count,
+        retry_base_delay=args.retry_base_delay,
+    )
+    progress_callback = _emit_progress if args.verbose else None
+
+    converter = MarkdownConverter(account_id=account_id, api_token=api_token, options=options)
+    try:
+        try:
+            local_or_remote_input: str | Path
+            if _is_remote_url(args.input):
+                local_or_remote_input = args.input
+            else:
+                local_or_remote_input = Path(args.input).expanduser()
+
+            result = converter.convert(
+                local_or_remote_input,
+                url_strategy=args.url_strategy,
+                progress_callback=progress_callback,
+            )
+            if isinstance(result, list):
+                raise SystemExit("CLI currently supports single-item conversion only.")
+        except Anything2MDError as exc:
+            print(str(exc), file=sys.stderr)
+            raise SystemExit(1) from exc
+    finally:
+        converter.close()
+
+    if args.output:
+        output_path = Path(args.output).expanduser()
+        output_path.write_text(result.markdown, encoding="utf-8")
+        print(str(output_path))
+        return
+
+    print(result.markdown, end="" if result.markdown.endswith("\n") else "\n")
+
+
+if __name__ == "__main__":
+    main()

anything2md-0.1.0/src/anything2md/client.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+from typing import Sequence
+
+import httpx
+
+from .config import CloudflareCredentials, ConvertOptions
+from .errors import APIError, HTTPError, InvalidResponseError, NetworkError, UnsupportedFormatError
+from .formats import from_filename
+from .models import ConversionResult, SupportedFormatInfo
+
+
+_RETRYABLE_NETWORK_EXCEPTIONS = (
+    httpx.ConnectError,
+    httpx.ReadError,
+    httpx.WriteError,
+    httpx.ConnectTimeout,
+    httpx.ReadTimeout,
+    httpx.WriteTimeout,
+    httpx.PoolTimeout,
+    httpx.RemoteProtocolError,
+)
+
+
+class CloudflareClient:
+    def __init__(
+        self,
+        credentials: CloudflareCredentials,
+        options: ConvertOptions = ConvertOptions(),
+        session: httpx.Client | None = None,
+    ) -> None:
+        self.credentials = credentials
+        self.options = options
+        self._session = session or httpx.Client(timeout=options.timeout)
+
+    def to_markdown(self, files: Sequence[tuple[bytes, str]]) -> list[ConversionResult]:
+        if not files:
+            return []
+
+        multipart: list[tuple[str, tuple[str, bytes, str]]] = []
+        for data, filename in files:
+            fmt = from_filename(filename)
+            if fmt is None:
+                raise UnsupportedFormatError(filename)
+            multipart.append(("files", (filename, data, fmt.mime_type)))
+
+        endpoint = (
+            f"https://api.cloudflare.com/client/v4/accounts/{self.credentials.account_id}/"
+            "ai/tomarkdown"
+        )
+        response = self._request_with_retry(
+            method="POST",
+            endpoint=endpoint,
+            files=multipart,
+        )
+
+        payload = self._decode_success_payload(response)
+        result_payload = payload.get("result", [])
+        if not isinstance(result_payload, list):
+            raise InvalidResponseError()
+
+        try:
+            return [ConversionResult.from_api_item(item) for item in result_payload]
+        except (TypeError, ValueError, KeyError) as exc:
+            raise InvalidResponseError() from exc
+
+    def supported_formats(self) -> list[SupportedFormatInfo]:
+        endpoint = (
+            f"https://api.cloudflare.com/client/v4/accounts/{self.credentials.account_id}/"
+            "ai/tomarkdown/supported"
+        )
+        response = self._request_with_retry(
+            method="GET",
+            endpoint=endpoint,
+        )
+
+        payload = self._decode_success_payload(response)
+        result_payload = payload.get("result", [])
+        if not isinstance(result_payload, list):
+            raise InvalidResponseError()
+
+        try:
+            return [SupportedFormatInfo.from_api_item(item) for item in result_payload]
+        except (TypeError, ValueError, KeyError) as exc:
+            raise InvalidResponseError() from exc
+
+    def markdown_from_url(self, url: str, **options: Any) -> str:
+        endpoint = (
+            f"https://api.cloudflare.com/client/v4/accounts/{self.credentials.account_id}/"
+            "browser-rendering/markdown"
+        )
+        payload: dict[str, Any] = {"url": url}
+        payload.update(options)
+
+        response = self._request_with_retry(
+            method="POST",
+            endpoint=endpoint,
+            json=payload,
+        )
+
+        decoded = self._decode_success_payload(response)
+        result_payload = decoded.get("result")
+        if not isinstance(result_payload, str):
+            raise InvalidResponseError()
+        return result_payload
+
+    def close(self) -> None:
+        self._session.close()
+
+    def _request_with_retry(self, method: str, endpoint: str, **kwargs: Any) -> httpx.Response:
+        headers = kwargs.pop("headers", {}) or {}
+        headers["Authorization"] = f"Bearer {self.credentials.api_token}"
+
+        attempt = 0
+        while True:
+            try:
+                response = self._session.request(
+                    method=method,
+                    url=endpoint,
+                    headers=headers,
+                    timeout=self.options.timeout,
+                    **kwargs,
+                )
+            except _RETRYABLE_NETWORK_EXCEPTIONS as exc:
+                if self._should_retry_network(attempt):
+                    self._sleep_before_retry(attempt)
+                    attempt += 1
+                    continue
+                raise NetworkError(exc) from exc
+            except httpx.HTTPError as exc:
+                raise NetworkError(exc) from exc
+
+            if not 200 <= response.status_code < 300:
+                if self._should_retry_status(response.status_code, attempt):
+                    self._sleep_before_retry(attempt)
+                    attempt += 1
+                    continue
+                raise HTTPError(response.status_code, response.text)
+            return response
+
+    def _decode_success_payload(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise InvalidResponseError() from exc
+
+        if not isinstance(payload, dict):
+            raise InvalidResponseError()
+
+        success = bool(payload.get("success", False))
+        if not success:
+            messages = self._extract_messages(payload)
+            raise APIError(messages)
+        return payload
+
+    def _should_retry_status(self, status_code: int, attempt: int) -> bool:
+        return attempt < self.options.max_retry_count and (
+            status_code == 429 or status_code >= 500
+        )
+
+    def _should_retry_network(self, attempt: int) -> bool:
+        return attempt < self.options.max_retry_count
+
+    def _sleep_before_retry(self, attempt: int) -> None:
+        base = max(0.0, self.options.retry_base_delay)
+        if base <= 0:
+            return
+        time.sleep(base * (2**attempt))
+
+    @staticmethod
+    def _extract_messages(payload: dict) -> list[str]:
+        values: list[str] = []
+        for key in ("errors", "messages"):
+            entries = payload.get(key, [])
+            if not isinstance(entries, list):
+                continue
+            for item in entries:
+                if isinstance(item, str):
+                    values.append(item)
+                elif isinstance(item, dict):
+                    message = item.get("message")
+                    if isinstance(message, str):
+                        values.append(message)
+        return values

anything2md-0.1.0/src/anything2md/config.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CloudflareCredentials:
+    """Cloudflare credentials required for Workers AI requests."""
+
+    account_id: str
+    api_token: str
+
+
+@dataclass(frozen=True)
+class ConvertOptions:
+    """Runtime options for conversion requests."""
+
+    timeout: float = 60.0
+    max_retry_count: int = 2
+    retry_base_delay: float = 1.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "max_retry_count", max(0, self.max_retry_count))