PyPDFForm 5.4.1__tar.gz → 5.5.0__tar.gz

{pypdfform-5.4.1 → pypdfform-5.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.4.1
+Version: 5.5.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm/__init__.py

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

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm/cli/inspect.py

@@ -2,10 +2,10 @@
 """
 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.
+It exposes the `inspect` command group, which prints PDF titles and 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
@@ -20,6 +20,28 @@ inspect_cli = typer.Typer(
 )
 
 
+@inspect_cli.command(
+    no_args_is_help=True,
+    help="Print the PDF title.",
+)
+def title(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """
+    Print the document title metadata from an existing PDF.
+
+    The command loads the PDF with the global CLI options stored in `ctx.obj`,
+    reads `PdfWrapper.title`, 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(PdfWrapper(str(pdf), **ctx.obj).title)
+
+
 @inspect_cli.command(
     no_args_is_help=True,
     help="Print the form schema as JSON.",

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm/cli/root.py

@@ -113,6 +113,7 @@ def main(
         typer.Option(
             "--preserve-metadata",
             help="Preserve input PDF metadata.",
+            hidden=True,
         ),
     ] = False,
     use_full_widget_name: Annotated[
@@ -137,7 +138,8 @@ def main(
             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.
+        preserve_metadata (bool): Deprecated compatibility option. Input PDF
+            metadata is preserved automatically.
         use_full_widget_name (bool): Whether widget lookups should use full
             form field names.
     """

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm/lib/egress.py

@@ -5,11 +5,9 @@ A module for egress functions.
 This module provides functionalities that prepare the final PDF for output (egress),
 ensuring that it is properly formatted and ready for the end-user. This includes
 managing appearance streams (so form fields display correctly after being filled),
-handling the /NeedAppearances flag, and preserving or updating document-level
-properties like metadata, title, and OpenAction scripts. It can also rebuild the
-AcroForm `/Fields` array from the widget annotations present on each page. These
-functions are typically called right before the final PDF byte stream is returned by
-the wrapper module.
+handling the /NeedAppearances flag, and rebuilding the AcroForm `/Fields` array from
+the widget annotations present on each page. These functions are typically called
+right before the final PDF byte stream is returned by the wrapper module.
 """
 
 from functools import lru_cache
@@ -18,19 +16,14 @@ from warnings import catch_warnings, filterwarnings
 
 from pikepdf import Pdf
 from pypdf import PdfWriter
-from pypdf.generic import ArrayObject, DictionaryObject, NameObject, TextStringObject
+from pypdf.generic import ArrayObject, DictionaryObject, NameObject
 
 from .constants import (
-    JS,
     XFA,
     AcroForm,
     Annots,
     Fields,
-    JavaScript,
-    OpenAction,
     Parent,
-    S,
-    Title,
 )
 from .template import get_widget_key
 
@@ -85,50 +78,6 @@ def appearance_streams_handler(pdf: bytes, generate_appearance_streams: bool) ->
     return result
 
 
-def preserve_pdf_properties(
-    pdf: bytes, title: str, script: str, metadata: dict
-) -> bytes:
-    """
-    Preserves and updates PDF properties such as metadata, title, and OpenAction scripts.
-
-    This function allows setting or updating the PDF's title and metadata, and
-    attaching a JavaScript script that executes when the PDF is opened. Metadata
-    is merged into the reader's current metadata when provided; the title and
-    OpenAction JavaScript are written only when non-empty values are supplied.
-
-    Args:
-        pdf (bytes): The PDF file content as a bytes stream.
-        title (str): The title to be set in the PDF metadata.
-        script (str): JavaScript code to be executed when the PDF is opened.
-        metadata (dict): The original metadata to preserve.
-
-    Returns:
-        bytes: The modified PDF content as a bytes stream.
-    """
-    writer = PdfWriter(BytesIO(pdf))
-
-    if title or metadata:
-        _metadata = writer.metadata or {}
-        if metadata:
-            _metadata.update(metadata)
-        if title:
-            _metadata[NameObject(Title)] = TextStringObject(title)
-
-        writer.add_metadata(_metadata)
-
-    if script:
-        open_action = DictionaryObject()
-        open_action[NameObject(S)] = NameObject(JavaScript)
-        open_action[NameObject(JS)] = TextStringObject(script)
-
-        writer._root_object.update({NameObject(OpenAction): open_action})  # type: ignore # noqa: SLF001 # # pylint: disable=W0212
-
-    with BytesIO() as f:
-        writer.write(f)
-        f.seek(0)
-        return f.read()
-
-
 def rebuild_acroform_fields(
     pdf: bytes, widget_keys: set, use_full_widget_name: bool
 ) -> bytes:

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm/lib/template.py

@@ -2,10 +2,10 @@
 """
 Module for handling PDF form templates.
 
-This module provides functionalities to extract, build, and update widgets
-in PDF form templates. It leverages the pypdf library for PDF manipulation
-and defines specific patterns for identifying and constructing different
-types of widgets.
+This module provides functionalities to read and update document metadata, set
+document-level actions, and extract, build, and update widgets in PDF form
+templates. It leverages the pypdf library for PDF manipulation and defines
+specific patterns for identifying and constructing different types of widgets.
 """
 
 from copy import deepcopy
@@ -14,10 +14,21 @@ from io import BytesIO
 from typing import Dict, List, cast
 
 from pypdf import PdfReader, PdfWriter
-from pypdf.generic import ArrayObject, DictionaryObject, NameObject
+from pypdf.generic import ArrayObject, DictionaryObject, NameObject, TextStringObject
 
 from .annotations import AnnotationTypes
-from .constants import COMB, MULTILINE, READ_ONLY, REQUIRED, Annots
+from .constants import (
+    COMB,
+    JS,
+    MULTILINE,
+    READ_ONLY,
+    REQUIRED,
+    Annots,
+    JavaScript,
+    OpenAction,
+    S,
+    Title,
+)
 from .middleware import WIDGET_TYPES
 from .middleware.checkbox import Checkbox
 from .middleware.dropdown import Dropdown
@@ -60,6 +71,87 @@ def get_metadata(pdf: bytes) -> dict:
     return reader.metadata or {}
 
 
+def get_title(pdf: bytes) -> str | None:
+    """
+    Retrieves the title from a PDF's document metadata.
+
+    Args:
+        pdf (bytes): The PDF stream from which to retrieve the title.
+
+    Returns:
+        str | None: The document title, or None when no title is present.
+    """
+    return get_metadata(pdf).get(Title)
+
+
+def set_metadata(pdf: bytes, metadata: dict) -> bytes:
+    """
+    Merges metadata into a PDF's existing document metadata.
+
+    Existing entries are retained unless the supplied mapping contains the
+    same key, in which case the supplied value replaces the existing value.
+
+    Args:
+        pdf (bytes): The PDF stream whose metadata should be updated.
+        metadata (dict): Metadata entries to add or replace.
+
+    Returns:
+        bytes: The PDF stream containing the merged metadata.
+    """
+    writer = PdfWriter(BytesIO(pdf))
+    _metadata = writer.metadata or {}
+    _metadata.update(metadata)
+    writer.add_metadata(_metadata)
+
+    with BytesIO() as f:
+        writer.write(f)
+        f.seek(0)
+        return f.read()
+
+
+def set_title(pdf: bytes, title: str) -> bytes:
+    """
+    Sets a PDF's document title while preserving its other metadata.
+
+    Args:
+        pdf (bytes): The PDF stream whose title should be set.
+        title (str): The document title to store in the PDF metadata.
+
+    Returns:
+        bytes: The PDF stream containing the updated title.
+    """
+    return set_metadata(pdf, {Title: title})
+
+
+def set_on_open_javascript(pdf: bytes, script: str) -> bytes:
+    """
+    Sets a PDF's document-open action to execute JavaScript.
+
+    The script is written to the document catalog as a JavaScript
+    `/OpenAction`, replacing any existing document-open action. An action is
+    written even when `script` is empty.
+
+    Args:
+        pdf (bytes): The PDF stream whose document-open action should be set.
+        script (str): JavaScript to execute when the PDF is opened.
+
+    Returns:
+        bytes: The PDF stream containing the JavaScript `/OpenAction`.
+    """
+    writer = PdfWriter(BytesIO(pdf))
+
+    open_action = DictionaryObject()
+    open_action[NameObject(S)] = NameObject(JavaScript)
+    open_action[NameObject(JS)] = TextStringObject(script)
+
+    writer._root_object.update({NameObject(OpenAction): open_action})  # type: ignore # noqa: SLF001 # # pylint: disable=W0212
+
+    with BytesIO() as f:
+        writer.write(f)
+        f.seek(0)
+        return f.read()
+
+
 def build_widgets(
     pdf_stream: bytes,
     use_full_widget_name: bool,

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm/lib/wrapper.py

@@ -27,7 +27,6 @@ from typing import (
     BinaryIO,
     Dict,
     List,
-    Optional,
     Sequence,
     TextIO,
     Tuple,
@@ -38,9 +37,9 @@ from .adapter import (
     fp_or_f_obj_or_stream_to_stream,
 )
 from .coordinate import generate_coordinate_grid
+from .deprecation import deprecation_notice
 from .egress import (
     appearance_streams_handler,
-    preserve_pdf_properties,
     rebuild_acroform_fields,
 )
 from .filler import fill
@@ -58,7 +57,10 @@ from .template import (
     build_widgets,
     create_annotations,
     get_metadata,
+    get_title,
     remove_widgets_by_keys,
+    set_on_open_javascript,
+    set_title,
     update_widget_keys,
 )
 from .types import PdfArray
@@ -107,8 +109,11 @@ class PdfWrapper:
                 - `use_full_widget_name` (bool): Whether to use the full widget name when filling the form.
                 - `need_appearances` (bool): Whether to set the `NeedAppearances` flag in the PDF's AcroForm dictionary.
                 - `generate_appearance_streams` (bool): Whether to explicitly generate appearance streams for all form fields using pikepdf.
-                - `preserve_metadata` (bool): Whether to preserve the original metadata of the PDF.
-                - `title` (str): The title of the PDF document.
+                - `preserve_metadata` (bool): Deprecated compatibility attribute;
+                  input PDF metadata is captured automatically.
+                - `title` (str | None): The title stored in the PDF's document
+                  metadata. A non-None value replaces the existing title; None
+                  preserves it.
 
     """
 
@@ -129,9 +134,12 @@ class PdfWrapper:
         Constructor method for the `PdfWrapper` class.
 
         Initializes a new `PdfWrapper` object with the given template PDF and optional keyword arguments.
-        The template is normalized to bytes, existing widgets are loaded immediately, and
-        original metadata is captured only when `preserve_metadata` is requested.
-        Enabling `generate_appearance_streams` also enables `need_appearances`.
+        The template is normalized to bytes, existing widgets are loaded immediately,
+        and the original metadata and title are read. A non-None `title` keyword
+        updates the title in the PDF stream; None preserves the title read from the
+        template. The deprecated `preserve_metadata` keyword is accepted for backward
+        compatibility and emits a deprecation warning. Enabling
+        `generate_appearance_streams` also enables `need_appearances`.
 
         Args:
             template (bytes | str | BinaryIO | BlankPage): The template PDF, provided as either:
@@ -148,12 +156,10 @@ class PdfWrapper:
         super().__init__()
         self._stream = fp_or_f_obj_or_stream_to_stream(template)
         self.widgets = {}
-        self.title: Optional[str] = None
 
         self._version = None
-        self._metadata = (
-            get_metadata(self._read()) if kwargs.get("preserve_metadata") else {}
-        )
+        self._metadata = get_metadata(self._read())
+        self._title = get_title(self._read())
         self._on_open_javascript = None
         self._available_fonts = {}  # for setting /F1
         self._available_fonts_loaded = None  # for lazy loading fonts
@@ -163,6 +169,10 @@ class PdfWrapper:
 
         # sets attrs from kwargs
         for attr, default in self.USER_PARAMS:
+            if attr == "preserve_metadata" and attr in kwargs:
+                deprecation_notice("", "preserve_metadata").emit_notice(
+                    self, "__init__"
+                )
             setattr(self, attr, kwargs.get(attr, default))
 
         if getattr(self, "generate_appearance_streams") is True:
@@ -317,6 +327,34 @@ class PdfWrapper:
 
         return self
 
+    @property
+    def title(self) -> str | None:
+        """
+        Gets the title stored in the PDF's document metadata.
+
+        Returns:
+            str | None: The current document title, or None when no title exists.
+        """
+
+        return str(self._title) if self._title is not None else None
+
+    @title.setter
+    def title(self, value: str | None) -> None:
+        """
+        Updates the title stored in the PDF's document metadata.
+
+        A non-None value is written to the underlying PDF stream immediately.
+        None is ignored so the current title is preserved.
+
+        Args:
+            value (str | None): The new document title, or None to preserve the
+                current title.
+        """
+
+        if value is not None:
+            self._stream = set_title(self._read(), value)
+            self._title = value
+
     @property
     def schema(self) -> dict:
         """
@@ -430,10 +468,14 @@ class PdfWrapper:
     @property
     def on_open_javascript(self) -> str | None:
         """
-        Returns the JavaScript script that executes when the PDF is opened.
+        Returns the on-open JavaScript most recently assigned to this wrapper.
+
+        This property tracks assignments made through the wrapper; it does not
+        inspect the template PDF for an existing `/OpenAction`.
 
         Returns:
-            str | None: The JavaScript script, or None if no script is set.
+            str | None: The assigned JavaScript, or None if no script has been
+                assigned through this wrapper.
         """
 
         return self._on_open_javascript
@@ -443,13 +485,18 @@ class PdfWrapper:
         """
         Sets the JavaScript script that executes when the PDF is opened.
 
+        Assignment immediately writes a JavaScript `/OpenAction` to the stored
+        PDF stream, replacing any existing document-open action.
+
         Args:
             value (str | TextIO): The JavaScript script, provided as either:
                 - str: The JavaScript code as a string, or a file path to a .js file.
                 - TextIO: An open file-like object containing the JavaScript code.
         """
 
-        self._on_open_javascript = fp_or_f_obj_or_f_content_to_content(value)
+        script = fp_or_f_obj_or_f_content_to_content(value)
+        self._stream = set_on_open_javascript(self._read(), script)
+        self._on_open_javascript = script
 
     def read(self) -> bytes:
         """
@@ -460,12 +507,10 @@ class PdfWrapper:
         2. If `need_appearances` is enabled, it handles appearance streams and the
            `/NeedAppearances` flag, which may include removing XFA and explicitly
            generating appearance streams.
-        3. If `preserve_metadata`, title, or on-open JavaScript are set, it preserves
-           or updates the corresponding PDF properties accordingly.
-        4. Rebuilds the AcroForm `/Fields` array from page annotations for
+        3. Rebuilds the AcroForm `/Fields` array from page annotations for
            widgets known to this wrapper, leaving the stream unchanged when no
            matching widget annotations are found.
-        5. Restores the wrapper's cached PDF header version after egress
+        4. Restores the wrapper's cached PDF header version after egress
            processing, since PDF writers may emit their own default version.
         The wrapper's stored stream is not replaced by these final egress-only changes.
 
@@ -479,23 +524,6 @@ class PdfWrapper:
                 result, getattr(self, "generate_appearance_streams")
             )  # cached
 
-        if (
-            any(
-                [
-                    getattr(self, "preserve_metadata"),
-                    self.title,
-                    self.on_open_javascript,
-                ]
-            )
-            and result
-        ):
-            result = preserve_pdf_properties(
-                result,
-                self.title,
-                self.on_open_javascript,
-                self._metadata if getattr(self, "preserve_metadata") else None,
-            )
-
         if result:
             result = rebuild_acroform_fields(
                 result, set(self.widgets.keys()), getattr(self, "use_full_widget_name")

{pypdfform-5.4.1 → pypdfform-5.5.0}/PyPDFForm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.4.1
+Version: 5.5.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

{pypdfform-5.4.1 → pypdfform-5.5.0}/tests/test_functional.py

@@ -735,6 +735,10 @@ def test_blank_page(pdf_samples, request):
         expected = f.read()
 
         assert len(obj.read()) == len(expected)
+
+        assert not obj.widgets
+        assert len(obj.pages) == 1
+
         request.config.results["skip_regenerate"] = len(obj.read()) == len(expected)
 
 
@@ -752,6 +756,10 @@ def test_blank_page_custom_size_multiply(pdf_samples, request):
         expected = f.read()
 
         assert len(obj.read()) == len(expected)
+
+        assert not obj.widgets
+        assert len(obj.pages) == 3
+
         request.config.results["skip_regenerate"] = len(obj.read()) == len(expected)