ENH: Add actions base class

docs/index.rst

@@ -62,6 +62,7 @@ You can contribute to `pypdf on GitHub <https://github.com/py-pdf/pypdf>`_.
    modules/RectangleObject
    modules/Transformation
    modules/XmpInformation
+   modules/actions
    modules/annotations
    modules/constants
    modules/errors

docs/modules/actions.rst

@@ -0,0 +1,7 @@
+Actions
+-------
+
+.. automodule:: pypdf.actions
+    :members:
+    :undoc-members:
+    :show-inheritance:

pypdf/_page.py

@@ -58,6 +58,7 @@
     logger_warning,
     matrix_multiply,
 )
+from .actions import Action
 from .constants import _INLINE_IMAGE_KEY_MAPPING, _INLINE_IMAGE_VALUE_MAPPING
 from .constants import AnnotationDictionaryAttributes as ADA
 from .constants import ImageAttributes as IA
@@ -2157,6 +2158,50 @@ def annotations(self, value: Optional[ArrayObject]) -> None:
         else:
             self[NameObject("/Annots")] = value
 
+    def add_action(self, trigger: Literal["open", "close"], action: Action) -> None:
+        """
+        Add an action which will launch on the open or close trigger event of this page.
+
+        Args:
+            trigger: "open" or "close" trigger event.
+            action: An :py:class:`~pypdf.actions.Action` object;
+                    JavaScript is currently the only available action type.
+
+        # Example: Display the page number when the page is opened
+        >>> self.add_action("open", JavaScript("app.alert('This is page ' + this.pageNum);")))
+        # Example: Display the page number when the page is closed
+        >>> self.add_action("close", JavaScript("app.alert('This is page ' + this.pageNum);")))
+        """
+        Action._create_new(self, trigger, action)
+
+    def delete_action(self, trigger: Literal["open", "close"]) -> None:
+        """
+        Delete an action associated with an open or close trigger event of this page.
+
+        Args:
+            trigger: "open" or "close" trigger event.
+
+        # Example: Delete all actions triggered by a page open.
+        >>> self.delete_action("open")
+        # Example: Delete all actions triggered by a page close.
+        >>> self.delete_action("close")
+        """
+        if trigger not in {"open", "close"}:
+            raise ValueError("The trigger must be 'open' or 'close'")
+
+        trigger_name = NameObject("/O") if trigger == "open" else NameObject("/C")
+
+        if NameObject("/AA") not in self:
+            raise ValueError("An additional-actions dictionary is absent; nothing to delete")
+
+        additional_actions: DictionaryObject = cast(DictionaryObject, self[NameObject("/AA")])
+
+        if trigger_name in additional_actions:
+            del additional_actions[trigger_name]
+
+            if not additional_actions:
+                del self[NameObject("/AA")]
+
 
 class _VirtualList(Sequence[PageObject]):
     def __init__(

pypdf/actions/__init__.py

@@ -0,0 +1,16 @@
+"""
+PDF includes a wide variety of standard action types, whose characteristics and
+behaviour are defined by an action dictionary. These are defined in this
+submodule.
+
+Trigger events, which are the other component of actions, are defined with their
+associated object, elsewhere in the codebase.
+"""
+
+
+from ._actions import Action, JavaScript
+
+__all__ = [
+    "Action",
+    "JavaScript",
+]

pypdf/actions/_actions.py

@@ -0,0 +1,136 @@
+"""Action types"""
+from abc import ABC
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+)
+
+from .._utils import logger_warning
+from ..generic import (
+    ArrayObject,
+    DictionaryObject,
+    NameObject,
+    NullObject,
+    TextStringObject,
+    is_null_or_none,
+)
+
+if TYPE_CHECKING:
+    from .._page import PageObject
+
+
+class Action(DictionaryObject, ABC):
+    """An action dictionary defines the characteristics and behaviour of an action."""
+    def __init__(self) -> None:
+        super().__init__()
+        self[NameObject("/Type")] = NameObject("/Action")
+        # The next action or sequence of actions that shall be performed after the action
+        # represented by this dictionary. The value is either a single action dictionary
+        # or an array of action dictionaries that shall be performed in order.
+        self[NameObject("/Next")] = NullObject()  # Optional
+
+    @classmethod
+    def _create_new(cls, page: "PageObject", trigger: Literal["open", "close"], action: "Action") -> None:
+        """
+        Create a new action and add it to the PageObject.
+
+        Args:
+            page: The PageObject instance to add the embedded file to.
+            trigger: "open" or "close" trigger event.
+            action: An :py:class:`~pypdf.actions.Action` object;
+                    JavaScript is currently the only available action type.
+
+        Returns:
+            None, the action is added to the page directly.
+        """
+        if trigger not in {"open", "close"}:
+            raise ValueError("The trigger must be 'open' or 'close'")
+
+        trigger_name = NameObject("/O") if trigger == "open" else NameObject("/C")
+
+        if not isinstance(action, JavaScript):
+            raise ValueError("Currently the only action type supported is JavaScript")
+
+        if NameObject("/AA") not in page:
+            # Additional actions key not present
+            page[NameObject("/AA")] = DictionaryObject(
+                {trigger_name: action}
+            )
+            return
+
+        if not isinstance(page[NameObject("/AA")], DictionaryObject):
+            page[NameObject("/AA")] = DictionaryObject()
+
+        additional_actions: DictionaryObject = cast(DictionaryObject, page[NameObject("/AA")])
+
+        if trigger_name not in additional_actions or is_null_or_none(additional_actions[trigger_name]):
+            additional_actions.update({trigger_name: action})
+            page[NameObject("/AA")] = additional_actions
+            return
+
+        """
+        The action dictionary's Next entry allows sequences of actions to be
+        chained together. For example, the effect of clicking a link
+        annotation with the mouse can be to play a sound, jump to a new
+        page, and start up a movie. Note that the Next entry is not
+        restricted to a single action but can contain an array of actions,
+        each of which in turn can have a Next entry of its own. The actions
+        can thus form a tree instead of a simple linked list. Actions within
+        each Next array are executed in order, each followed in turn by any
+        actions specified in its Next entry, and so on recursively. It is
+        recommended that interactive PDF processors attempt to provide
+        reasonable behaviour in anomalous situations. For example,
+        self-referential actions ought not be executed more than once, and
+        actions that close the document or otherwise render the next action
+        impossible ought to terminate the execution sequence. Applications
+        need also provide some mechanism for the user to interrupt and
+        manually terminate a sequence of actions.
+        ISO 32000-2:2020
+        """
+        head = current = additional_actions.get(trigger_name)
+        if not isinstance(head, DictionaryObject):
+            raise TypeError(
+                "The entries in a page object's additional-actions dictionary must be dictionaries"
+            )
+        current = cast(DictionaryObject, current)
+
+        visited = set()
+        while True:
+            next_ = current[NameObject("/Next")]
+
+            if is_null_or_none(next_):
+                break
+
+            if not isinstance(next_, (ArrayObject, DictionaryObject)):
+                raise TypeError(
+                    "Must be either a single action dictionary or an array of action dictionaries"
+                )
+
+            id_ = id(next_)
+            if id_ in visited:
+                logger_warning(f"Detected cycle in the action tree for {current}", __name__)
+                break
+            visited.add(id_)
+
+            if isinstance(next_, ArrayObject):
+                current = next_[-1]
+            elif isinstance(next_, DictionaryObject):
+                current = next_
+
+        if not is_null_or_none(current[NameObject("/Next")]) and id(current[NameObject("/Next")]) in visited:
+            logger_warning(f"Detected cycle in the action tree for {current}", __name__)
+
+        current[NameObject("/Next")] = action
+        additional_actions.update({trigger_name: head})
+        page[NameObject("/AA")] = additional_actions
+
+
+class JavaScript(Action):
+    # Upon invocation of an ECMAScript action, a PDF processor shall execute a script
+    # that is written in the ECMAScript programming language. ECMAScript extensions
+    # described in ISO/DIS 21757-1 shall also be allowed.
+    def __init__(self, JS: str) -> None:
+        super().__init__()
+        self[NameObject("/S")] = NameObject("/JavaScript")
+        self[NameObject("/JS")] = TextStringObject(JS)

pypdf/types.py

@@ -78,3 +78,7 @@
     "/Projection",
     "/RichMedia",
 ]
+
+ActionSubtype: TypeAlias = Literal[
+    "/JavaScript",
+]