New interface for page-level actions

[j-t-1]

Explanation

Page objects may Include an entry named AA that specifies an additional-actions dictionary that extends the set of events that can trigger the execution of an action.

Because there are many types of action (see Table 201—Action types), a good interface for adding them is needed. #3382 is for adding a JavaScript action, but this needs critiquing to ensure it is extensible for other action types.

Code Example

    def add_action(
            self,
            trigger: Literal["O", "C"] = "O",
            action_type: Literal["JavaScript"] = "JavaScript",
            action: str = ""
        ) -> None:
        r"""
        Add action which will launch on the open or close trigger event of this page.

        Args:
            trigger: "/O" or "/C", for open or close trigger event respectively.
            action_type: "JavaScript" is currently the only available action type.
            action: Your JavaScript.

        >>> output.add_action("/O", "JavaScript", 'app.alert("This is page " + this.pageNum);')
        # Example: This will display the page number when the page is opened.
        >>> output.add_action("/C", "JavaScript", 'app.alert("This is page " + this.pageNum);')
        # Example: This will display the page number when the page is closed.

        Note that this will replace any existing open or close trigger event on this page.
        Currently only an open or close event can be added, not both.
        """
        if trigger not in {"/O", "/C"}:
            raise ValueError('The trigger must be "/O" or "/C"')

        if action_type != "JavaScript":
            raise ValueError('Currently the only action_type supported is "JavaScript"')

        additional_actions = DictionaryObject()
        self[NameObject("/AA")] = additional_actions
        additional_actions[NameObject(trigger)] = DictionaryObject(
            {
                NameObject("/Type"): NameObject("/Action"),
                NameObject("/S"): NameObject("/JavaScript"),
                NameObject("/JS"): TextStringObject(f"{action}"),
            }
        )
        action_object = DecodedStreamObject()
        action_object.set_data(action.encode())

[keikurono7]

Can I work on this under the tag of Hacktoberfest?

[stefan6419846]

You can of course look into it and propose some approach, but please keep in mind that - as you can see from the linked existing PR - the API has to be designed and discussed first, including the reasons for choosing a specific API design.

[keikurono7]

Sure I'll let u know as soon as possible

[j-t-1]

There are other objects that can have actions, such as some annotations. Encapsulating action_type and action into an Action class would simplify this API and allow code re-use for other PDF objects that can take actions.

[keikurono7]

Yeah, having classes would be reasonable for this to reduce complexity. I could prepare a draft of the required action class and all the action types it can handle, which you could take a look at

[j-t-1]

@keikurono7 maybe open an Issue with the initial draft. Maybe with one or two actions at first, as getting a good interface is one of the most important things.

Similar to this Issue, the API of an Action class will need thinking about. There are about twenty actions. If the Action class has an extensible interface not all of the actions need be implemented at first.

The arguments to the constructor would be something like action_type first and the action as a second argument. The second argument would be more difficult, although possibly we do similar to this elsewhere in the codebase.

Eventually, pypdf/generic/_actions.py may be a good place for the Action class.

[j-t-1]

Update of add_action to use class Action being developed by @keikurono7:

def add_action(
        self,
        trigger: Literal["O", "C"] = "O",
        action: Action
    ) -> None:
    r"""
    Add action which will launch on the open or close trigger event of this page.

    Args:
        trigger: "/O" or "/C", for open or close trigger event respectively.
        action: An Action object applicable to a page object.

    >>> output.add_action("/O", Action("JavaScript", 'app.alert("This is page " + this.pageNum);'))
    # Example: This will display the page number when the page is opened.
    >>> output.add_action("/C", Action("JavaScript", 'app.alert("This is page " + this.pageNum);'))
    # Example: This will display the page number when the page is closed.

     TODO: Enable both an open or close trigger event to be added
      TODO: Add multiple actions functionality
      TODO: Create a function to delete actions.
    """
    if trigger not in {"/O", "/C"}:
        raise ValueError('The trigger must be "/O" or "/C"')

    additional_actions = DictionaryObject()
    self[NameObject("/AA")] = additional_actions
    additional_actions[NameObject(trigger)] = action

[keikurono7]

here is the action class

class Action(DictionaryObject):

    def __init__(self, action_type: str, data: dict[str, Any] | None = None):
        super().__init__()
        self[NameObject("/Type")] = NameObject("/Action")
        subtype = self.get_subtype(action_type)
        self[NameObject("/S")] = NameObject(subtype)
        self.fill_action(subtype, data)

    def get_subtype(self, action_type: str) -> str:
        supported = {
            "URI": "/URI",
            "JavaScript": "/JavaScript",
        }
        if action_type not in supported:
            raise ValueError(f"Unsupported action type: {action_type}")
        return supported[action_type]

    def fill_action(self, subtype: str, data: dict):
        if subtype == "/URI":
            self[NameObject("/URI")] = TextStringObject(data.get("uri", ""))
        elif subtype == "/JavaScript":
            self[NameObject("/JS")] = TextStringObject(data.get("code", ""))

hey @j-t-1, the data is much more clearer now i feel and i have made the necessary changes u asked for

[j-t-1]

I like it. There may be a better way, but this is how I would do it. One problem is the user needs to know to have "uri" in the dict they pass. Maybe we use the same keys as in the specification. So for the URI action these would be "URI" and "IsMap".

The URI is an ASCII string (see Table 210). It also needs an IsMap.

@stefan6419846 are you ok for this issue to be in two PRs? If not I can close my original one and @keikurono7 copy it into their PR.

[stefan6419846]

Looking into #3486 (comment), I do not see any justification or references to the PDF specification which allows to evaluate the approach. Nevertheless, even this part of the interface looks partially wrong:

• Having action_type passed as a string and basically just prepending a slash to make it a name sounds wrong. Why aren't we asking the user to pass a NameObject directly?
• Why do we need public interfaces for get_subtype and fill_action?
• Apart from this: Is it really desirable to have one class implementing everything? Shouldn't we rather follow the approach from the annotations with one generic base class and sub-classes implementing the action-specific logic? This would allow us to get rid of the action_type parameter completely, while avoiding the generic and hard to document data parameter for action-specific data.

For the following functionality, we still need some evaluation:

• Adding multiple actions.
• Deleting actions.
• Modifying actions(?)

are you ok for this issue to be in two PRs?

I am not going to merge any PRs which have a known weak interface, as we would have to add a deprecation process for it, especially since we do not know when the discussed changes will be released.

[j-t-1]

@stefan6419846 thanks, you are correct using the same method as for annotations simplifies this.

class Action(DictionaryObject, ABC):
    def __init__(self) -> None:
        super().__init__()
        pass

class JavaScript(Action)
    pass

class URI(Action)
    pass

@keikurono7, apologies for the wrong direction.

[keikurono7]

@stefan6419846, @j-t-1, following is the implementation with abstract class and subclass as per the requirements

class Action(DictionaryObject, ABC):
    def __init__(self) -> None:
        super().__init__()
        self[NameObject("/Type")] = NameObject("/Action")

class URIAction(Action):
    def __init__(self, uri: str) -> None:
        super().__init__()
        self[NameObject("/S")] = NameObject("/URI")
        self[NameObject("/URI")] = TextStringObject(uri)

class JavaScriptAction(Action):
    def __init__(self, code: str) -> None:
        super().__init__()
        self[NameObject("/S")] = NameObject("/JavaScript")
        self[NameObject("/JS")] = TextStringObject(code)

Below is the implementation for the requirements

• Adding multiple actions.
• Deleting actions.
• Modifying actions(?)

class PageObject(DictionaryObject):
    # ... other PageObject methods ...

    def add_page_action(self, event: Literal["O", "C"], action_obj: Action) -> None:
        if NameObject("/AA") not in self:
            self[NameObject("/AA")] = DictionaryObject()
        additional_actions = self[NameObject("/AA")]
        additional_actions[NameObject(event)] = action_obj

    def delete_page_action(self, event: Literal["O", "C"]) -> None:
        if NameObject("/AA") in self:
            additional_actions = self[NameObject("/AA")]
            if NameObject(event) in additional_actions:
                del additional_actions[NameObject(event)]
                if not additional_actions:
                    del self[NameObject("/AA")]

And for the modify action add page action can be used to overwrite the previous action. Please let me know if there is any fault in the approach