apdf-cloud-cli 0.1.0__py3-none-any.whl

apdf_cloud_cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI and MCP tools for APDF."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

apdf_cloud_cli/cli.py

@@ -0,0 +1,162 @@
+"""Command-line interface for APDF tools."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import operations
+from .config import ConfigError
+
+app = typer.Typer(help="APDF CLI tools.")
+storage_app = typer.Typer(help="Cloud storage operations.")
+pdf_app = typer.Typer(help="PDF operations.")
+mcp_app = typer.Typer(help="MCP server commands.")
+app.add_typer(storage_app, name="storage")
+app.add_typer(pdf_app, name="pdf")
+app.add_typer(mcp_app, name="mcp")
+
+console = Console()
+
+
+def _json(data: object) -> None:
+    console.print_json(json.dumps(data, ensure_ascii=False))
+
+
+def _handle_error(exc: Exception) -> None:
+    typer.echo(f"Error: {exc}", err=True)
+    raise typer.Exit(code=1) from exc
+
+
+def _run(action):
+    try:
+        return action()
+    except (operations.ApdfToolError, ConfigError) as exc:
+        _handle_error(exc)
+
+
+@storage_app.command("list")
+def list_storage_files(
+    path: Annotated[str, typer.Argument(help="Folder path in Aspose storage.")],
+    storage: Annotated[str | None, typer.Option("--storage", help="Storage name.")] = None,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit JSON output.")] = False,
+) -> None:
+    """List files and folders in Aspose storage."""
+
+    result = _run(lambda: operations.list_files(path, storage))
+    if as_json:
+        _json(result)
+        return
+
+    table = Table(title=f"Storage: {storage or 'default'}  Path: {path}")
+    table.add_column("Name")
+    table.add_column("Path")
+    table.add_column("Size", justify="right")
+    table.add_column("Folder")
+
+    items = result.get("items", {})
+    values = items.get("value") or items.get("Value") or items.get("files") or items
+    if isinstance(values, dict):
+        values = values.get("value") or values.get("Value") or []
+    if not isinstance(values, list):
+        values = []
+
+    for item in values:
+        if not isinstance(item, dict):
+            continue
+        table.add_row(
+            str(item.get("name") or item.get("Name") or ""),
+            str(item.get("path") or item.get("Path") or ""),
+            str(item.get("size") or item.get("Size") or ""),
+            str(item.get("is_folder") or item.get("IsFolder") or False),
+        )
+    console.print(table)
+
+
+@storage_app.command("upload")
+def upload_storage_file(
+    local_path: Annotated[Path, typer.Argument(help="Local file to upload.")],
+    remote_path: Annotated[str, typer.Argument(help="Remote storage path.")],
+    storage: Annotated[str | None, typer.Option("--storage", help="Storage name.")] = None,
+) -> None:
+    """Upload a local file to Aspose storage."""
+
+    result = _run(lambda: operations.upload_file(local_path, remote_path, storage))
+    console.print(f"Uploaded [bold]{result['local_path']}[/bold] to [bold]{remote_path}[/bold].")
+
+
+@storage_app.command("download")
+def download_storage_file(
+    remote_path: Annotated[str, typer.Argument(help="Remote storage path.")],
+    local_path: Annotated[Path, typer.Argument(help="Local output path.")],
+    storage: Annotated[str | None, typer.Option("--storage", help="Storage name.")] = None,
+    version_id: Annotated[str | None, typer.Option("--version-id", help="File version ID.")] = None,
+) -> None:
+    """Download a file from Aspose storage."""
+
+    result = _run(
+        lambda: operations.download_file(remote_path, local_path, storage, version_id)
+    )
+    console.print(f"Downloaded [bold]{remote_path}[/bold] to [bold]{result['local_path']}[/bold].")
+
+
+@pdf_app.command("merge")
+def merge_pdf_files(
+    input_1: Annotated[str, typer.Argument(help="First input PDF path in storage.")],
+    input_2: Annotated[str, typer.Argument(help="Second input PDF path in storage.")],
+    output_name: Annotated[str, typer.Argument(help="Output PDF name.")],
+    folder: Annotated[str | None, typer.Option("--folder", help="Output folder.")] = None,
+    storage: Annotated[str | None, typer.Option("--storage", help="Storage name.")] = None,
+) -> None:
+    """Merge two PDF files already present in Aspose storage."""
+
+    result = _run(lambda: operations.merge_pdfs(input_1, input_2, output_name, folder, storage))
+    console.print(
+        f"Merged [bold]{input_1}[/bold] and [bold]{input_2}[/bold] into "
+        f"[bold]{result['output_name']}[/bold]."
+    )
+
+
+@pdf_app.command("extract-text")
+def extract_pdf_text(
+    name: Annotated[str, typer.Argument(help="PDF name/path in storage.")],
+    folder: Annotated[str | None, typer.Option("--folder", help="Document folder.")] = None,
+    storage: Annotated[str | None, typer.Option("--storage", help="Storage name.")] = None,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit JSON output.")] = False,
+    output: Annotated[Path | None, typer.Option("--output", help="Write plain text to a file.")] = None,
+) -> None:
+    """Extract text from a PDF in Aspose storage."""
+
+    result = _run(lambda: operations.extract_text(name, folder, storage))
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(result["text"], encoding="utf-8")
+
+    if as_json:
+        _json(result)
+    elif output:
+        console.print(f"Wrote extracted text to [bold]{output}[/bold].")
+    else:
+        console.print(result["text"])
+
+
+@mcp_app.command("serve")
+def serve_mcp() -> None:
+    """Run the MCP server over stdio."""
+
+    from .mcp_server import main
+
+    main()
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

apdf_cloud_cli/client.py

@@ -0,0 +1,20 @@
+"""APDF SDK client factory."""
+
+from __future__ import annotations
+
+import asposepdfcloud
+
+from .config import AsposeConfig, load_config
+
+
+def create_pdf_api(config: AsposeConfig | None = None) -> asposepdfcloud.PdfApi:
+    """Create an authenticated Aspose PdfApi instance."""
+
+    cfg = config or load_config()
+    api_client = asposepdfcloud.ApiClient(
+        cfg.client_secret,
+        cfg.client_id,
+        cfg.base_url,
+        cfg.self_host,
+    )
+    return asposepdfcloud.PdfApi(api_client)

apdf_cloud_cli/config.py

@@ -0,0 +1,75 @@
+"""Configuration helpers for APDF access."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ConfigError(RuntimeError):
+    """Raised when required configuration is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class AsposeConfig:
+    client_id: str
+    client_secret: str
+    base_url: str | None = None
+    self_host: bool = False
+    storage_name: str | None = None
+
+
+def _truthy(value: str | None) -> bool:
+    return value is not None and value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _read_env_file(path: str | Path | None) -> dict[str, str]:
+    if path is None:
+        return {}
+
+    env_path = Path(path)
+    if not env_path.is_file():
+        return {}
+
+    values: dict[str, str] = {}
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, value = stripped.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key:
+            values[key] = value
+    return values
+
+
+def _get_setting(name: str, env_file_values: dict[str, str]) -> str:
+    return os.getenv(name, env_file_values.get(name, "")).strip()
+
+
+def load_config(env_file: str | Path | None = ".env") -> AsposeConfig:
+    """Load Aspose Cloud configuration from environment variables and optional .env."""
+
+    env_file_values = _read_env_file(env_file)
+
+    client_id = _get_setting("ASPOSE_CLIENT_ID", env_file_values)
+    client_secret = _get_setting("ASPOSE_CLIENT_SECRET", env_file_values)
+
+    if not client_id or not client_secret:
+        raise ConfigError(
+            "Missing Aspose credentials. Set ASPOSE_CLIENT_ID and "
+            "ASPOSE_CLIENT_SECRET."
+        )
+
+    base_url = _get_setting("ASPOSE_BASE_URL", env_file_values) or None
+    storage_name = _get_setting("ASPOSE_STORAGE_NAME", env_file_values) or None
+
+    return AsposeConfig(
+        client_id=client_id,
+        client_secret=client_secret,
+        base_url=base_url,
+        self_host=_truthy(_get_setting("ASPOSE_SELF_HOST", env_file_values)),
+        storage_name=storage_name,
+    )

apdf_cloud_cli/mcp_server.py

@@ -0,0 +1,82 @@
+"""MCP server exposing APDF Stage 1 tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from . import operations
+
+mcp = FastMCP("aspose-pdf-cloud")
+
+
+def _safe_call(func, *args: Any, **kwargs: Any) -> dict[str, Any]:
+    try:
+        return {"ok": True, "data": func(*args, **kwargs)}
+    except Exception as exc:  # noqa: BLE001 - MCP should receive sanitized failures.
+        return {"ok": False, "error": str(exc)}
+
+
+@mcp.tool()
+def list_files(path: str, storage_name: str | None = None) -> dict[str, Any]:
+    """List files and folders in Aspose storage."""
+
+    return _safe_call(operations.list_files, path, storage_name)
+
+
+@mcp.tool()
+def upload_file(
+    local_path: str,
+    remote_path: str,
+    storage_name: str | None = None,
+) -> dict[str, Any]:
+    """Upload a local file to Aspose storage."""
+
+    return _safe_call(operations.upload_file, local_path, remote_path, storage_name)
+
+
+@mcp.tool()
+def download_file(
+    remote_path: str,
+    local_path: str,
+    storage_name: str | None = None,
+    version_id: str | None = None,
+) -> dict[str, Any]:
+    """Download a file from Aspose storage."""
+
+    return _safe_call(
+        operations.download_file,
+        remote_path,
+        local_path,
+        storage_name,
+        version_id,
+    )
+
+
+@mcp.tool()
+def merge_pdfs(
+    input_1: str,
+    input_2: str,
+    output_name: str,
+    folder: str | None = None,
+    storage: str | None = None,
+) -> dict[str, Any]:
+    """Merge two PDF files already present in Aspose storage."""
+
+    return _safe_call(operations.merge_pdfs, input_1, input_2, output_name, folder, storage)
+
+
+@mcp.tool()
+def extract_text(
+    name: str,
+    folder: str | None = None,
+    storage: str | None = None,
+) -> dict[str, Any]:
+    """Extract text from a PDF in Aspose storage."""
+
+    return _safe_call(operations.extract_text, name, folder, storage)
+
+
+def main() -> None:
+    mcp.run()

apdf_cloud_cli/operations.py

@@ -0,0 +1,230 @@
+"""Shared Stage 1 APDF operations."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+import asposepdfcloud
+
+from .client import create_pdf_api
+from .config import AsposeConfig, load_config
+
+
+class ApdfToolError(RuntimeError):
+    """Raised for sanitized user-facing operation failures."""
+
+
+def _api_error(exc: Exception) -> ApdfToolError:
+    reason = getattr(exc, "reason", None) or str(exc)
+    status = getattr(exc, "status", None)
+    message = "Aspose API error"
+    if status:
+        message += f" ({status})"
+    if reason:
+        message += f": {reason}"
+    return ApdfToolError(message)
+
+
+def _call_api(func, *args: Any, **kwargs: Any) -> Any:
+    try:
+        return func(*args, **{k: v for k, v in kwargs.items() if v is not None})
+    except Exception as exc:  # noqa: BLE001 - SDK raises several exception shapes.
+        api_exception = getattr(getattr(asposepdfcloud, "rest", None), "ApiException", None)
+        if api_exception and isinstance(exc, api_exception):
+            raise _api_error(exc) from exc
+        raise ApdfToolError(str(exc)) from exc
+
+
+def _api_and_config(api: Any | None, config: AsposeConfig | None) -> tuple[Any, AsposeConfig | None]:
+    if api is not None:
+        return api, config
+    cfg = config or load_config()
+    return create_pdf_api(cfg), cfg
+
+
+def _storage(explicit: str | None, config: AsposeConfig | None) -> str | None:
+    return explicit if explicit is not None else (config.storage_name if config else None)
+
+
+def to_plain_data(value: Any) -> Any:
+    """Convert SDK model objects into JSON-friendly values."""
+
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, list | tuple | set):
+        return [to_plain_data(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): to_plain_data(item) for key, item in value.items()}
+    if hasattr(value, "to_dict"):
+        return to_plain_data(value.to_dict())
+    if hasattr(value, "__dict__"):
+        return {
+            key.lstrip("_"): to_plain_data(item)
+            for key, item in vars(value).items()
+            if not key.startswith("__")
+        }
+    return str(value)
+
+
+def list_files(
+    path: str,
+    storage_name: str | None = None,
+    *,
+    api: Any | None = None,
+    config: AsposeConfig | None = None,
+) -> dict[str, Any]:
+    pdf_api, cfg = _api_and_config(api, config)
+    effective_storage = _storage(storage_name, cfg)
+    response = _call_api(pdf_api.get_files_list, path, storage_name=effective_storage)
+    return {"path": path, "storage_name": effective_storage, "items": to_plain_data(response)}
+
+
+def upload_file(
+    local_path: str | Path,
+    remote_path: str,
+    storage_name: str | None = None,
+    *,
+    api: Any | None = None,
+    config: AsposeConfig | None = None,
+) -> dict[str, Any]:
+    source = Path(local_path)
+    if not source.is_file():
+        raise ApdfToolError(f"Local file not found: {source}")
+
+    pdf_api, cfg = _api_and_config(api, config)
+    effective_storage = _storage(storage_name, cfg)
+    response = _call_api(
+        pdf_api.upload_file,
+        remote_path,
+        str(source),
+        storage_name=effective_storage,
+    )
+    return {
+        "local_path": str(source),
+        "remote_path": remote_path,
+        "storage_name": effective_storage,
+        "result": to_plain_data(response),
+    }
+
+
+def download_file(
+    remote_path: str,
+    local_path: str | Path,
+    storage_name: str | None = None,
+    version_id: str | None = None,
+    *,
+    api: Any | None = None,
+    config: AsposeConfig | None = None,
+) -> dict[str, Any]:
+    destination = Path(local_path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    pdf_api, cfg = _api_and_config(api, config)
+    effective_storage = _storage(storage_name, cfg)
+    downloaded = _call_api(
+        pdf_api.download_file,
+        remote_path,
+        storage_name=effective_storage,
+        version_id=version_id,
+    )
+
+    if isinstance(downloaded, bytes):
+        destination.write_bytes(downloaded)
+    elif hasattr(downloaded, "read"):
+        with destination.open("wb") as output:
+            shutil.copyfileobj(downloaded, output)
+    else:
+        downloaded_path = Path(str(downloaded))
+        if not downloaded_path.is_file():
+            raise ApdfToolError(f"Download did not return a readable file: {downloaded}")
+        shutil.copyfile(downloaded_path, destination)
+
+    return {
+        "remote_path": remote_path,
+        "local_path": str(destination),
+        "storage_name": effective_storage,
+        "version_id": version_id,
+    }
+
+
+def merge_pdfs(
+    input_1: str,
+    input_2: str,
+    output_name: str,
+    folder: str | None = None,
+    storage: str | None = None,
+    *,
+    api: Any | None = None,
+    config: AsposeConfig | None = None,
+) -> dict[str, Any]:
+    pdf_api, cfg = _api_and_config(api, config)
+    effective_storage = _storage(storage, cfg)
+    merge_documents = asposepdfcloud.MergeDocuments(list=[input_1, input_2])
+    response = _call_api(
+        pdf_api.put_merge_documents,
+        output_name,
+        merge_documents,
+        folder=folder,
+        storage=effective_storage,
+    )
+    return {
+        "inputs": [input_1, input_2],
+        "output_name": output_name,
+        "folder": folder,
+        "storage": effective_storage,
+        "result": to_plain_data(response),
+    }
+
+
+def _extract_text_from_rects(data: Any) -> str:
+    plain = to_plain_data(data)
+    fragments: list[str] = []
+
+    def collect(value: Any) -> None:
+        if isinstance(value, dict):
+            text = value.get("text") or value.get("Text")
+            if isinstance(text, str) and text:
+                fragments.append(text)
+            for item in value.values():
+                collect(item)
+        elif isinstance(value, list):
+            for item in value:
+                collect(item)
+
+    collect(plain)
+    return "\n".join(fragments)
+
+
+def extract_text(
+    name: str,
+    folder: str | None = None,
+    storage: str | None = None,
+    *,
+    api: Any | None = None,
+    config: AsposeConfig | None = None,
+) -> dict[str, Any]:
+    pdf_api, cfg = _api_and_config(api, config)
+    effective_storage = _storage(storage, cfg)
+    response = _call_api(
+        pdf_api.get_text,
+        name,
+        0,
+        0,
+        10000,
+        10000,
+        folder=folder,
+        storage=effective_storage,
+    )
+    raw = to_plain_data(response)
+    text = _extract_text_from_rects(raw)
+    return {
+        "name": name,
+        "folder": folder,
+        "storage": effective_storage,
+        "text": text,
+        "raw": raw,
+    }

apdf_cloud_cli/py.typed

@@ -0,0 +1 @@
+

apdf_cloud_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: apdf-cloud-cli
+Version: 0.1.0
+Summary: CLI and MCP server tools for Aspose PDF Cloud
+Keywords: aspose,pdf,cli,mcp
+Author: Andriy Andruhovski
+Author-email: andruhovski@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Provides-Extra: dev
+Requires-Dist: asposepdfcloud (>=26.4.0,<27.0.0)
+Requires-Dist: build (>=1.2.0) ; extra == "dev"
+Requires-Dist: mcp (>=1.0.0)
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: pytest-mock (>=3.12.0) ; extra == "dev"
+Requires-Dist: rich (>=13.0.0)
+Requires-Dist: twine (>=5.0.0) ; extra == "dev"
+Requires-Dist: typer (>=0.12.0)
+Project-URL: Homepage, https://github.com/andruhovski/apdf-tools
+Project-URL: Issues, https://github.com/andruhovski/apdf-tools/issues
+Project-URL: Repository, https://github.com/andruhovski/apdf-tools
+Description-Content-Type: text/markdown
+
+# APDF Cloud CLI + MCP Tools
+
+Stage 1 exposes APDF storage and PDF operations through both a CLI
+and an MCP server.
+
+## Configuration
+
+Set credentials before running CLI commands or the MCP server:
+
+```powershell
+$env:ASPOSE_CLIENT_ID = "your-client-id"
+$env:ASPOSE_CLIENT_SECRET = "your-client-secret"
+```
+
+Optional environment variables:
+
+- `ASPOSE_BASE_URL`
+- `ASPOSE_SELF_HOST`
+- `ASPOSE_STORAGE_NAME`
+
+## CLI
+
+The canonical executable is `apdf-cloud-cli`. A shorter `apdf`
+alias is also installed for convenience.
+
+```powershell
+apdf-cloud-cli storage list /
+apdf-cloud-cli storage upload .\sample.pdf /sample.pdf
+apdf-cloud-cli storage download /sample.pdf .\sample.pdf
+apdf-cloud-cli pdf merge /a.pdf /b.pdf merged.pdf
+apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
+apdf-cloud-cli mcp serve
+```
+
+## Development
+
+Install the package with development dependencies:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Run the default test suite:
+
+```powershell
+python -m pytest -q
+```
+
+Build and validate the package distributions:
+
+```powershell
+python -m build
+python -m twine check dist/*
+```
+
+## Publishing
+
+Publishing is handled by GitHub Actions with PyPI trusted publishing.
+
+1. In PyPI, add a trusted publisher for repository
+   `andruhovski/apdf-tools`, workflow `publish.yml`, environment `pypi`,
+   and project name `apdf-cloud-cli`.
+2. Update the version in `pyproject.toml` and
+   `src/apdf_cloud_cli/__init__.py`.
+3. Push a matching version tag, for example:
+
+```powershell
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## Stage 2 Roadmap
+
+- Split PDF files
+- Extract images from PDF files
+- Extract tables from PDF files
+

apdf_cloud_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+apdf_cloud_cli/__init__.py,sha256=WQvXqxmVCUsQsd_kiwbDwfUhQhQIxUIwW_cYHUK0QX0,84
+apdf_cloud_cli/cli.py,sha256=b5QGUryFsVUzJqBRIUtQab7_OEwI-qHXyWTeq-1jGQY,5562
+apdf_cloud_cli/client.py,sha256=F9W_GbdJvGAE747CtIcBZIjkvyDQq4WXrCOmqSHNJ-M,502
+apdf_cloud_cli/config.py,sha256=jh5GUZmZKOGjP-l01vRFDw32y79NGeR2oD51sKPGUN0,2225
+apdf_cloud_cli/mcp_server.py,sha256=f-E7WDElSOY3NyX_NQJt5BUxlM7wNV0sj8gekv-Qk-c,1940
+apdf_cloud_cli/operations.py,sha256=JdIu4Qbb9kwkcvvBHEyQXlDYO9VvexZPkOHzPbP5VkQ,6732
+apdf_cloud_cli/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+apdf_cloud_cli-0.1.0.dist-info/METADATA,sha256=0dZj3WYfU-e8exPMVVMfTLGl-T3HUgMNQIONJTuhVn4,2951
+apdf_cloud_cli-0.1.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+apdf_cloud_cli-0.1.0.dist-info/entry_points.txt,sha256=Tonz2NfAIqASp5YTh5g8OhWuI-RkaFS8Q9YG5jo3sOg,87
+apdf_cloud_cli-0.1.0.dist-info/RECORD,,

apdf_cloud_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.1
+Root-Is-Purelib: true
+Tag: py3-none-any

apdf_cloud_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+apdf=apdf_cloud_cli.cli:main
+apdf-cloud-cli=apdf_cloud_cli.cli:main
+