toon-to-pdf 0.1.0

A lightweight library to convert TOON format files to PDF using pdfme

TOON to PDF

A lightweight Python library that converts TOON format files to PDF documents using pdfme as the backend PDF generation engine.

Overview

TOON to PDF provides a simple, declarative way to create PDF documents using the TOON syntax. It acts as a wrapper around pdfme, allowing you to describe PDF structures in a human-readable TOON format and automatically generate professional PDF files.

Installation

Install the library using pip:

pip install toon-to-pdf

Dependencies

The library requires:

• pdfme - PDF generation engine

The TOON parser is built into the library, so no additional parsing dependencies are needed. The pdfme package will be automatically installed when you install toon-to-pdf.

Quick Start

Hello World Example

Create a simple TOON file (hello_world.toon):

(
  schemas: [
    (
      content: ( type: "text", text: "Hello World" )
      position: ( x: 50, y: 50 )
    )
  ]
  basePdf: "blank"
)

Generate the PDF:

from toon_to_pdf import generate_from_toon_file

generate_from_toon_file("hello_world.toon", "hello_world.pdf")

Or use a TOON string directly:

from toon_to_pdf import generate_from_toon

toon_content = """
(
  schemas: [
    (
      content: ( type: "text", text: "Hello World" )
      position: ( x: 50, y: 50 )
    )
  ]
  basePdf: "blank"
)
"""

generate_from_toon(toon_content, "output.pdf")

TOON Schema Design

The TOON schema is designed to map directly to pdfme's JSON structure. Here's how it works:

Basic Structure

Every TOON document must have:

• schemas: A list of content elements (text, images, tables, etc.)
• basePdf: The base PDF template (use "blank" for a blank page)

Text Elements

Each schema entry in the schemas list represents a content element with:

• content: The content definition (type, text, styling, etc.)
• position: The position on the page (x, y coordinates)

Example: Simple Invoice

(
  schemas: [
    (
      content: ( type: "text", text: "INVOICE", fontSize: 24, bold: true )
      position: ( x: 50, y: 50 )
    )
    (
      content: ( type: "text", text: "Invoice #: INV-001" )
      position: ( x: 50, y: 100 )
    )
    (
      content: ( type: "text", text: "Date: 2024-01-15" )
      position: ( x: 50, y: 130 )
    )
    (
      content: ( type: "text", text: "Total: $100.00", fontSize: 16, bold: true )
      position: ( x: 50, y: 250 )
    )
  ]
  basePdf: "blank"
)

API Reference

generate_from_toon(toon_input: str, output_path: Union[str, Path]) -> None

Generate a PDF file from a TOON format string.

Parameters:

• toon_input: TOON format string describing the PDF structure
• output_path: Path where the generated PDF file will be saved

Raises:

• ImportError: If required dependencies are not installed
• ValueError: If the TOON input cannot be parsed or is invalid
• IOError: If the output file cannot be written

Example:

from toon_to_pdf import generate_from_toon

toon_content = """
(
  schemas: [
    (
      content: ( type: "text", text: "Hello World" )
      position: ( x: 50, y: 50 )
    )
  ]
  basePdf: "blank"
)
"""

generate_from_toon(toon_content, "output.pdf")

generate_from_toon_file(toon_file_path: Union[str, Path], output_path: Union[str, Path]) -> None

Generate a PDF file from a TOON format file.

Parameters:

• toon_file_path: Path to the input TOON file
• output_path: Path where the generated PDF file will be saved

Raises:

• FileNotFoundError: If the TOON file does not exist
• ValueError: If the TOON input cannot be parsed or is invalid
• IOError: If the output file cannot be written

Example:

from toon_to_pdf import generate_from_toon_file

generate_from_toon_file("document.toon", "document.pdf")

How It Works

The library performs a simple three-step process:

1. Parse: Converts the TOON input string into a Python dictionary using the python-toon parser
2. Transform: Validates and normalizes the data structure to match pdfme's expected format
3. Generate: Creates the PDF file using pdfme's build_pdf function

Mapping to pdfme Format

The TOON schema directly maps to pdfme's JSON structure:

pdfme JSON:

{
  "schemas": [{
    "content": { "type": "text", "text": "Hello World" },
    "position": { "x": 50, "y": 50 }
  }],
  "basePdf": "blank"
}

Equivalent TOON:

(
  schemas: [
    (
      content: ( type: "text", text: "Hello World" )
      position: ( x: 50, y: 50 )
    )
  ]
  basePdf: "blank"
)

Examples

Check the examples/ directory for more examples:

• hello_world.toon - Basic "Hello World" example
• simple_invoice.toon - A simple invoice document

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/toon-to-pdf.git
cd toon-to-pdf

# Install in development mode
pip install -e ".[dev]"

Running Tests

pytest

Future Enhancements

• Support for more pdfme features (tables, images, etc.)
• Convenience functions for common PDF patterns
• JavaScript/Node.js version using pdfmake
• CLI tool for command-line usage
• Advanced transformation features

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

• pdfme - The PDF generation engine
• python-toon - The TOON parser

Support

For issues, questions, or contributions, please visit the GitHub repository.