Aspose.Page FOSS for Python

Aspose.Page FOSS for Python is a free, open-source, MIT-licensed, pure-Python library for working with PostScript, Encapsulated PostScript (EPS), and XPS documents. It reads and authors PS/EPS and XPS content directly, builds page content programmatically through its own render model, and writes PDF or raster (PNG, JPEG, BMP, TIFF) output without Ghostscript or Adobe tooling. Raster output uses the free skia-python package, which has native components. The same conversions are also exposed as MCP tools for LLM-agent and automation workflows.

Navigation

• At a Glance
• Key Capabilities
• Installation
• Dependencies
• Quick Start
• Additional Examples
• API Reference
• Documentation & Resources
• Scope and Limitations
• Development and Testing
• License

At a Glance

flowchart TD
  subgraph StartingPoints["Starting Points"]
    direction LR
    i1["An existing EPS or XPS document (.ps, .eps, and .xps files)"]
    i2["Nothing — authored from scratch"]
  end
  PRODUCT["Aspose.Page FOSS for Python"]
  subgraph Capabilities["Core Capabilities"]
    direction LR
    subgraph capl[" "]
      direction TB
      c1["Read PS and EPS documents (PsDocument)"]
      c2["Read XPS packages (XpsDocument)"]
      c3["Author PS, EPS, and XPS documents from scratch (PsDocument.create, XpsDocument.create)"]
    end
    subgraph capr[" "]
      direction TB
      c4["Build the render model (RenderModelBuilder)"]
      c5["Write PDF and raster output (PdfWriter, RasterRenderer)"]
      c6["MCP server tools for automated conversion"]
    end
  end
  subgraph Outputs["Outputs"]
    direction TB
    o1["PDF documents"]
    o2["PNG, JPEG, BMP, and TIFF images"]
  end
  StartingPoints --> PRODUCT --> Capabilities --> Outputs

Key Capabilities

• Read and parse PS/EPS documents with PsDocument.from_file() / from_bytes(), backed by a full PostScript interpreter (PsInterpreter, PsParser, PsTokenizer, OperatorRegistry) and DSC/EPS metadata extraction (DscMetadata).
• Read XPS packages with XpsDocument.from_file() / from_bytes(), walking fixed pages and print tickets through XpsParser, XpsPackage, and XpsRenderer.
• Create and edit PS/EPS and XPS documents from scratch with PsDocument.create() / XpsDocument.create(), drawing through PsCanvas (move_to, line_to, curve_to, stroke, fill, draw_text, draw_image) or the XpsDocumentBuilder page API, then save() back to the source format.
• Build page content programmatically with RenderModelBuilder — paths, text, images, and a clip/state stack — independent of any PS/XPS input, producing a RenderDocument.
• Write PDF 1.4 output with PdfWriter, including TrueType/Type1 font embedding resolved through FontResolver and FontCache.
• Rasterize PS/EPS content to PNG, JPEG, BMP, or TIFF with RasterRenderer; the Skia backend (skia-python) is used automatically when installed for speed, with a transparent pure-Python fallback (DefaultRasterWriter) when it isn't. XPS-to-image conversion has no such fallback — skia-python is a hard requirement there (see Scope and Limitations).
• Expose every conversion as an MCP tool (ps_to_pdf, ps_to_image, xps_to_pdf, xps_to_image, eps_metadata) through create_server(), for FastMCP-based automation.

Installation

To build and verify a wheel from a clone of the repository, install uv, setuptools, and wheel, then run:

git clone https://github.com/aspose-page-foss/Aspose.Page-FOSS-for-Python.git
cd Aspose.Page-FOSS-for-Python
python package.py build
python package.py verify

The wheel version comes from local/Version.txt. verify installs it with all dependencies in .package-venv and tests PS/XPS to PDF/PNG conversion. To upload the built wheel, use python package.py publish-test for TestPyPI or python package.py publish for PyPI; these commands read credentials from the matching files in local/.

The library targets Python 3.10+ (pyproject.toml's requires-python = ">=3.10"). See Dependencies below for the full required/optional/native breakdown.

Dependencies

Required Package Dependencies

skia-python is required and installed automatically with the wheel.

Optional Dependencies

• fastmcp — required to host the MCP server (create_server() / run()); imported lazily, only when the server is started.

Native and System Requirements

• Python 3.10 or later (pyproject.toml's requires-python = ">=3.10").

Development Dependencies

• pypdf, pypdfium2, and Pillow — required only when running the project's tests (see Development and Testing).

Quick Start

Convert a PS file to PDF through the MCP handler function:

from aspose.page.mcp.handlers import ps_to_pdf
from aspose.page.mcp.types import McpInput, McpOutput

result = ps_to_pdf(
    McpInput(input_path="input.ps", input_bytes_b64=None),
    McpOutput(output_path="output.pdf", return_bytes=False),
)

Convert a PS or EPS file to a raster image directly through the document API:

from aspose.page.ps.document import PsDocument
from aspose.page.ps.output import ImageSaveOptions

ps = PsDocument.from_file("input.ps")
data = ps.to_image(ImageSaveOptions(format="png", dpi=150))

with open("output.png", "wb") as f:
    f.write(data)

Additional Examples

Build a PDF Directly From the Render Model

No PS/XPS input is required — pages can be constructed entirely in code and written straight to PDF. Import aspose.page.ps first, before any other aspose.page submodule, to avoid a circular-import error in a fresh interpreter:

import aspose.page.ps  # works around a module import-order issue in aspose.page.pdf.writer
from aspose.page.common.render_model import RenderModelBuilder, Matrix
from aspose.page.pdf.writer import PdfWriter, PdfMetadata

builder = RenderModelBuilder()
builder.begin_page(100, 100)
builder.add_text("Hello, Aspose.Page", "Helvetica", 12, Matrix.identity(), None)
builder.end_page()
doc = builder.document()

metadata = PdfMetadata(
    title="", creator="", producer="Aspose.Page FOSS for Python",
    creation_date="D:20260101000000", mod_date="D:20260101000000", trapped=False,
)
writer = PdfWriter(metadata)
pdf_bytes = writer.write(doc)

from aspose.page.mcp.handlers import eps_metadata
from aspose.page.mcp.types import McpInput

meta = eps_metadata(McpInput(input_path="input.eps", input_bytes_b64=None))
print(meta["bounding_box"], meta["title"])

from aspose.page.mcp.handlers import xps_to_pdf
from aspose.page.mcp.types import McpInput, McpOutput

result = xps_to_pdf(
    McpInput(input_path="input.xps", input_bytes_b64=None),
    McpOutput(output_path="output.pdf", return_bytes=False),
)

import aspose.page.ps  # works around a module import-order issue in aspose.page.image.raster_renderer
from aspose.page.common.render_model import RenderDocument, RenderPage
from aspose.page.image.raster_renderer import RasterRenderer
from aspose.page.image.encoders import encode_png

doc = RenderDocument()
doc.pages.append(RenderPage(width=200, height=100))

surface = RasterRenderer(dpi=144).render(doc)
png_bytes = encode_png(surface, dpi=144)

with open("blank.png", "wb") as f:
    f.write(png_bytes)

from aspose.page.xps.document import XpsDocument
from aspose.page.ps.output import ImageSaveOptions

doc = XpsDocument.from_file("input.xps")
data = doc.to_image(ImageSaveOptions(format="png", dpi=150))

with open("output.png", "wb") as f:
    f.write(data)

from aspose.page.mcp import create_server

server = create_server()
server.run(host="127.0.0.1", port=8000)

API Reference

The primary entry points are PsDocument and XpsDocument, which read, author, and convert PS/EPS and XPS content respectively; both delegate PDF output to PdfWriter and raster output to RasterRenderer, once page content has passed through the shared RenderModelBuilder / RenderDocument model. The public API surface includes 139 types, organized by module below.

Documentation & Resources

• Getting started guide — installation, walkthroughs, and feature guides for this library.
• How-to guides & FAQ — task-focused answers for common PS/EPS/XPS-processing questions.
• Full API reference — the complete, browsable reference for all 139 public types.
• Found a bug or have a feature request? Open an issue on GitHub.

Scope and Limitations

• This library converts and authors documents; it does not read existing PDF files (there is no PDF import/parsing API).
• PS/EPS raster output falls back to a pure-Python renderer when skia-python isn't installed — a performance difference, not a functional gap. XPS-to-image conversion has no such fallback: skia-python must be installed, or it raises a runtime error.
• Importing aspose.page.pdf.writer or aspose.page.image.raster_renderer directly, or calling XpsDocument.to_pdf() / to_image(), before anything has imported aspose.page.ps raises a circular-import ImportError in a fresh Python interpreter — a structural property of the package's own module graph. Import aspose.page.ps first, as the Additional Examples above do, to avoid it; converting a PS/EPS document directly, and every MCP handler, already do this internally and never need the workaround.
• Font embedding resolves TrueType/Type1 glyphs from an explicit additional_fonts_folder path via FontResolver / FontCache; there is no automatic system-font-directory discovery.
• The MCP server exposes the five conversion/metadata tools (ps_to_pdf, ps_to_image, xps_to_pdf, xps_to_image, eps_metadata) only — document creation/authoring (PsDocument.create, XpsDocument.create) is available through the direct Python API, not as an MCP tool.

These limitations don't apply to Aspose.Page — Enterprise Edition, which adds broader format coverage, including PDF reading, and commercial support.

Development and Testing

Sync dependencies and run the test suite with uv:

make sync
make test

make test runs python3 -m unittest discover -s tests (see Makefile); make build produces wheel and sdist artifacts, and make check runs both test and build.

python3 -m unittest tests.mcp.test_handlers tests.mcp.test_server

make build

License

This project is licensed under the MIT License. The MIT License permits use, copying, modification, distribution, sublicensing, and commercial use, provided its copyright and permission notice are retained. The software is provided without warranty.