Working with interactive forms

pikepdf provides two interfaces for working with interactive forms. There is a low-level interface, pikepdf.AcroForm, which is exposed as the pikepdf.Pdf.acroform property. There is also a higher-level interface available in the pikepdf.form module, which provides several abstractions to make usage easier.

Extracting Form Data

It is relatively easy to extract basic form data from a PDF.

>>> from pikepdf.form import Form

>>> form = Form(pdf)

>>> data = {}

>>> for field_name, field in form.items():
...    if field.is_text or field.is_choice or field.is_radio_button:
...        data[field_name] = field.value
...    elif field.is_checkbox:
...        data[field_name] = field.checked

Inspecting the Form

The form allows retrieving specific named fields via dict-like access. There are several useful properties common to all fields. The most useful of these are:

alternate_name, which is a human-readable label for the field.
fully_qualified_name, which is the machine-readable key which identifies this field
is_required
is_text
is_checkbox
is_radio_button
is_pushbutton
is_choice

>>> field = form['MyField']

>>> field.fully_qualified_name
"MyField"

>>> field.alternate_name
"Applicant's first given name"

>>> field.is_text
True

>>> field.is_required
False

Fields with duplicate names are supported. Accessing them by name returns a list of fields instead of a single field. Accessing attributes directly on this list (e.g. field.value) will proxy to the first field in the list.

Filling Form Data

Before filling a form, you will need to determine how you will deal with appearance streams. In addition to merely holding values, PDF form fields must explicitly declare how the filled-in value should look. This is known as the appearance stream. There are several options available.

First, you may choose not to generate appearance streams at all. Most full-fat PDF readers are capable of generating these appearance streams themselves, so depending on your use case it may be acceptable to leave appearance stream generation to the end-user application. This is the default behavior of the pikepdf.form.Form class.

If you do need or want to generate appearance streams, you must provide the class you wish to use to accomplish this task. There are two possible implementations provided with pikepdf: pikepdf.form.DefaultAppearanceStreamGenerator and pikepdf.form.ExtendedAppearanceStreamGenerator. To use either of these, simply pass the class as the second argument to the constructor:

>>> from pikepdf.form import Form, DefaultAppearanceStreamGenerator

>>> form = Form(pdf, DefaultAppearanceStreamGenerator)

The differences between these two options is explained in the documentation for each class.

Lastly, you may implement your own class for generating appearance streams that better fits your specific use case. It must implement the interface provided by pikepdf.form.AppearanceStreamGenerator.

After filling a form, you may also wish to flatten it. This converts the interactive form fields into normal, un-editable text. This can be done as follows:

pdf.flatten_annotations()

Generating appearance streams is required if you wish to flatten the form.

Text Fields

Text fields can either resemble an HTML text input, or an HTML textarea, as well as a password field, file upload, or rich text input. pikepdf supports only the first two options, which can be distinguished from one another using the is_multiline property.

The underlying value of the text field is stored in the value property. The field may also have a default_value which should be used when resetting the form.

>>> text_field = form['MyTextField']

>>> text_field.is_multiline
False

>>> text_field.default_value
''

>>> text_field.value
''

>>> text_field.max_length
75

>>> text_field.value = "Hello World!"

Checkbox Fields

Checkbox fields behave somewhat similarly to what you might be familiar with working with HTML forms in JavaScript. There is a checked property which will tell you if the box is checked or not. If access to the underlying value is needed, it can be fetched via the value property.

Unlike HTML checkboxes, however, there is a value for both the on and off states, and thus value will return different values depending on if the box is checked or not. The value for an off state will be a pikepdf.Name with the value “/Off”. The value for the on state is variable, and can be retrieved from the on_value property.

>>> checkbox_field = form['MyCheckbox']

>>> checkbox.checked
False

>>> checkbox.value
pikepdf.Name("/Off")

>>> checkbox.on_value
pikepdf.Name("/Yes")

>> checkbox.states
(pikepdf.Name("/Yes"), pikepdf.Name("/Off"))

>>> checkbox.checked = True

>>> checkbox.value
pikepdf.Name("/Yes")

Radio Button Groups

A radio button group is constrained to a finite list of allowed values, which are all pikepdf.Name objects. The list of allowed values can be obtained via the states property.

>>> radio_group = form['MyRadioButtonGroup']

>>> radio_group.states
(pikepdf.Name("/1"), pikepdf.Name("/2"), pikepdf.Name("/3"))

>>> radio_group.value
None

>>> radio_group.value = pikepdf.Name("/1")

Radio buttons are returned as a group rather than as individual buttons, though representations of the individual buttons can be obtained by way of the options property. You can set the selection option via the group’s selected property, or via the button’s select method.

>>> radio_group.options[0].checked
True

>>> radio_group.options[1].on_value
pikepdf.Name("/2")

>>> radio_group.options[1].states
(pikepdf.Name("/2"), pikepdf.Name("/Off"))

>>> radio_group.selected = radio_group.options[1]

>>> radio_group.value
pikepdf.Name("/2")

>>> radio_group.options[2].select()

>>> radio_group.value
pikepdf.Name("/3")

Choice Fields

Choice fields may be either list boxes or comboboxes, as determined by the is_combobox property. If the field is a combobox, it may optionally have an editable text box attached to it, as shown by the allows_edit property. Editable choice fields may store arbitrary values, but otherwise choice fields are limited to those options which are returned via the options property.

>>> field = form['MyChoiceField']

>>> field.is_combobox
True

>>> field.allows_edit
False

>>> field.options[0].display_name
"Pike"

>>> field.options[2].select()

>>> field.value
"Trout"

>>> field.value = "Pike"

Signature Fields

pikepdf does not support signature fields, but does include a utility function to stamp an image over the top of the field’s bounding box. The stamped image must be a PDF.

>>> form_pdf = Pdf.open(...)

>>> sig_pdf = Pdf.open(...)

>>> form = Form(form_pdf)

>>> form['MySigField'].stamp_overlay(sig_pdf.pages[0])

To stamp an image that is not already a PDF, you will need to use an image processing library, such as Pillow to convert it:

>>> from PIL import Image

>>> img = Image.open(img).convert('RGB')

>>> img_as_pdf = BytesIO()

>>> img.save(img_as_pdf, 'pdf')

>>> img_as_pdf.seek(0)

>>> sig_pdf = Pdf.open(img_as_pdf)