Form

The pikepdf.form module provides a high-level API for working with interactive forms, built on top of the lower-level pikepdf.AcroForm interface.

Support for working with interactive forms.

class pikepdf.form.Form(pdf, generate_appearances=None, *, ignore_max_length=False)

Utility class to make it easier to work with interactive forms.

This is easier to use than the core {class}`pikepdf.AcroForm` implementation, but is higher-level, and abstracts over details in ways which do impose some limitations, such as failing for PDFs which have multiple fields with the same name.

A non-exhaustive list of limitations:

  • No support for signatures

  • No support for password fields

  • No support for rich text fields

  • Multiselect choice fields are treated as single-select

  • Generating appearance streams imposes additional limitations (see {class}`pikepdf.form.DefaultAppearanceStreamGenerator` and {class}`pikepdf.form.ExtendedAppearanceStreamGenerator` for details.)

Parameters:
generate_appearances: AppearanceStreamGenerator | None = None

If provided, this object will be used to generate appearance streams for fields as the form is filled. If not, the needs_appearances flag will be set on the form.

ignore_max_length: bool

If True, we will ignore the MaxLen property of any text fields in this form. This produces a PDF that would typically not be possible to create in an interactive PDF reader, but this may be desirable or useful if the PDF is intended to be read by another automated system rather than a human.

items()

Yield (name, field) pairs for all fields in this form.

Return type:

collections.abc.Generator[tuple[str, _FieldWrapper]]

Form Fields

class pikepdf.form._FieldWrapper(form, field)

Base class for other field types.

In addition to the methods and properties documented here, all fields expose the same properties and methods defined on pikepdf.AcroFormField. These are forwarded to the underlying field object.

Parameters:
property export_enabled: bool

Should this field’s value be included when exporting data from the PDF?

Return type:

bool

property is_read_only: bool

Is this a read-only field?

Return type:

bool

property is_required: bool

Is this a required field?

Return type:

bool

class pikepdf.form.TextField(form, field)

Represents an editable text field.

Parameters:
property default_value: str

The default (placeholder) value of the text field.

Return type:

str

property is_combed: bool

Is this a combed text field?

If True, the field will be split into equal-length segments, based on max_length, containing one character each.

Return type:

bool

property is_file_select: bool

Is this a file select field?

File select fields are not currently implemented, but this flag is presented for your information.

Return type:

bool

property is_multiline: bool

Is this a multiline text field?

If True, text will be wrapped and newlines will be allowed. If False, text will not be wrapped and newlines are stripped.

Return type:

bool

property is_password: bool

Is this a password field?

Password fields are not currently implemented, but this flag is presented for your information.

Return type:

bool

property is_rich_text: bool

Is this a rich text field?

Rich text functionality is not currently implemented, but this flag is presented for your information.

Return type:

bool

property max_length: int | None

The maximum length of the text in this field.

Return type:

int | None

property scrolling_enabled: bool

Should scrolling (horizontal or vertical) be allowed in this field?

Return type:

bool

property spell_check_enabled: bool

Should spell-checking be enabled in this field?

Return type:

bool

property value: str

The value of the text field.

Return type:

str

class pikepdf.form.CheckboxField(form, field)

Represents a checkbox field.

Parameters:
property checked: bool

Is this checkbox checked?

Return type:

bool

property on_value: pikepdf.Name

The underlying value associated with this checkbox’s “on” state.

Return type:

pikepdf.Name

property states: collections.abc.Sequence[pikepdf.Name]

List the possible states for this checkbox.

Typically this will be /Off plus one additional arbitrary value representing the on state.

Return type:

collections.abc.Sequence[pikepdf.Name]

property value: pikepdf.Name | None

The actual current stored value of this checkbox.

Return type:

pikepdf.Name | None

class pikepdf.form.RadioButtonGroup(form, field)

Represents a radio button group.

Parameters:
property can_toggle_off

If radio buttons in this group are allowed to be togged off.

property options: collections.abc.Sequence[RadioButtonOption]

A list of all available options.

Return type:

collections.abc.Sequence[RadioButtonOption]

property selected: RadioButtonOption | None

The currently selected option.

Return type:

RadioButtonOption | None

property states: collections.abc.Sequence[pikepdf.Name]

List the possible on states of all component radio buttons in this group.

Return type:

collections.abc.Sequence[pikepdf.Name]

property value: pikepdf.Name | None

The value of the currently selected option.

Return type:

pikepdf.Name | None

class pikepdf.form.RadioButtonOption(group, annot_dict, index)

Represents a single radio button in a radio button group.

Parameters:
property checked: bool

Is this is the currently selected option?

Return type:

bool

property on_value: pikepdf.Name

The underlying value associated with this button’s “on” state.

Return type:

pikepdf.Name

select()

Mark this as the selected option.

property states: collections.abc.Sequence[pikepdf.Name]

List the possible states for this radio button.

Typically this will be /Off plus one additional arbitrary value representing the on state.

Return type:

collections.abc.Sequence[pikepdf.Name]

class pikepdf.form.PushbuttonField(form, field)

Represents a pushbutton field.

Pushbuttons retain no permanent state, so this class is merely a placeholder. It exposes no functionality.

Parameters:
class pikepdf.form.ChoiceField(form, field)

Represents a choice field.

Multiselect is not currently supported; multiselect fields will still only allow selecting a single value.

Parameters:
property allow_edit: bool

Does this field include an editable text box in addition to the dropdown?

The field must be a comboxbox; this option is not valid for list boxes.

Return type:

bool

property is_combobox: bool

Is this a combobox field? If false, this is instead a list box.

Return type:

bool

property is_multiselect: bool

Is this a multiselect field?

Multiselect fields are currently treated as single-selection fields. True multiselect is not yet supported, but this flag is presented for your information.

Return type:

bool

property options: collections.abc.Sequence[ChoiceFieldOption]

A list of all available options.

Return type:

collections.abc.Sequence[ChoiceFieldOption]

property selected: ChoiceFieldOption | None

The currently selected option, or None if no option is selected.

Return type:

ChoiceFieldOption | None

property spell_check_enabled: bool

Should spell-checking be enabled in this field?

This is only valid for fields that allow editing.

Return type:

bool

property value: str | None

The value of the currently selected option.

Return type:

str | None

class pikepdf.form.ChoiceFieldOption(field, opt, index)

Represents a single option for a choice field.

Parameters:
property display_value

The value that will be displayed on-screen to the user in a PDF reader.

property export_value

The value that will be used when exporting data from this form.

property is_hidden: bool

Is this option hidden?

Hidden options are still settable via code, but are not shown to users in PDF reader applications.

Return type:

bool

property is_preset: bool

Is this option one of the field’s preset options?

If false, this is a manually entered value typed by the user in an editable choice field.

Return type:

bool

select()

Set this option as the selected option.

property selected: bool

Is this the currently selected option?

Return type:

bool

class pikepdf.form.SignatureField(form, field)

Represents a signature field.

Signatures are not truly supported.

Parameters:
stamp_overlay(overlay, *, expand_rect=None)

Stamp an image over the top of a signature field.

This is not true support for PDF signatures. Rather, it is merely a utility for adding an image to the PDF at the location of a signature field.

This uses pikepdf.Page.add_overlay under the hood, see that method for additional usage information.

If the bounding box of the signature field is smaller than the “visual” signature area in the PDF, you may use the expand_rect parameter to increase the dimensions of the rectangle when stamping. This may be any of the following types:

  • A number, which will be added equally to all sides of the box

  • A sequence of two numbers, which will be added on the X and Y axis, respectively

  • A sequence of four numbers, which will be added to the left, bottom, right, and top sides respectively

Positive numbers will increase the size of the box, and negative numbers will decease it.

Parameters:

  • overlay (pikepdf.Object | pikepdf.Page)

  • expand_rect (int | float | decimal.Decimal | collections.abc.Sequence[int | float | decimal.Decimal] | None)

Return type:

pikepdf.Name

Generating Appearance Streams

Merely setting the values of form fields is not sufficient. It is also necessary to generate appearance streams for fields. These appearance streams define how the filled-out field should actually look when viewed in a PDF reader.

Generating appearance streams can be very complex. Both of the classes below have limited capacities, but should work for many use cases, and can be extended to meet your needs.

class pikepdf.form.AppearanceStreamGenerator(pdf, form)

Appearance stream generators are used to render forms.

They are used by the pikepdf.form.Form class to optionally generate appearance streams as forms are filled.

Parameters:
form: pikepdf.AcroForm
abstractmethod generate_choice(field)

Generate the appearance stream for a choice field.

Parameters:

field (pikepdf.AcroFormField)

abstractmethod generate_text(field)

Generate the appearance stream for a text field.

Parameters:

field (pikepdf.AcroFormField)

pdf: pikepdf.Pdf
class pikepdf.form.DefaultAppearanceStreamGenerator(pdf, form)

Basic appearance stream generator using QPDF’s default algorithm.

It is thus subject to all the same limitations.

Briefly summarized, these limitations are:

  • Cannot generate appearance streams using encodings other than ASCII, WinAnsi, or MacRoman

  • No support for multiline text

  • No support for auto-sized text

  • Does not respect quadding

Using this class will produce the same results as the following code:

form = Form(pdf, generate_appearances = None)
...
pdf.generate_appearances()

However, unlike the above, appearances will be generated on the fly as the form is filled out, rather than all at once at the end.

You may extend this class to customize appearance streams or add support for features you need.

Parameters:
generate_choice(field)

Generate the appearance stream for a choice field.

Parameters:

field (pikepdf.AcroFormField)

generate_text(field)

Generate the appearance stream for a text field.

Parameters:

field (pikepdf.AcroFormField)

class pikepdf.form.ExtendedAppearanceStreamGenerator(pdf, form)

Alternate appearance stream generator to address limitations of the default one.

Improved features include:

  • Supports multiline text fields, with caveats:

  • Word wrap does not take scaling factors (other than font size) into account

  • Spacing operators not taken into consideration either

  • Quadding is still ignored

  • Due to limitations in Firefox’s PDF viewer, the font and the line breaks will be incorrect when viewed in Firefox. PDFs filled by full-fat PDF readers, including Adobe Acrobat Reader, exhibit the same behavior when viewed in Firefox.

  • Supports combed text fields, with most of the same caveats as above

Otherwise, this implementation has most of the same limitations as the default implementation. Unlike the default implementation, this is implemented in Python rather than C++, so will also be less performant.

Parameters:
generate_text(field)

Generate the appearance stream for a text field.

Parameters:

field (pikepdf.AcroFormField)