Improve examples

- All examples should now put their output near the script itself
  instead of cwd.
- Added `run_samples` scripts for quickly running all the samples in
  one go. Useful for quick testing.
- Added additional explanatory READMEs.
- Added an explicit `openai` check in the ToC example.

Author: Eswcvlad

README.md

@@ -52,6 +52,8 @@ document.Add(Paragraph("Hello, World!"))
 document.Close()
 ```
 
+More source code examples are available in the [samples](./samples) directory.
+
 # Limitations
 
 * .NET Core SDK is required for building.
@@ -73,4 +75,4 @@ document.Close()
 * Current 9.1.0 build contains a bug, which prevents running iText with .NET
   Core under Python.NET. For now, we have a workaround here with a binary 
   patch. Patching is done with the `scripts/patch_itext_binaries.py` script.
-  So the `itext.io.dll` binary is not the same, as the one from NuGet.
+  So don't worry, if the `itext.io.dll` binary differs from the one from NuGet.

samples/README.md

@@ -0,0 +1,25 @@
+This directory contains examples on how to use the iText library within a
+Python.NET environment. The Python scripts themselves are located in the
+`sandbox` directory.
+
+Files, which start with an `_` are common "library" files and should not be
+run directly. Every other Python file is a separate example, which can be
+run on its own. Examples will put their output next to the Python scripts
+themselves with the same base name.
+
+For example, to run the `paragraph_text_with_style` sample, make sure the
+`python` environment you are using has the `itextpy` package installed and
+run this command in the terminal:
+
+```shell
+python layout/paragraph_text_with_style.py
+```
+
+This will create a PDF file at `layout/paragraph_text_with_style.pdf`, where
+you can check the results.
+
+To run all the available samples, use the `run_samples.ps1` script on Windows
+and the `run_samples.sh` script on *nix.
+
+Most of the samples are based on the .NET iText samples, which can be found at
+[itext-publications-samples-dotnet](https://github.com/itext/itext-publications-samples-dotnet).

samples/run_samples.ps1

@@ -0,0 +1,4 @@
+Get-ChildItem -Path $PSScriptRoot\sandbox\ -File -Filter "*.py" -Exclude "_*" -Recurse | ForEach-Object {
+    Write-Output "Running $($_.Directory.Name)/$($_.Name)..."
+    python $_.FullName
+}

samples/run_samples.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
+shopt -s globstar
+for f in "$SCRIPT_DIR"/**/[^_]*.py; do
+    echo "Processing $(basename "$(dirname "$f")")/$(basename "$f")..."
+    python "$f"
+done

samples/sandbox/acroforms/create_form_field_through_layout.py

@@ -3,13 +3,17 @@
 
 from itextpy.util import disposing
 
+from pathlib import Path
+
 from iText.Forms.Form.Element import Button, InputField, Radio, TextArea
 from iText.Kernel.Colors import ColorConstants
 from iText.Kernel.Pdf import PdfWriter, PdfDocument
 from iText.Layout import Document
 from iText.Layout.Borders import SolidBorder
 from iText.Layout.Element import Cell, Paragraph, Table
 
+SCRIPT_DIR = Path(__file__).parent.absolute()
+
 
 def manipulate_pdf(dest):
     with disposing(Document(PdfDocument(PdfWriter(dest)))) as document:
@@ -62,4 +66,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("create_form_field_through_layout.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "create_form_field_through_layout.pdf"))

samples/sandbox/ai/README.md

@@ -0,0 +1,6 @@
+The `table_of_contents.py` example requires additional Python packages, which
+are listed in `requirements.txt`. Additionally, you need to have a local
+Ollama instance running with a `Qwen2.5` model pre-pulled.
+
+For further information on how to setup the environment or customize the LLM
+environment used, check the comments in the `table_of_contents.py` script.

samples/sandbox/ai/table_of_contents.py

@@ -10,6 +10,8 @@
 # The default Ollama context window is small, so make sure to change it using
 # the instructions below.
 #
+import sys
+
 import itextpy
 itextpy.load()
 
@@ -18,8 +20,6 @@
 from pathlib import Path
 from sys import stderr
 
-from openai import OpenAI
-
 from iText.Kernel.Geom import PageSize
 from iText.Kernel.Pdf.Canvas.Parser import PdfTextExtractor
 from iText.Kernel.Pdf.Canvas.Parser.Listener import LocationTextExtractionStrategy
@@ -138,6 +138,13 @@ def add_page_data(toc_data: TableEntry, pages: list[str]) -> None:
 # This function ask the LLM to generate the table of contents for the provided
 # pages of text. The result gets parsed into a tree-like structure.
 def generate_toc_data(pages: list[str]) -> TableEntry:
+    try:
+        from openai import OpenAI
+    except ImportError:
+        print('ai/table_of_contents.py sample requires openai package, '
+              'skipping...', file=sys.stderr)
+        sys.exit()
+
     openai_client = OpenAI(
         base_url=OPENAI_BASE_URL,
         api_key=OPENAI_API_KEY,
@@ -238,4 +245,4 @@ def main(in_path: str, out_path: str) -> None:
 
 
 # Call the function to create a PDF
-main(INPUT_PDF_PATH, "table_of_contents.pdf")
+main(INPUT_PDF_PATH, str(SCRIPT_DIR / "table_of_contents.pdf"))

samples/sandbox/annotations/add_link_annotation_5.py

@@ -36,4 +36,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("add_link_annotation_5.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "add_link_annotation_5.pdf"))

samples/sandbox/annotations/move_popup.py

@@ -39,4 +39,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("move_popup.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "move_popup.pdf"))

samples/sandbox/events/page_rotation.py

@@ -57,4 +57,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("page_rotation.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "page_rotation.pdf"))

samples/sandbox/events/text_footer.py

@@ -73,4 +73,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("text_footer.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "text_footer.pdf"))

samples/sandbox/events/watermarking.py

@@ -83,4 +83,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("watermarking.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "watermarking.pdf"))

samples/sandbox/images/multiple_images.py

@@ -33,4 +33,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("multiple_images.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "multiple_images.pdf"))

samples/sandbox/layout/page_size_and_margins.py

@@ -3,11 +3,15 @@
 
 from itextpy.util import disposing
 
+from pathlib import Path
+
 from iText.Kernel.Geom import PageSize
 from iText.Kernel.Pdf import PdfWriter, PdfDocument
 from iText.Layout import Document
 from iText.Layout.Element import AreaBreak, Paragraph
 
+SCRIPT_DIR = Path(__file__).parent.absolute()
+
 
 def manipulate_pdf(dest):
     page_size = PageSize(200, 200)
@@ -40,4 +44,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("page_size_and_margins.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "page_size_and_margins.pdf"))

samples/sandbox/layout/paragraph_text_with_style.py

@@ -3,13 +3,17 @@
 
 from itextpy.util import disposing
 
+from pathlib import Path
+
 from iText.IO.Font.Constants import StandardFonts
 from iText.Kernel.Colors import ColorConstants
 from iText.Kernel.Font import PdfFontFactory
 from iText.Kernel.Pdf import PdfWriter, PdfDocument
 from iText.Layout import Style, Document
 from iText.Layout.Element import Paragraph, Text
 
+SCRIPT_DIR = Path(__file__).parent.absolute()
+
 
 def manipulate_pdf(dest):
     code = PdfFontFactory.CreateFont(StandardFonts.COURIER)
@@ -32,4 +36,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("paragraph_text_with_style.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "paragraph_text_with_style.pdf"))

samples/sandbox/merge/add_cover_1.py

@@ -24,4 +24,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("add_cover_1.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "add_cover_1.pdf"))

samples/sandbox/objects/nested_lists.py

@@ -3,10 +3,14 @@
 
 from itextpy.util import disposing
 
+from pathlib import Path
+
 from iText.Kernel.Pdf import PdfWriter, PdfDocument
 from iText.Layout import Document
 from iText.Layout.Element import List, ListItem, Paragraph
 
+SCRIPT_DIR = Path(__file__).parent.absolute()
+
 
 def manipulate_pdf(dest):
     with disposing(Document(PdfDocument(PdfWriter(dest)))) as document:
@@ -31,4 +35,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("nested_lists.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "nested_lists.pdf"))

samples/sandbox/pdfa/pdf_a3.py

@@ -70,4 +70,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("pdf_a3.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "pdf_a3.pdf"))

samples/sandbox/pdfa/pdf_a4.py

@@ -38,4 +38,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("pdf_a4.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "pdf_a4.pdf"))

samples/sandbox/pdfhtml/colorblindness.py renamed to samples/sandbox/pdfhtml/_colorblindness.py

@@ -29,6 +29,6 @@ def manipulate_pdf(html_source, pdf_dest, resource_loc):
 if __name__ == "__main__":
     manipulate_pdf(
         html_source=str(SRC_DIR / "rainbow.html"),
-        pdf_dest="parse_html_as_print.pdf",
+        pdf_dest=str(SCRIPT_DIR / "parse_html_as_print.pdf"),
         resource_loc=str(SRC_DIR),
     )

samples/sandbox/pdfhtml/qr_code_tag.py renamed to samples/sandbox/pdfhtml/_qr_code_tag.py

@@ -8,7 +8,7 @@
 from System.IO import FileAccess, FileMode, FileShare, FileStream
 from iText.Html2pdf import ConverterProperties, HtmlConverter
 
-from colorblindness import ColorBlindnessCssApplierFactory, ColorBlindnessTransforms
+from _colorblindness import ColorBlindnessCssApplierFactory, ColorBlindnessTransforms
 
 SCRIPT_DIR = Path(__file__).parent.absolute()
 RESOURCES_DIR = SCRIPT_DIR / ".." / ".." / "resources"
@@ -34,6 +34,6 @@ def manipulate_pdf(html_source, pdf_dest, resource_loc):
 if __name__ == "__main__":
     manipulate_pdf(
         html_source=str(SRC_DIR / "rainbow.html"),
-        pdf_dest="parse_html_color_blind.pdf",
+        pdf_dest=str(SCRIPT_DIR / "parse_html_color_blind.pdf"),
         resource_loc=str(SRC_DIR),
     )

samples/sandbox/pdfhtml/parse_html_as_print.py

@@ -8,7 +8,7 @@
 from System.IO import FileAccess, FileMode, FileStream
 from iText.Html2pdf import ConverterProperties, HtmlConverter
 
-from qr_code_tag import QRCodeTagCssApplierFactory, QRCodeTagWorkerFactory
+from _qr_code_tag import QRCodeTagCssApplierFactory, QRCodeTagWorkerFactory
 
 SCRIPT_DIR = Path(__file__).parent.absolute()
 RESOURCES_DIR = SCRIPT_DIR / ".." / ".." / "resources"
@@ -39,6 +39,6 @@ def manipulate_pdf(html_source, pdf_dest, resource_loc):
 if __name__ == "__main__":
     manipulate_pdf(
         html_source=str(SRC_DIR / "qrcode.html"),
-        pdf_dest="parse_html_qr_code.pdf",
+        pdf_dest=str(SCRIPT_DIR / "parse_html_qr_code.pdf"),
         resource_loc=str(SRC_DIR),
     )

samples/sandbox/pdfhtml/parse_html_color_blind.py

@@ -23,6 +23,6 @@ def manipulate_pdf(html_source, pdf_dest, resource_loc):
 if __name__ == "__main__":
     manipulate_pdf(
         html_source=str(SRC_DIR / "rainbow.html"),
-        pdf_dest="parse_html_simple.pdf",
+        pdf_dest=str(SCRIPT_DIR / "parse_html_simple.pdf"),
         resource_loc=str(SRC_DIR),
     )

samples/sandbox/pdfhtml/parse_html_qr_code.py

@@ -47,5 +47,5 @@ def manipulate_pdf(html_source, pdf_dest):
 if __name__ == "__main__":
     manipulate_pdf(
         html_source=str(SRC_DIR / "FontExample.html"),
-        pdf_dest="using_custom_fonts.pdf",
+        pdf_dest=str(SCRIPT_DIR / "using_custom_fonts.pdf"),
     )

samples/sandbox/pdfhtml/parse_html_simple.py

@@ -163,4 +163,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("pdf_ua.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "pdf_ua.pdf"))

samples/sandbox/pdfhtml/using_custom_fonts.py

@@ -49,7 +49,7 @@ def __init__(self, element: IElementNode, context: ProcessorContext):
 
     def GetElementResult(self) -> IPropertyContainer:
         # FIXME: For some reason super().GetElementResult() doesn't work.
-        #        It just call this method again, causing infinite recursion.
+        #        It just calls this method again, causing infinite recursion.
         element_result = HTagWorker.GetElementResult(self)
         # Duck typing does not really work for .NET types...
         result = clr_try_cast(element_result, Div)
@@ -96,4 +96,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("wtpdf.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "wtpdf.pdf"))

samples/sandbox/pdfua/pdf_ua.py

@@ -3,7 +3,7 @@
 
 from typing import Self
 
-from utils import TestOcspResponseBuilder
+from _utils import TestOcspResponseBuilder
 
 from System.Collections.Generic import Dictionary
 from iText.Bouncycastleconnector import BouncyCastleFactoryCreator

samples/sandbox/pdfua/wtpdf.py

@@ -23,15 +23,14 @@
 from pathlib import Path
 import sys
 
-from utils import PemFileHelper
+from _utils import PemFileHelper
 
 from System.IO import FileMode, FileStream
 from iText.Kernel.Crypto import DigestAlgorithms
 from iText.Kernel.Pdf import PdfReader, StampingProperties
 from iText.Signatures import PdfSigner, PrivateKeySignature
 from Org.BouncyCastle.Crypto import CryptoServicesRegistrar
 
-
 SCRIPT_DIR = Path(__file__).parent.absolute()
 RESOURCES_DIR = SCRIPT_DIR / ".." / ".." / "resources"
 SRC_PATH = str(RESOURCES_DIR / "pdfs" / "signExample.pdf")
@@ -57,4 +56,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("fips.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "fips.pdf"))

samples/sandbox/signatures/clients.py renamed to samples/sandbox/signatures/_clients.py

@@ -84,4 +84,4 @@ def manipulate_pdf(dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("signature_example.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "signature_example.pdf"))

samples/sandbox/signatures/utils.py renamed to samples/sandbox/signatures/_utils.py

@@ -5,8 +5,8 @@
 
 from pathlib import Path
 
-from utils import PemFileHelper, TestOcspResponseBuilder
-from clients import TestOcspClient
+from _utils import PemFileHelper, TestOcspResponseBuilder
+from _clients import TestOcspClient
 
 from System import Func
 from System.Collections.Generic import List
@@ -99,5 +99,5 @@ def manipulate_pdf(src, dest):
 if __name__ == "__main__":
     manipulate_pdf(
         str(RESOURCES_DIR / "pdfs" / "hello.pdf"),
-        "validate_chain_before_signing_example.txt",
+        str(SCRIPT_DIR / "validate_chain_before_signing_example.txt"),
     )

samples/sandbox/signatures/fips.py

@@ -37,4 +37,4 @@ def manipulate_pdf(pdf_dest):
 
 
 if __name__ == "__main__":
-    manipulate_pdf("convert_svg_string_to_pdf.pdf")
+    manipulate_pdf(str(SCRIPT_DIR / "convert_svg_string_to_pdf.pdf"))

samples/sandbox/signatures/signature_example.py

@@ -40,5 +40,5 @@ def manipulate_pdf(svg_source, pdf_dest):
 if __name__ == "__main__":
     manipulate_pdf(
         svg_source=str(SVG_RESOURCES_DIR / "cauldron.svg"),
-        pdf_dest="convert_svg_to_layout_image.pdf",
+        pdf_dest=str(SCRIPT_DIR / "convert_svg_to_layout_image.pdf"),
     )

samples/sandbox/signatures/validate_chain_before_signing_example.py

@@ -18,5 +18,5 @@ def manipulate_pdf(svg_source, pdf_dest):
 if __name__ == "__main__":
     manipulate_pdf(
         svg_source=str(SVG_RESOURCES_DIR / "cauldron.svg"),
-        pdf_dest="convert_svg_to_pdf.pdf",
+        pdf_dest=str(SCRIPT_DIR / "convert_svg_to_pdf.pdf"),
     )