PyPDFForm 5.2.5__tar.gz → 5.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.2.5
+Version: 5.4.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"
@@ -120,15 +121,3 @@ The official documentation can be found on [the GitHub page](https://chinapandam
 <!-- TODO: remove WIP when finish recording -->
 * [(WIP) Video Tutorials](https://youtube.com/playlist?list=PLNz_PBu1QA-gzYg5BvyOO98q15u5Xve1L&si=8MWasKEckBzY-NRQ)
 * [Chicago Python User Group - Dec 14, 2023](https://youtu.be/8t1RdAKwr9w?si=TLgumBNXv9H8szSn)
-
-## Star History
-
-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.
-
-<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.5 → pypdfform-5.4.0}/PyPDFForm/__init__.py

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

pypdfform-5.4.0/PyPDFForm/cli/common.py

@@ -0,0 +1,373 @@
+# -*- coding: utf-8 -*-
+"""
+This module provides shared helpers for PyPDFForm CLI commands.
+
+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.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+
+import typer
+import yaml
+from jsonschema import ValidationError, validate
+
+from .. import PdfWrapper
+from ..lib.middleware.base import Widget
+
+INPUT_PDF = Annotated[
+    Path,
+    typer.Argument(
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help="Input PDF path.",
+    ),
+]
+REQUIRED_OUTPUT_PDF = Annotated[
+    Path,
+    typer.Option(
+        "--output",
+        "-o",
+        file_okay=True,
+        dir_okay=False,
+        writable=True,
+        resolve_path=True,
+        help="Output PDF path.",
+    ),
+]
+OPTIONAL_OUTPUT_PDF = Annotated[
+    Path | None,
+    typer.Option(
+        "--output",
+        "-o",
+        file_okay=True,
+        dir_okay=False,
+        writable=True,
+        resolve_path=True,
+        help="Output PDF path. Overwrites the input when omitted.",
+    ),
+]
+FIELD_NAME = Annotated[str, typer.Option("--field", help="Form field name.")]
+FIELD_NAMES = Annotated[
+    list[str],
+    typer.Option(
+        "--field",
+        help="Form field name. Repeat this option to select multiple fields.",
+    ),
+]
+
+
+def data_file_option(help_text: str):
+    """
+    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 file input.
+    """
+    return typer.Option(
+        "--file",
+        "-f",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help=help_text,
+    )
+
+
+def cli_bad_parameter(
+    message: str,
+    param_hint: str,
+    cause: BaseException | None = None,
+) -> NoReturn:
+    """
+    Raises a Typer input error with a stable CLI message.
+
+    Args:
+        message (str): Error message to display to the CLI user.
+        param_hint (str): CLI parameter associated with the error.
+        cause (BaseException, optional): Original exception that caused the CLI
+            error. Defaults to None.
+
+    Raises:
+        typer.BadParameter: Raised with the provided message and parameter hint.
+    """
+    if cause is None:
+        raise typer.BadParameter(message, param_hint=param_hint)
+
+    raise typer.BadParameter(message, param_hint=param_hint) from cause
+
+
+def _validation_error_path(exc: ValidationError) -> str:
+    """
+    Builds a dotted input data path for a validation error.
+
+    Args:
+        exc (ValidationError): The JSON schema validation error.
+
+    Returns:
+        str: Dotted path for the failing instance location.
+    """
+    return ".".join(str(each) for each in exc.absolute_path)
+
+
+def _input_file_kind(data: Path) -> str:
+    """
+    Gets the structured data format to use for a CLI input file.
+
+    Args:
+        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 _validate_input_data(
+    input_data: Any,
+    schema: dict,
+    source: str,
+    param_hint: str,
+) -> Any:
+    """
+    Validates parsed CLI input against a JSON schema.
+
+    Args:
+        input_data (Any): Parsed input data to validate.
+        schema (dict): JSON schema to validate against.
+        source (str): User-facing description of the input source.
+        param_hint (str): CLI parameter associated with the input.
+
+    Returns:
+        Any: The validated input data.
+
+    Raises:
+        typer.BadParameter: Raised when validation fails.
+    """
+    try:
+        validate(instance=input_data, schema=schema)
+    except ValidationError as exc:
+        error_path = _validation_error_path(exc)
+        location = f" at {error_path}" if error_path else ""
+        cli_bad_parameter(
+            f"Invalid {source}{location}: {exc.message}",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+    return input_data
+
+
+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 input file.
+
+    Returns:
+        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 = 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 {input_kind} file: {exc}",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+    return _validate_input_data(
+        input_data,
+        schema,
+        f"{input_kind} file",
+        param_hint,
+    )
+
+
+def load_data_options(options: list[str], schema: dict, param_hint: str) -> Any:
+    """
+    Parses command-line data options and validates them against a schema.
+
+    Options use ``--name value`` syntax. Each value is parsed with
+    :func:`yaml.safe_load`.
+
+    Args:
+        options (list[str]): Unrecognized command arguments captured by Typer.
+        schema (dict): JSON schema to validate the resulting option mapping
+            against.
+        param_hint (str): CLI parameter description used in error messages.
+
+    Returns:
+        Any: Parsed and validated option data.
+
+    Raises:
+        typer.BadParameter: Raised when the options cannot be parsed or the
+            resulting mapping fails validation.
+    """
+    if any(not option.startswith("--") for option in options[::2]):
+        cli_bad_parameter(
+            "Use '--name value' pairs with valid values.",
+            param_hint=param_hint,
+        )
+
+    try:
+        input_data = {
+            option[2:]: yaml.safe_load(value)
+            for option, value in zip(options[::2], options[1::2], strict=True)
+        }
+    except (ValueError, yaml.YAMLError) as exc:
+        cli_bad_parameter(
+            "Use '--name value' pairs with valid values.",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+    return _validate_input_data(input_data, schema, "CLI options", param_hint)
+
+
+def get_widget(wrapper: PdfWrapper, field: str, param_hint: str) -> Widget:
+    """
+    Look up a widget and report missing names as CLI input errors.
+
+    Args:
+        wrapper (PdfWrapper): PDF wrapper containing form widgets.
+        field (str): Form field name to look up.
+        param_hint (str): CLI parameter associated with the field name.
+
+    Returns:
+        Widget: The matching widget.
+
+    Raises:
+        typer.BadParameter: Raised when the widget name is not present.
+    """
+    try:
+        return wrapper.widgets[field]
+    except KeyError as exc:
+        cli_bad_parameter(
+            f"Form field '{field}' does not exist.",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+
+def handle_font_registration(
+    obj: PdfWrapper, params: dict, registered_font: dict
+) -> None:
+    """
+    Registers a custom font referenced by CLI input.
+
+    CLI input 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 CLI input.
+            This dictionary is mutated when it contains a `font` key.
+        registered_font (dict): Mapping of resolved source font paths to
+            generated `PdfWrapper` font names for the current command
+            invocation.
+    """
+    if "font" in params:
+        font_path = str(Path(params["font"]).resolve())
+        if font_path not in registered_font:
+            font_name = f"new_font_{len(registered_font)}"
+            obj.register_font(font_name, font_path)
+            registered_font[font_path] = font_name
+        params["font"] = registered_font[font_path]
+
+
+def create_elements_from_file(
+    pdf: Path,
+    data: Path | None,
+    element_map: dict,
+    schema: dict,
+    method_name: str,
+    ctx: typer.Context,
+    file_param_hint: str,
+    options_param_hint: str,
+    output: Path | None = None,
+    element_type: str | None = None,
+) -> None:
+    """
+    Creates PDF elements from a data file or command-line options.
+
+    A data file groups element definitions by type, such as `text`, `image`, or
+    `highlight`. Without a data file, one element of `element_type` is created
+    from the additional command-line options stored in ``ctx.args``. The data
+    file takes precedence when both input forms are supplied. Each definition
+    is constructed after optional font registration and passed to `method_name`
+    on `PdfWrapper`.
+
+    Args:
+        pdf (Path): The path to the input PDF file.
+        data (Path, optional): The path to the input file containing grouped
+            element definitions. Defaults to None.
+        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 file or command-line input.
+        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`.
+        file_param_hint (str): CLI parameter associated with the input file.
+        options_param_hint (str): CLI parameter description associated with
+            command-line options.
+        output (Path, optional): Path where the modified PDF should be saved. If
+            omitted, the input PDF is overwritten. Defaults to None.
+        element_type (str, optional): Element type selected for command-line
+            input. Defaults to None.
+    """
+    if data is not None:
+        input_data = load_data_file(data, schema, file_param_hint)
+    else:
+        if element_type not in element_map:
+            choices = ", ".join(element_map)
+            cli_bad_parameter(
+                f"Choose one of: {choices}.",
+                param_hint="--type",
+            )
+        input_data = {
+            element_type: [
+                load_data_options(
+                    ctx.args,
+                    schema["properties"][element_type]["items"],
+                    options_param_hint,
+                )
+            ]
+        }
+
+    obj = PdfWrapper(str(pdf), **ctx.obj)
+    ungrouped_input = []
+    registered_font = {}
+    for k, v in input_data.items():
+        for each in v:
+            handle_font_registration(obj, each, registered_font)
+            ungrouped_input.append(element_map[k](**each))
+
+    getattr(obj, method_name)(ungrouped_input).write(output or pdf)

{pypdfform-5.2.5 → pypdfform-5.4.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
 
@@ -188,30 +188,43 @@ def merge(
 
 
 @create_cli.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
     no_args_is_help=True,
-    help="Add form fields to a PDF.",
+    help="Add form fields from a YAML or JSON file or command-line options.",
 )
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field definitions.")],
+    data: Annotated[
+        Path | None, data_file_option("YAML or JSON file with form field definitions.")
+    ] = None,
     output: OPTIONAL_OUTPUT_PDF = None,
+    element_type: Annotated[
+        str | None,
+        typer.Option("--type", help="Type of form field to create without --file."),
+    ] = None,
 ) -> None:
     """
-    Add form fields described by grouped JSON definitions.
+    Add form fields from a data file or command-line options.
 
-    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.
+    The command maps input groups such as `text`, `check`, and `signature` to
+    PyPDFForm field classes, validates the input against the CLI field schema,
+    creates the corresponding field objects, and calls
+    `PdfWrapper.bulk_create_fields` before writing the modified PDF. A data file
+    can define multiple fields grouped by type. Without `--file`, `--type` and
+    the field options define one field. The data file takes precedence when
+    both input forms are supplied.
 
     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.
+        data (Path, optional): YAML or JSON file containing grouped form field
+            definitions. Defaults to None.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
+        element_type (str, optional): Form field type used when `data` is
+            omitted. Defaults to None.
     """
     field_map = {
         "text": Fields.TextField,
@@ -228,36 +241,51 @@ def field(
         schema=FIELD_SCHEMA,
         method_name="bulk_create_fields",
         ctx=ctx,
-        param_hint="--file",
+        file_param_hint="--file",
+        options_param_hint="field options",
         output=output,
+        element_type=element_type,
     )
 
 
 @create_cli.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
     no_args_is_help=True,
-    help="Draw text, images, and shapes on a PDF.",
+    help="Draw elements from a YAML or JSON file or command-line options.",
 )
 def raw(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with raw element definitions.")],
+    data: Annotated[
+        Path | None, data_file_option("YAML or JSON file with raw element definitions.")
+    ] = None,
     output: OPTIONAL_OUTPUT_PDF = None,
+    element_type: Annotated[
+        str | None,
+        typer.Option("--type", help="Type of element to draw without --file."),
+    ] = None,
 ) -> None:
     """
-    Draw raw elements described by grouped JSON definitions.
+    Draw elements from a data file or command-line options.
 
-    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.
+    The command maps input groups such as `text`, `image`, and `rectangle` to
+    raw element classes, validates the input against the CLI raw element schema,
+    creates the corresponding drawable objects, and calls `PdfWrapper.draw`
+    before writing the modified PDF. A data file can define multiple elements
+    grouped by type. Without `--file`, `--type` and the element options define
+    one element. The data file takes precedence when both input forms are
+    supplied.
 
     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.
+        data (Path, optional): YAML or JSON file containing grouped raw element
+            definitions. Defaults to None.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
+        element_type (str, optional): Element type used when `data` is omitted.
+            Defaults to None.
     """
     raw_element_map = {
         "text": RawElements.RawText,
@@ -274,36 +302,51 @@ def raw(
         schema=RAW_SCHEMA,
         method_name="draw",
         ctx=ctx,
-        param_hint="--file",
+        file_param_hint="--file",
+        options_param_hint="element options",
         output=output,
+        element_type=element_type,
     )
 
 
 @create_cli.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
     no_args_is_help=True,
-    help="Add annotations to a PDF.",
+    help="Add annotations from a YAML or JSON file or command-line options.",
 )
 def annotation(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with annotation definitions.")],
+    data: Annotated[
+        Path | None, data_file_option("YAML or JSON file with annotation definitions.")
+    ] = None,
     output: OPTIONAL_OUTPUT_PDF = None,
+    element_type: Annotated[
+        str | None,
+        typer.Option("--type", help="Type of annotation to add without --file."),
+    ] = None,
 ) -> None:
     """
-    Add annotations described by grouped JSON definitions.
+    Add annotations from a data file or command-line options.
 
-    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.
+    The command maps input groups such as `text`, `link`, and `highlight` to
+    annotation classes, validates the input against the CLI annotation schema,
+    creates the corresponding annotation objects, and calls
+    `PdfWrapper.annotate` before writing the modified PDF. A data file can
+    define multiple annotations grouped by type. Without `--file`, `--type` and
+    the annotation options define one annotation. The data file takes
+    precedence when both input forms are supplied.
 
     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.
+        data (Path, optional): YAML or JSON file containing grouped annotation
+            definitions. Defaults to None.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
+        element_type (str, optional): Annotation type used when `data` is
+            omitted. Defaults to None.
     """
     annotation_map = {
         "text": Annotations.TextAnnotation,
@@ -321,8 +364,10 @@ def annotation(
         schema=ANNOTATION_SCHEMA,
         method_name="annotate",
         ctx=ctx,
-        param_hint="--file",
+        file_param_hint="--file",
+        options_param_hint="annotation options",
         output=output,
+        element_type=element_type,
     )
 
 

{pypdfform-5.2.5 → pypdfform-5.4.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]'"