PyPDFForm 5.2.5__tar.gz → 5.3.0__tar.gz

{pypdfform-5.2.5 → pypdfform-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.2.5
+Version: 5.3.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -33,6 +33,7 @@ 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"
+Requires-Dist: PyYAML<7.0.0,>=6.0.3; extra == "cli"
 Provides-Extra: dev
 Requires-Dist: coverage<8.0.0,>=7.14.1; extra == "dev"
 Requires-Dist: mike<3.0.0,>=2.2.0; extra == "dev"

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm/__init__.py

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

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm/cli/common.py

@@ -2,8 +2,8 @@
 """
 This module provides shared helpers for PyPDFForm CLI commands.
 
-It contains utilities for loading JSON command input, registering custom fonts
-once per command invocation, and converting grouped JSON element definitions
+It contains utilities for loading structured command input, registering custom
+fonts once per command invocation, and converting grouped element definitions
 into the objects expected by `PdfWrapper` methods.
 """
 
@@ -12,6 +12,7 @@ from pathlib import Path
 from typing import Annotated, Any, NoReturn
 
 import typer
+import yaml
 from jsonschema import ValidationError, validate
 
 from .. import PdfWrapper
@@ -62,15 +63,15 @@ FIELD_NAMES = Annotated[
 ]
 
 
-def json_file_option(help_text: str):
+def data_file_option(help_text: str):
     """
-    Creates the common validated JSON file option.
+    Creates the common validated structured data file option.
 
     Args:
         help_text (str): Help text to display for the option.
 
     Returns:
-        typer.Option: A configured `--file` / `-f` option for JSON file input.
+        typer.Option: A configured `--file` / `-f` option for file input.
     """
     return typer.Option(
         "--file",
@@ -109,7 +110,7 @@ def cli_bad_parameter(
 
 def _validation_error_path(exc: ValidationError) -> str:
     """
-    Builds a dotted JSON path for a validation error.
+    Builds a dotted input data path for a validation error.
 
     Args:
         exc (ValidationError): The JSON schema validation error.
@@ -120,28 +121,45 @@ def _validation_error_path(exc: ValidationError) -> str:
     return ".".join(str(each) for each in exc.absolute_path)
 
 
-def load_json_file(data: Path, schema: dict, param_hint: str) -> Any:
+def _input_file_kind(data: Path) -> str:
     """
-    Loads a JSON CLI input file and validates it against a schema.
+    Gets the structured data format to use for a CLI input file.
 
     Args:
-        data (Path): JSON file path.
+        data (Path): Input file path.
+
+    Returns:
+        str: The upper-case format name for user-facing messages.
+    """
+    if data.suffix.lower() in {".yaml", ".yml"}:
+        return "YAML"
+
+    return "JSON"
+
+
+def load_data_file(data: Path, schema: dict, param_hint: str) -> Any:
+    """
+    Loads a YAML or JSON CLI input file and validates it against a schema.
+
+    Args:
+        data (Path): YAML or JSON file path.
         schema (dict): JSON schema to validate against.
-        param_hint (str): CLI parameter associated with the JSON file.
+        param_hint (str): CLI parameter associated with the input file.
 
     Returns:
-        Any: Parsed and validated JSON input.
+        Any: Parsed and validated input data.
 
     Raises:
         typer.BadParameter: Raised when the file cannot be loaded or validation
             fails.
     """
+    input_kind = _input_file_kind(data)
     try:
         with open(data, "r", encoding="utf-8") as f:
-            input_data = json.load(f)
-    except (OSError, json.JSONDecodeError) as exc:
+            input_data = yaml.safe_load(f) if input_kind == "YAML" else json.load(f)
+    except (OSError, json.JSONDecodeError, yaml.YAMLError) as exc:
         cli_bad_parameter(
-            f"Invalid JSON file: {exc}",
+            f"Invalid {input_kind} file: {exc}",
             param_hint=param_hint,
             cause=exc,
         )
@@ -152,7 +170,7 @@ def load_json_file(data: Path, schema: dict, param_hint: str) -> Any:
         error_path = _validation_error_path(exc)
         location = f" at {error_path}" if error_path else ""
         cli_bad_parameter(
-            f"Invalid JSON file{location}: {exc.message}",
+            f"Invalid {input_kind} file{location}: {exc.message}",
             param_hint=param_hint,
             cause=exc,
         )
@@ -191,15 +209,15 @@ def handle_font_registration(
     """
     Registers a custom font referenced by CLI input.
 
-    CLI JSON files may provide a file path in a `font` parameter. This helper
+    CLI input files may provide a file path in a `font` parameter. This helper
     registers each unique font path on the supplied `PdfWrapper` once, assigns
     it a generated internal font name, and mutates `params["font"]` to that
     registered name so downstream field or element constructors can use it.
 
     Args:
         obj (PdfWrapper): The wrapper for the PDF currently being modified.
-        params (dict): The element or widget parameters loaded from JSON. This
-            dictionary is mutated when it contains a `font` key.
+        params (dict): The element or widget parameters loaded from the input
+            file. This dictionary is mutated when it contains a `font` key.
         registered_font (dict): Mapping of source font paths to generated
             `PdfWrapper` font names for the current command invocation.
     """
@@ -222,9 +240,9 @@ def create_elements_from_file(
     output: Path | None = None,
 ) -> None:
     """
-    Creates PDF elements from grouped JSON definitions.
+    Creates PDF elements from grouped file definitions.
 
-    The input JSON is expected to group element definitions by type, such as
+    The input data is expected to group element definitions by type, such as
     `text`, `image`, or `highlight`. Each group key is resolved through
     `element_map`, each item is constructed after optional font registration,
     and the resulting objects are passed to `method_name` on `PdfWrapper`.
@@ -232,21 +250,21 @@ def create_elements_from_file(
 
     Args:
         pdf (Path): The path to the input PDF file.
-        data (Path): The path to the JSON file containing grouped element
+        data (Path): The path to the input file containing grouped element
             definitions.
-        element_map (dict): Mapping from JSON group names to element classes or
-            callables used to construct each object.
+        element_map (dict): Mapping from input group names to element classes
+            or callables used to construct each object.
         schema (dict): JSON schema used to validate the grouped definitions.
         method_name (str): Name of the `PdfWrapper` method that accepts the
             constructed elements, such as `bulk_create_fields`, `draw`, or
             `annotate`.
         ctx (typer.Context): Typer context containing global wrapper options in
             `ctx.obj`.
-        param_hint (str): CLI parameter associated with the JSON file.
+        param_hint (str): CLI parameter associated with the input file.
         output (Path, optional): Path where the modified PDF should be saved. If
             omitted, the input PDF is overwritten. Defaults to None.
     """
-    input_data = load_json_file(data, schema, param_hint)
+    input_data = load_data_file(data, schema, param_hint)
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     ungrouped_input = []

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm/cli/create.py

@@ -4,8 +4,8 @@ This module defines CLI commands for creating PDF files and PDF content.
 
 It exposes the `create` command group for blank PDFs, extracted page ranges,
 merged PDFs, form fields, raw drawn elements, annotations, and coordinate grid
-views. Commands in this module translate command-line arguments or grouped JSON
-input into `PdfWrapper`, `BlankPage`, `Fields`, `RawElements`, and
+views. Commands in this module translate command-line arguments or grouped
+YAML/JSON input into `PdfWrapper`, `BlankPage`, `Fields`, `RawElements`, and
 `Annotations` operations.
 """
 
@@ -21,7 +21,7 @@ from .common import (
     REQUIRED_OUTPUT_PDF,
     cli_bad_parameter,
     create_elements_from_file,
-    json_file_option,
+    data_file_option,
 )
 from .schemas.create import ANNOTATION_SCHEMA, FIELD_SCHEMA, RAW_SCHEMA
 
@@ -194,13 +194,15 @@ def merge(
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field definitions.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with form field definitions.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Add form fields described by grouped JSON definitions.
+    Add form fields described by grouped YAML or JSON definitions.
 
-    The command maps JSON groups such as `text`, `check`, and `signature` to
+    The command maps input 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.
@@ -209,7 +211,8 @@ def field(
         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.
+        data (Path): YAML or JSON file containing grouped form field
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
     """
@@ -240,13 +243,15 @@ def field(
 def raw(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with raw element definitions.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with raw element definitions.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Draw raw elements described by grouped JSON definitions.
+    Draw raw elements described by grouped YAML or JSON definitions.
 
-    The command maps JSON groups such as `text`, `image`, and `rectangle` to
+    The command maps input 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.
@@ -255,7 +260,8 @@ def raw(
         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.
+        data (Path): YAML or JSON file containing grouped raw element
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
     """
@@ -286,13 +292,15 @@ def raw(
 def annotation(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with annotation definitions.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with annotation definitions.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Add annotations described by grouped JSON definitions.
+    Add annotations described by grouped YAML or JSON definitions.
 
-    The command maps JSON groups such as `text`, `link`, and `highlight` to
+    The command maps input 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.
@@ -301,7 +309,8 @@ def annotation(
         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.
+        data (Path): YAML or JSON file containing grouped annotation
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
     """

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm/cli/entry.py

@@ -10,7 +10,7 @@ of an import traceback when those optional dependencies are absent.
 import importlib
 import sys
 
-CLI_DEPENDENCIES = {"jsonschema", "typer"}
+CLI_DEPENDENCIES = {"jsonschema", "typer", "yaml"}
 CLI_INSTALL_HINT = 'pipx install "PyPDFForm[cli]"'
 CLI_ENV_INSTALL_HINT = "pip install 'PyPDFForm[cli]'"
 

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm/cli/root.py

@@ -8,7 +8,7 @@ commands. The root callback collects global flags in the Typer context so each
 subcommand can initialize `PdfWrapper` with consistent settings.
 
 Commands:
-    - `fill`: Fill an existing PDF form from JSON data.
+    - `fill`: Fill an existing PDF form from YAML or JSON data.
     - `create`: Create PDFs, fields, annotations, raw elements, and grid views.
     - `inspect`: Print form metadata and field data as JSON.
     - `update`: Modify PDF metadata, field names, properties, geometry, and scripts.
@@ -21,7 +21,7 @@ from typing import Annotated
 import typer
 
 from .. import PdfWrapper, Widgets, __version__
-from .common import INPUT_PDF, OPTIONAL_OUTPUT_PDF, json_file_option, load_json_file
+from .common import INPUT_PDF, OPTIONAL_OUTPUT_PDF, data_file_option, load_data_file
 from .create import create_cli
 from .inspect import inspect_cli
 from .remove import remove_cli
@@ -145,12 +145,14 @@ def main(
 
 @cli_app.command(
     no_args_is_help=True,
-    help="Fill a PDF form with JSON data.",
+    help="Fill a PDF form with YAML or JSON data.",
 )
 def fill(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field values.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with form field values.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
     flatten: Annotated[
         bool,
@@ -158,11 +160,11 @@ def fill(
     ] = None,
 ) -> None:
     """
-    Fill an existing PDF form from a validated JSON file.
+    Fill an existing PDF form from a validated YAML or 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
+    accept path objects, validates the input file, normalizes image and
     signature values, and writes the filled PDF to the requested output path or
     back to the input file.
 
@@ -170,7 +172,7 @@ def fill(
         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.
+        data (Path): YAML or 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.
@@ -196,7 +198,7 @@ def fill(
                 ]
             }
 
-    input_data = load_json_file(data, schema, "--file")
+    input_data = load_data_file(data, schema, "--file")
     for k, each in obj.widgets.items():
         if (
             k in input_data

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm/cli/update.py

@@ -5,8 +5,8 @@ This module defines CLI commands for updating existing PDF files.
 It exposes the `update` command group for metadata changes, PDF version
 changes, field bounds edits, field renames, field property updates, and
 document-level JavaScript actions. Commands in this module load command-line or
-JSON input, apply the matching `PdfWrapper` operation, and write the modified
-PDF to either the requested output path or the original file.
+YAML/JSON input, apply the matching `PdfWrapper` operation, and write the
+modified PDF to either the requested output path or the original file.
 """
 
 from enum import Enum
@@ -22,10 +22,10 @@ from .common import (
     INPUT_PDF,
     OPTIONAL_OUTPUT_PDF,
     cli_bad_parameter,
+    data_file_option,
     get_widget,
     handle_font_registration,
-    json_file_option,
-    load_json_file,
+    load_data_file,
 )
 from .schemas.update import FIELD_SCHEMA, RENAME_SCHEMA
 
@@ -186,18 +186,20 @@ def bounds(
 
 @update_cli.command(
     no_args_is_help=True,
-    help="Rename form fields from JSON.",
+    help="Rename form fields from YAML or JSON.",
 )
 def rename(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field renames.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with form field renames.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Rename form fields using a validated JSON mapping file.
+    Rename form fields using a validated YAML or JSON mapping file.
 
-    The command rejects full widget name mode, validates the JSON file against
+    The command rejects full widget name mode, validates the input file against
     the rename schema, resolves each existing field, queues the requested key
     updates on the `PdfWrapper`, commits the rename operations, and writes the
     modified PDF to the requested output path or back to the input file.
@@ -206,13 +208,14 @@ def rename(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing form field rename definitions.
+        data (Path): YAML or JSON file containing form field rename
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
 
     Raises:
         typer.BadParameter: Raised when full widget name mode is enabled, the
-            JSON file is invalid, or a requested field does not exist.
+            input file is invalid, or a requested field does not exist.
     """
     if ctx.obj.get("use_full_widget_name"):
         cli_bad_parameter(
@@ -221,7 +224,7 @@ def rename(
             param_hint="--use-full-widget-name",
         )
 
-    input_data = load_json_file(data, RENAME_SCHEMA, "--file")
+    input_data = load_data_file(data, RENAME_SCHEMA, "--file")
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     for item in input_data:
@@ -234,20 +237,20 @@ def rename(
 
 @update_cli.command(
     no_args_is_help=True,
-    help="Update form field properties from JSON.",
+    help="Update form field properties from YAML or JSON.",
 )
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
     data: Annotated[
-        Path, json_file_option("JSON file with form field property updates.")
+        Path, data_file_option("YAML or JSON file with form field property updates.")
     ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Update form field properties from a validated JSON file.
+    Update form field properties from a validated YAML or JSON file.
 
-    The command validates the JSON input against the field update schema, loads
+    The command validates the input file against the field update schema, loads
     the PDF with the global CLI options stored in `ctx.obj`, resolves each
     field name, registers any referenced fonts once per invocation, assigns the
     requested widget properties, and writes the modified PDF to the requested
@@ -257,15 +260,15 @@ def field(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing form field property updates.
+        data (Path): YAML or JSON file containing form field property updates.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
 
     Raises:
-        typer.BadParameter: Raised when the JSON file is invalid or a requested
+        typer.BadParameter: Raised when the input file is invalid or a requested
             field does not exist.
     """
-    input_data = load_json_file(data, FIELD_SCHEMA, "--file")
+    input_data = load_data_file(data, FIELD_SCHEMA, "--file")
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     registered_font = {}

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.2.5
+Version: 5.3.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -33,6 +33,7 @@ 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"
+Requires-Dist: PyYAML<7.0.0,>=6.0.3; extra == "cli"
 Provides-Extra: dev
 Requires-Dist: coverage<8.0.0,>=7.14.1; extra == "dev"
 Requires-Dist: mike<3.0.0,>=2.2.0; extra == "dev"

{pypdfform-5.2.5 → pypdfform-5.3.0}/PyPDFForm.egg-info/requires.txt

@@ -8,6 +8,7 @@ reportlab<6.0.0,>=4.5.1
 [cli]
 typer<1.0.0,>=0.26.1
 jsonschema<5.0.0,>=4.26.0
+PyYAML<7.0.0,>=6.0.3
 
 [dev]
 coverage<8.0.0,>=7.14.1

{pypdfform-5.2.5 → pypdfform-5.3.0}/pyproject.toml

@@ -43,7 +43,11 @@ Documentation = "https://chinapandaman.github.io/PyPDFForm/"
 
 [project.optional-dependencies]
 # update `CLI_DEPENDENCIES` in `PyPDFForm/cli/entry.py` when changing cli dependencies
-cli = ["typer>=0.26.1,<1.0.0", "jsonschema>=4.26.0,<5.0.0"]
+cli = [
+    "typer>=0.26.1,<1.0.0",
+    "jsonschema>=4.26.0,<5.0.0",
+    "PyYAML>=6.0.3,<7.0.0",
+]
 dev = [
     "coverage>=7.14.1,<8.0.0",
     "mike>=2.2.0,<3.0.0",