PyPDFForm 5.2.1__tar.gz → 5.2.3__tar.gz

{pypdfform-5.2.1 → pypdfform-5.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.2.1
+Version: 5.2.3
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -29,7 +29,7 @@ Requires-Dist: fonttools<5.0.0,>=4.63.0
 Requires-Dist: pikepdf<11.0.0,>=10.7.2
 Requires-Dist: pillow<13.0.0,>=12.2.0
 Requires-Dist: pypdf<7.0.0,>=6.12.2
-Requires-Dist: reportlab<5.0.0,>=4.5.1
+Requires-Dist: reportlab<6.0.0,>=4.5.1
 Provides-Extra: cli
 Requires-Dist: typer<1.0.0,>=0.26.1; extra == "cli"
 Requires-Dist: jsonschema<5.0.0,>=4.26.0; extra == "cli"
@@ -125,4 +125,10 @@ The official documentation can be found on [the GitHub page](https://chinapandam
 
 This project is maintained entirely in my spare time. If you like the project please consider starring the GitHub repository. It is the best way to keep me motivated and continue making the project better.
 
-[![Stargazers over time](https://starchart.cc/chinapandaman/PyPDFForm.svg?variant=adaptive)](https://starchart.cc/chinapandaman/PyPDFForm)
+<a href="https://www.star-history.com/?repos=chinapandaman%2FPyPDFForm&type=date&logscale=&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=chinapandaman/PyPDFForm&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=chinapandaman/PyPDFForm&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=chinapandaman/PyPDFForm&type=date&legend=top-left" />
+ </picture>
+</a>

{pypdfform-5.2.1 → pypdfform-5.2.3}/PyPDFForm/__init__.py

@@ -18,7 +18,7 @@ from Python code or from the command line.
 
 import logging
 
-__version__ = "5.2.1"
+__version__ = "5.2.3"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage

{pypdfform-5.2.1 → pypdfform-5.2.3}/PyPDFForm/cli/create.py

@@ -30,7 +30,10 @@ create_cli = typer.Typer(
 )
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Create a new blank PDF.",
+)
 def blank(
     ctx: typer.Context,
     output: REQUIRED_OUTPUT_PDF,
@@ -60,7 +63,23 @@ def blank(
         ),
     ] = None,
 ) -> None:
-    """Create a new blank PDF."""
+    """
+    Create a blank PDF with optional page size and page count.
+
+    The command builds a `BlankPage` using the supplied dimensions, duplicates
+    it when multiple pages are requested, wraps the result with the global CLI
+    options stored in `ctx.obj`, and writes the new PDF to the required output
+    path.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        output (Path): Output PDF path.
+        count (int, optional): Number of blank pages to create. Defaults to
+            None.
+        width (float, optional): Page width in points. Defaults to None.
+        height (float, optional): Page height in points. Defaults to None.
+    """
     params = {}
     if width is not None:
         params["width"] = width
@@ -74,7 +93,10 @@ def blank(
     PdfWrapper(obj, **ctx.obj).write(output)
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Extract pages from an existing PDF.",
+)
 def extract(
     ctx: typer.Context,
     pdf: INPUT_PDF,
@@ -98,7 +120,28 @@ def extract(
         ),
     ] = None,
 ) -> None:
-    """Extract pages from an existing PDF."""
+    """
+    Extract a page range from an existing PDF.
+
+    The command validates that the requested end page does not precede the
+    start page, converts the 1-based CLI page numbers into the slice expected
+    by `PdfWrapper.pages`, and writes the extracted pages to the required
+    output path.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        output (Path): Output PDF path.
+        start (int, optional): First page to extract, starting at 1. Defaults
+            to None.
+        end (int, optional): Last page to extract, starting at 1. Defaults to
+            None.
+
+    Raises:
+        typer.BadParameter: Raised when both page bounds are supplied and the
+            start page is after the end page.
+    """
     if start is not None and end is not None and start > end:
         message = "End page must be greater than or equal to start page."
         cli_bad_parameter(
@@ -109,7 +152,10 @@ def extract(
     PdfWrapper(str(pdf), **ctx.obj).pages[slice((start or 1) - 1, end)].write(output)
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Merge multiple PDFs into one.",
+)
 def merge(
     ctx: typer.Context,
     pdfs: Annotated[
@@ -125,18 +171,48 @@ def merge(
     ],
     output: REQUIRED_OUTPUT_PDF,
 ) -> None:
-    """Merge multiple PDFs into one."""
+    """
+    Merge input PDFs in the order provided on the command line.
+
+    Each path is loaded into a `PdfWrapper` with the global CLI options, passed
+    to `PdfArray`, merged into one document, and written to the required output
+    path.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdfs (list[Path]): Input PDF paths in merge order.
+        output (Path): Output PDF path.
+    """
     PdfArray([PdfWrapper(str(pdf), **ctx.obj) for pdf in pdfs]).merge().write(output)
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Add form fields to a PDF.",
+)
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
     data: Annotated[Path, json_file_option("JSON file with form field definitions.")],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
-    """Add form fields to a PDF."""
+    """
+    Add form fields described by grouped JSON definitions.
+
+    The command maps JSON groups such as `text`, `check`, and `signature` to
+    PyPDFForm field classes, validates the input file against the CLI field
+    schema, creates the corresponding field objects, and calls
+    `PdfWrapper.bulk_create_fields` before writing the modified PDF.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        data (Path): JSON file containing grouped form field definitions.
+        output (Path, optional): Output PDF path. If omitted, the input PDF is
+            overwritten. Defaults to None.
+    """
     field_map = {
         "text": Fields.TextField,
         "check": Fields.CheckBoxField,
@@ -157,14 +233,32 @@ def field(
     )
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Draw text, images, and shapes on a PDF.",
+)
 def raw(
     ctx: typer.Context,
     pdf: INPUT_PDF,
     data: Annotated[Path, json_file_option("JSON file with raw element definitions.")],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
-    """Draw text, images, and shapes on a PDF."""
+    """
+    Draw raw elements described by grouped JSON definitions.
+
+    The command maps JSON groups such as `text`, `image`, and `rectangle` to
+    raw element classes, validates the input file against the CLI raw element
+    schema, creates the corresponding drawable objects, and calls
+    `PdfWrapper.draw` before writing the modified PDF.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        data (Path): JSON file containing grouped raw element definitions.
+        output (Path, optional): Output PDF path. If omitted, the input PDF is
+            overwritten. Defaults to None.
+    """
     raw_element_map = {
         "text": RawElements.RawText,
         "image": RawElements.RawImage,
@@ -185,14 +279,32 @@ def raw(
     )
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Add annotations to a PDF.",
+)
 def annotation(
     ctx: typer.Context,
     pdf: INPUT_PDF,
     data: Annotated[Path, json_file_option("JSON file with annotation definitions.")],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
-    """Add annotations to a PDF."""
+    """
+    Add annotations described by grouped JSON definitions.
+
+    The command maps JSON groups such as `text`, `link`, and `highlight` to
+    annotation classes, validates the input file against the CLI annotation
+    schema, creates the corresponding annotation objects, and calls
+    `PdfWrapper.annotate` before writing the modified PDF.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        data (Path): JSON file containing grouped annotation definitions.
+        output (Path, optional): Output PDF path. If omitted, the input PDF is
+            overwritten. Defaults to None.
+    """
     annotation_map = {
         "text": Annotations.TextAnnotation,
         "link": Annotations.LinkAnnotation,
@@ -214,7 +326,10 @@ def annotation(
     )
 
 
-@create_cli.command(no_args_is_help=True)
+@create_cli.command(
+    no_args_is_help=True,
+    help="Add a coordinate grid to a PDF.",
+)
 def grid(
     ctx: typer.Context,
     pdf: INPUT_PDF,
@@ -259,7 +374,26 @@ def grid(
         ),
     ] = None,
 ) -> None:
-    """Add a coordinate grid to a PDF."""
+    """
+    Overlay a coordinate grid on an existing PDF.
+
+    The command collects optional RGB color components and margin values,
+    normalizes whole-number margins to integers for stable output, generates a
+    coordinate grid through `PdfWrapper.generate_coordinate_grid`, and writes
+    the result to the requested output path or back to the input file.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        output (Path, optional): Output PDF path. If omitted, the input PDF is
+            overwritten. Defaults to None.
+        red (float, optional): Grid red value from 0 to 1. Defaults to None.
+        green (float, optional): Grid green value from 0 to 1. Defaults to
+            None.
+        blue (float, optional): Grid blue value from 0 to 1. Defaults to None.
+        margin (float, optional): Grid margin in points. Defaults to None.
+    """
     params = {}
     if any(
         [

pypdfform-5.2.3/PyPDFForm/cli/inspect.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines CLI commands for inspecting PDF form information.
+
+It exposes the `inspect` command group, which prints JSON for form schemas,
+current form values, generated sample data, and field rectangle metadata.
+Each command wraps read-only `PdfWrapper` properties so users can inspect forms
+from the terminal without writing Python code.
+"""
+
+import json
+
+import typer
+
+from .. import PdfWrapper
+from .common import FIELD_NAME, INPUT_PDF, get_widget
+
+inspect_cli = typer.Typer(
+    context_settings={"help_option_names": ["--help", "-h"]}, no_args_is_help=True
+)
+
+
+@inspect_cli.command(
+    no_args_is_help=True,
+    help="Print the form schema as JSON.",
+)
+def schema(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """
+    Print the JSON schema for filling an existing PDF form.
+
+    The command loads the PDF with the global CLI options stored in `ctx.obj`,
+    reads `PdfWrapper.schema`, serializes it as JSON, and writes it to standard
+    output.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+    """
+    typer.echo(json.dumps(PdfWrapper(str(pdf), **ctx.obj).schema))
+
+
+@inspect_cli.command(
+    no_args_is_help=True,
+    help="Print current form data as JSON.",
+)
+def data(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """
+    Print the current field values from an existing PDF form.
+
+    The command loads the PDF with the global CLI options stored in `ctx.obj`,
+    reads `PdfWrapper.data`, serializes it as JSON, and writes it to standard
+    output.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+    """
+    typer.echo(json.dumps(PdfWrapper(str(pdf), **ctx.obj).data))
+
+
+@inspect_cli.command(
+    no_args_is_help=True,
+    help="Print sample fill data as JSON.",
+)
+def sample(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """
+    Print generated sample data for filling an existing PDF form.
+
+    The command loads the PDF with the global CLI options stored in `ctx.obj`,
+    reads `PdfWrapper.sample_data`, serializes it as JSON, and writes it to
+    standard output.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+    """
+    typer.echo(json.dumps(PdfWrapper(str(pdf), **ctx.obj).sample_data))
+
+
+@inspect_cli.command(
+    no_args_is_help=True,
+    help="Print a form field's location and size as JSON.",
+)
+def location(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    field: FIELD_NAME,
+) -> None:
+    """
+    Print geometry metadata for a single form field.
+
+    The command loads the PDF with the global CLI options stored in `ctx.obj`,
+    resolves the requested widget name, and prints a JSON object containing the
+    page number, x-coordinate, y-coordinate, width, and height.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        field (str): Form field name to inspect.
+
+    Raises:
+        typer.BadParameter: Raised when the requested field does not exist.
+    """
+    f = get_widget(PdfWrapper(str(pdf), **ctx.obj), field, "--field")
+
+    typer.echo(
+        json.dumps(
+            {
+                "page_number": f.page_number,
+                "x": f.x,
+                "y": f.y,
+                "width": f.width,
+                "height": f.height,
+            }
+        )
+    )

{pypdfform-5.2.1 → pypdfform-5.2.3}/PyPDFForm/cli/remove.py

@@ -18,14 +18,35 @@ remove_cli = typer.Typer(
 )
 
 
-@remove_cli.command(no_args_is_help=True)
+@remove_cli.command(
+    no_args_is_help=True,
+    help="Remove form fields from a PDF.",
+)
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
     fields: FIELD_NAMES,
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
-    """Remove form fields from a PDF."""
+    """
+    Remove one or more named form fields from an existing PDF.
+
+    The command loads the PDF with the global CLI options stored in `ctx.obj`,
+    validates each requested field name before changing the document, removes
+    the fields through `PdfWrapper.remove_fields`, and writes the modified PDF
+    to the requested output path or back to the input file.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF path.
+        fields (list[str]): Form field names to remove.
+        output (Path, optional): Output PDF path. If omitted, the input PDF is
+            overwritten. Defaults to None.
+
+    Raises:
+        typer.BadParameter: Raised when any requested field does not exist.
+    """
     obj = PdfWrapper(str(pdf), **ctx.obj)
     for field_name in fields:
         get_widget(obj, field_name, "--field")

{pypdfform-5.2.1 → pypdfform-5.2.3}/PyPDFForm/cli/root.py

@@ -117,7 +117,24 @@ def main(
         ),
     ] = False,
 ) -> None:
-    """Work with PDF forms from the command line."""
+    """
+    Initialize shared CLI options for the selected command.
+
+    Typer runs this callback before dispatching to a subcommand. The callback
+    stores global PDF handling options on `ctx.obj` so command groups can pass
+    a consistent set of keyword arguments to `PdfWrapper`.
+
+    Args:
+        ctx (typer.Context): Typer context for the current CLI invocation.
+        version (bool): Whether to print the package version and exit.
+        need_appearances (bool): Whether to ask PDF viewers to render form
+            field appearances.
+        generate_appearance_streams (bool): Whether to generate form field
+            appearance streams while handling PDFs.
+        preserve_metadata (bool): Whether to preserve input PDF metadata.
+        use_full_widget_name (bool): Whether widget lookups should use full
+            form field names.
+    """
     ctx.obj = {
         "need_appearances": need_appearances,
         "generate_appearance_streams": generate_appearance_streams,
@@ -126,7 +143,10 @@ def main(
     }
 
 
-@cli_app.command(no_args_is_help=True)
+@cli_app.command(
+    no_args_is_help=True,
+    help="Fill a PDF form with JSON data.",
+)
 def fill(
     ctx: typer.Context,
     pdf: INPUT_PDF,
@@ -137,7 +157,25 @@ def fill(
         typer.Option("--flatten", help="Flatten form fields after filling."),
     ] = None,
 ) -> None:
-    """Fill a PDF form with JSON data."""
+    """
+    Fill an existing PDF form from a validated JSON file.
+
+    The command loads the input PDF with the global options stored by the root
+    callback, expands the generated schema so image and signature widgets can
+    accept path objects, validates the JSON input, normalizes image and
+    signature values, and writes the filled PDF to the requested output path or
+    back to the input file.
+
+    Args:
+        ctx (typer.Context): Typer context containing global `PdfWrapper`
+            options in `ctx.obj`.
+        pdf (Path): Input PDF form path.
+        data (Path): JSON file containing form field values.
+        output (Path, optional): Output PDF path. If omitted, the input PDF is
+            overwritten. Defaults to None.
+        flatten (bool, optional): Whether to flatten form fields after filling.
+            Defaults to None.
+    """
     obj = PdfWrapper(str(pdf), **ctx.obj)
 
     schema = obj.schema